# Shallow clones and registries for Terraform monorepo modules

> Each Git module source in a Terraform monorepo clones the whole repository; registries need not.

Engineering note by Oleksandr Ponomarov · 18 November 2026 · Topics: terraform, atlantis
Canonical: https://oponomarov.com/blog/posts/shallow-clones-and-registries-for-terraform-modules/

Terraform modules have to come from somewhere, and in a monorepo the most
natural somewhere is the monorepo itself. The modules live in a `modules/`
directory alongside the _stacks_ that use them, each stack being a directory
that Terraform plans and applies on its own. Each stack pins every module it
calls to a Git tag of that same repository:

```hcl
module "orders_db" {
  source = "github.com/acme/infra//modules/db?ref=db-v1.1.0"
  name   = "orders"
}
```

That arrangement has a lot going for it: a module and its callers can change
together in a single pull request, each stack can move to a new module version
on its own schedule, and there is no second repository to look after. What is
less obvious is what Terraform has to do to honor that `source` argument, and
how the cost of doing so grows with the repository. This post follows a
module source address down to the `git clone` it turns into, measures that
cost for a monorepo of more than 500 stacks, and projects where it is
heading. The monorepo is planned by [Atlantis](https://www.runatlantis.io/),
which runs `terraform plan` on every pull request. Then the post looks at two
ways to reduce that cost: shallow clones, which fetch only the tagged commit
and need one argument added to each source, and an internal module registry,
which is more work but changes what gets downloaded in the first place.

> [!NOTE] Where the numbers come from
>
> The measurements come from a production monorepo I work on. Figures are
> rounded, and names in the snippets are placeholders. An AI coding agent,
> Claude, ran the benchmarks, the analysis and the demo at my request, with
> [Terraform 1.15.8](https://github.com/hashicorp/terraform/tree/v1.15.8) and
> [go-getter v1.8.6](https://github.com/hashicorp/go-getter/tree/v1.8.6) on a
> laptop with about 1 MB/s to GitHub.

<dl class="surface-grid">
  <div>
    <dt>About 12 hours a month</dt>
    <dd>Spent cloning the whole repository for modules, at laptop speed (about 1 MB/s): about 40 GB a month, averaged over six months of real plans, and growing with the repository.</dd>
  </div>
  <div>
    <dt>About 3 hours with shallow clones</dt>
    <dd>Shallow clones fetch only the tagged commit, not the whole history. The cost rises toward 6 hours as stacks move to newer module tags.</dd>
  </div>
  <div>
    <dt>Minutes with a registry</dt>
    <dd>A registry can serve each module as a small archive, an estimated second or so to fetch, or 9 to 15 minutes a month. Projected, not yet measured.</dd>
  </div>
</dl>

## Terraform downloads packages, not modules

When Terraform reads a module source address like the one above, it splits it
into two parts at the `//`. The repository address before it, together with
the `?ref=` arguments after the path, names a _module package_: something
Terraform knows how to download as a single unit, such as a Git repository at
a particular revision or an archive file at a URL. The path after the `//` is
a location inside that package, telling Terraform where to find the module
once the package is on disk.

Terraform never downloads "a module". It downloads a package and then looks
inside it, so for a Git source, asking for `modules/db` at `db-v1.1.0` really
means asking for the entire `infra` repository at that tag.

The download itself is handled by go-getter, the library Terraform uses to
fetch module packages, and for Git sources go-getter makes no attempt to be
economical. Unless the source address includes a `depth` argument, it runs a
plain `git clone` of the remote, with every branch, every tag and every
commit, and only then checks out the requested tag. The default is right
there in
[`get_git.go`](https://github.com/hashicorp/go-getter/blob/d23bff48fb87c956bb507a03d35a63ee45470e34/get_git.go#L66-L86):
`depth := 0 // 0 means "don't use shallow clone"`.

Terraform does avoid downloading the same package twice. Within a single
`terraform init`, two module calls that refer to the same package cause only
one download, and the second call
[gets a copy](https://github.com/hashicorp/terraform/blob/v1.15.8/internal/getmodules/getter.go#L122-L133)
of the first one's directory. But that reuse is keyed on the package address,
so two calls at different tags of the same repository are two separate full
clones, and nothing at all is shared between one working directory and the
next.

## Seeing it on a small scale

It's easier to get a feel for this with something small, so here is a
throwaway repository built to show the effect: two tiny modules, 125 commits,
and an 18 MB file that was committed once and later replaced with a different
one. One stack calls both modules, each at its own tag, through `file://`
Git sources, because Git ignores `--depth` for plain local paths and that
will matter in a moment. `<dir>` stands for the demo's directory:

```hcl title="stacks/full/main.tf"
module "orders_db" {
  source = "git::file://<dir>/infra//modules/db?ref=db-v1.1.0"
  name   = "orders"
}

module "orders_secret" {
  source = "git::file://<dir>/infra//modules/secret?ref=secret-v1.0.0"
  path   = "orders/db"
}
```

Running `terraform get`, which performs just the module-download part of
`terraform init`, gives:

```text
$ terraform get
Downloading git::file://<dir>/infra?ref=secret-v1.0.0 for orders_secret...
- orders_secret in .terraform/modules/orders_secret/modules/secret
Downloading git::file://<dir>/infra?ref=db-v1.1.0 for orders_db...
- orders_db in .terraform/modules/orders_db/modules/db
$ du -sh .terraform/modules
 86M	.terraform/modules
```

Notice where each module ended up: `.terraform/modules/orders_db/modules/db`.
The directory `orders_db` is a complete clone of the repository, history and
all, and the module Terraform actually wanted is one small directory inside
it. The two modules amount to a few hundred bytes of HCL, and they arrived
inside 86 MB of clones, about 70 MB of it Git history, because both versions
of that large file are still in the history even though only one of them is
in the tree.

## How often Atlantis pays for it

A single clone of a single repository isn't much to worry about. What makes it
add up is how often it happens, and in a repository planned by Atlantis that
is quite often.

Atlantis plans each pull request in its own working directory and keeps that
directory from one plan to the next, including `.terraform/`, where
Terraform keeps the modules it has installed. Terraform skips any module
that is already installed there, so in practice each stack downloads its
modules once per pull request, on its first plan. This post calls that first
plan a _cold init_. (If the stacks' dependency lock files,
`.terraform.lock.hcl`, aren't committed, Atlantis runs `terraform init
-upgrade`, which reinstalls every module, and then every plan is a cold
init. The numbers below assume Atlantis doesn't do that.)

The repository in question has about 550 stacks, and about 300 of them call
its own modules through Git sources. A full clone is about 80 MB. Over six
months, about 70 people opened pull requests against it, and with bot
updates that came to around 160 pull requests in a typical month. Atlantis
posts every plan as a comment on its pull request, which makes those
comments a convenient record. Leaving out one unusually large pull request,
they add up to about 600 plan runs and 1,450 stack inits a month. About 560
of those inits were cold. Some needed no clone at all, because their stack
calls no Git modules, and others needed one for each tag their stack pins;
together they cloned the repository about 580 times.

That works out to about 40 GB of Git data a month, spent entirely on fetching
modules. To turn that into time, 18 of the `git clone` commands that go-getter
runs, from small shallow clones up to the full repository, were timed on the
laptop. A straight line fits them reasonably well, at about 3.5 seconds per
clone plus about a second per megabyte, which puts a full clone of today's
repository at around 80 seconds. Costing each month at the size the
repository had then, a month of cold inits averages about 12 hours of
cloning. Over half a year that is about 240 GB and 73 hours.

Every hour figure in this post is at the laptop's speed. The Atlantis server
very likely has a faster connection, so its hours will be fewer. The bytes,
though, are the same wherever they're downloaded, and so is the shape of the
problem: each person waiting on a cold init is waiting for the whole repository,
once per tag.

## Shallow clones

The cheapest thing to try is the `depth` argument that go-getter already
checks for. Adding `&depth=1` to every source turns each clone into
`git clone --depth 1 --branch <tag>`, which fetches only the tagged commit and
none of the history behind it. Here is the same demo stack with that one
change:

```text
$ terraform get
Downloading git::file://<dir>/infra?ref=db-v1.1.0&depth=1 for orders_db...
- orders_db in .terraform/modules/orders_db/modules/db
Downloading git::file://<dir>/infra?ref=secret-v1.0.0&depth=1 for orders_secret...
- orders_secret in .terraform/modules/orders_secret/modules/secret
$ du -sh .terraform/modules
 35M	.terraform/modules
```

The history is gone, but 35 MB remains, and almost all of it is the current
version of that large file, counted once in the shallow clone's `.git` and
once in the checkout. A shallow clone still downloads the whole tree at the
tag: not just the module you asked for, but every other module and every
stack in the repository as they were at that commit.

In the real repository that tree is about 31 MB at a recent tag, most of it
images. Replaying the same six months of plans with `depth=1`
on every source gives about 9 GB and 3 hours a month, or 55 GB and 19 hours
over half a year. The modules Terraform installs are identical either way;
only the history is missing.

The ref has to be a tag or a branch rather than a commit, because go-getter
passes it to `git clone --branch`, which doesn't accept commit IDs. And
because every source string changes, every stack reinstalls its modules and
gets planned once, so it's kinder to Atlantis, and to reviewers, to roll it
out a group of stacks at a time.

Shallow clones are worth doing on their own. But they reduce the cost
without changing its shape: every module fetch still downloads the repository
as it was at that tag, and that tree keeps growing.

## Letting a registry decide what to download

Terraform has a second kind of module source that works quite differently. A
_registry source_ names a module and leaves the version to a separate
argument:

```hcl title="stacks/registry/main.tf"
module "orders_db" {
  source  = "registry.example.com/acme/db/aws"
  version = "1.1.0"
  name    = "orders"
}

module "orders_secret" {
  source  = "registry.example.com/acme/secret/aws"
  version = "1.0.0"
  path    = "orders/db"
}
```

For a source like this, Terraform doesn't download anything directly. It asks
the registry which versions of the module exist, picks the one that matches
`version`, and then asks the registry where to get it. The registry answers
with an `X-Terraform-Get` header containing an ordinary source address, which
Terraform then hands to go-getter just as it would any other.

The interesting part is that the registry gets to choose that address. The
public Terraform Registry, for example, points back at Git:

```shell
$ m=terraform-aws-modules/vpc/aws/6.0.1
$ curl -s -o /dev/null -D - \
    "https://registry.terraform.io/v1/modules/$m/download" \
    | grep -i -e '^HTTP' -e '^x-terraform-get'
HTTP/2 204
x-terraform-get: git::https://github.com/terraform-aws-modules/terraform-aws-vpc?ref=a0307d4d1807de60b3868b96ef1b369808289157
```

That works well enough for public modules, because each one lives in a
repository of its own. A registry that did the same for a monorepo would
change the syntax of every `source` and nothing else. What a monorepo needs is
a registry that stores each module version as its own archive, so that the
package Terraform downloads is the module and nothing more.

That is exactly what an internal registry such as
[boring-registry](https://github.com/boring-registry/boring-registry) does.
Publishing a module with `boring-registry upload module` packs the module's
directory into a `tar.gz` in object storage, and when Terraform asks where to
download a version, the registry answers with a
[pre-signed URL](https://github.com/boring-registry/boring-registry/blob/4a35013d14de5f1e2d256892b57509f695a07751/pkg/storage/s3.go#L70-L93)
for that one file. The demo has a small stand-in registry that serves
archives the same way, and pointing the stack above at it gives:

```text
$ terraform get
Downloading registry.example.com/acme/secret/aws 1.0.0 for orders_secret...
- orders_secret in .terraform/modules/orders_secret
Downloading registry.example.com/acme/db/aws 1.1.0 for orders_db...
- orders_db in .terraform/modules/orders_db
$ du -sh .terraform/modules
 12K	.terraform/modules
```

Each module now lands directly in its own directory, with no `modules/db`
path inside a clone and no `.git` directory anywhere.

Those archives are small. Built for every tag the real stacks used over the
six months, they come out at a median of about 6 KB. There is no registry in
front of this repository to time, so the fetch itself was estimated from the
same mechanism: downloading a small public module as an HTTPS archive took
about a second end to end with `terraform get`, and the two registry lookups
Terraform makes for each module took about 0.2 to 0.5 seconds between them
against the public registry.
Put next to the clones, the difference is hard to miss:

<figure class="concept-diagram" data-concept-diagram>
  <div class="diagram-exhibit" data-exhibit>
    <div class="diagram-exhibit-label">TIME SPENT FETCHING MODULES</div>
<svg viewBox="0 0 680 304" role="img" aria-label="Time spent fetching modules, full clone against shallow clone against a registry archive. One module fetch: full clone 77 s; shallow clone 32 s, recent tag; registry archive about 1 s, estimated. A month of plans, six-month average: full clone 12 hours; shallow clone 3 hours; registry archive 9 to 15 min, projected. Clone times measured on a laptop at about 1 MB/s; the registry fetch is estimated from a public archive download and registry lookups, and the registry month is a projection.">
  <text x="150.0" y="22.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="start" font-weight="600">ONE MODULE FETCH</text>
  <line x1="150.0" y1="34.0" x2="150.0" y2="118.0" stroke="var(--color-border)" stroke-width="1" />
  <line x1="150.0" y1="118.0" x2="150.0" y2="123.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="150.0" y="136.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">0 s</text>
  <line x1="245.0" y1="118.0" x2="245.0" y2="123.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="245.0" y="136.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">30</text>
  <line x1="340.0" y1="118.0" x2="340.0" y2="123.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="340.0" y="136.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">60</text>
  <line x1="435.0" y1="118.0" x2="435.0" y2="123.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="435.0" y="136.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">90</text>
  <line x1="530.0" y1="118.0" x2="530.0" y2="123.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="530.0" y="136.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">120 s</text>
  <text x="136.0" y="52.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="end">full clone</text>
  <path d="M150.0,41.0 H391.3 Q395.3,41.0 395.3,45.0 V51.0 Q395.3,55.0 391.3,55.0 H150.0 Z" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <text x="405.3" y="52.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">77 s</text>
  <text x="136.0" y="80.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="end">shallow clone</text>
  <path d="M150.0,69.0 H247.4 Q251.4,69.0 251.4,73.0 V79.0 Q251.4,83.0 247.4,83.0 H150.0 Z" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <text x="261.4" y="80.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">32 s, recent tag</text>
  <text x="136.0" y="108.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="end">registry archive</text>
  <path d="M150.0,97.0 H150.0 Q153.2,97.0 153.2,100.2 V107.8 Q153.2,111.0 150.0,111.0 H150.0 Z" fill="var(--color-text)" fill-opacity="1" stroke="var(--color-text)" stroke-width="1.5" />
  <text x="163.2" y="108.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">about 1 s, estimated</text>
  <text x="150.0" y="170.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="start" font-weight="600">A MONTH OF PLANS, SIX-MONTH AVERAGE</text>
  <line x1="150.0" y1="182.0" x2="150.0" y2="266.0" stroke="var(--color-border)" stroke-width="1" />
  <line x1="150.0" y1="266.0" x2="150.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="150.0" y="284.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">0 h</text>
  <line x1="245.0" y1="266.0" x2="245.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="245.0" y="284.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">4</text>
  <line x1="340.0" y1="266.0" x2="340.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="340.0" y="284.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">8</text>
  <line x1="435.0" y1="266.0" x2="435.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="435.0" y="284.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">12</text>
  <line x1="530.0" y1="266.0" x2="530.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="530.0" y="284.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">16 h</text>
  <text x="136.0" y="200.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="end">full clone</text>
  <path d="M150.0,189.0 H434.8 Q438.8,189.0 438.8,193.0 V199.0 Q438.8,203.0 434.8,203.0 H150.0 Z" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <text x="448.8" y="200.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">12 hours</text>
  <text x="136.0" y="228.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="end">shallow clone</text>
  <path d="M150.0,217.0 H222.0 Q226.0,217.0 226.0,221.0 V227.0 Q226.0,231.0 222.0,231.0 H150.0 Z" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <text x="236.0" y="228.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">3 hours</text>
  <text x="136.0" y="256.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="end">registry archive</text>
  <path d="M150.0,245.0 H152.1 Q156.1,245.0 156.1,249.0 V255.0 Q156.1,259.0 152.1,259.0 H150.0 Z" fill="var(--color-text)" fill-opacity="1" stroke="var(--color-text)" stroke-width="1.5" />
  <text x="166.1" y="256.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">9 to 15 min, projected</text>
</svg>
  </div>
  <figcaption class="exhibit-caption">One-fetch times are medians of three runs on a laptop at about 1 MB/s. The shallow clone is of a recent tag; the month uses each stack's own tags, many of them older and smaller. The registry fetch is estimated from a public archive download plus both registry lookups, and its month is about 580 fetches at that rate.</figcaption>
</figure>

A cold init that needs one module becomes a handful of small HTTPS requests
instead of a minute or so of cloning, and a month of them takes nine to
fifteen minutes instead of hours.

## Looking a year ahead

All of the numbers so far describe the last six months. The more useful
question is where those numbers are going, and the repository's own history
gives a reasonable way to estimate that.

Measuring the size of a full clone every six months since the repository began
shows a pattern that's probably familiar to anyone who has looked after a
long-lived monorepo. There is steady growth from ordinary commits, and then
there are steps, each one a large binary file being committed. Git never
forgets a file once it is committed, so
every step is permanent for full clones, even after the file is shrunk or
deleted. Shallow clones of the latest commit see the steps too, but only for
as long as the file stays in the tree:

<figure class="concept-diagram" data-concept-diagram>
  <div class="diagram-exhibit" data-exhibit>
    <div class="diagram-exhibit-label">HOW BIG A CLONE IS, OVER TIME</div>
<svg viewBox="0 0 680 300" role="img" aria-label="Size of a full clone and of a shallow clone of the main branch, measured every six months from 2021 to today, rounded to whole megabytes, and projected for a year at the average growth since late 2024. Full clone: under 1 MB in 2021, 11 MB in mid-2024, 78 MB today, about 100 MB in a year. Shallow clone: 31 MB today, about 35 MB in a year. The steps are large binary files being committed.">
  <line x1="56.0" y1="266.0" x2="560.0" y2="266.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="48.0" y="270.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">0</text>
  <line x1="56.0" y1="214.6" x2="560.0" y2="214.6" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="218.6" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">25 MB</text>
  <line x1="56.0" y1="163.3" x2="560.0" y2="163.3" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="167.3" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">50 MB</text>
  <line x1="56.0" y1="111.9" x2="560.0" y2="111.9" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="115.9" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">75 MB</text>
  <line x1="56.0" y1="60.5" x2="560.0" y2="60.5" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="64.5" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">100 MB</text>
  <line x1="56.0" y1="266.0" x2="56.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="56.0" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2021</text>
  <line x1="129.3" y1="266.0" x2="129.3" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="129.3" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2022</text>
  <line x1="202.6" y1="266.0" x2="202.6" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="202.6" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2023</text>
  <line x1="276.0" y1="266.0" x2="276.0" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="276.0" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2024</text>
  <line x1="349.5" y1="266.0" x2="349.5" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="349.5" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2025</text>
  <line x1="422.8" y1="266.0" x2="422.8" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="422.8" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2026</text>
  <line x1="496.1" y1="266.0" x2="496.1" y2="271.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="496.1" y="286.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">2027</text>
  <line x1="486.7" y1="40.0" x2="486.7" y2="266.0" stroke="var(--color-text-muted)" stroke-width="1" stroke-dasharray="2 3" />
  <text x="480.7" y="50.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">today</text>
  <text x="492.7" y="50.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="start">projected</text>
  <polyline points="56.0,266.0 92.4,266.0 129.3,263.9 165.7,261.9 202.6,257.8 239.0,255.7 276.0,249.6 312.5,243.4 349.5,194.1 385.8,167.4 422.8,161.2 459.2,116.0 486.7,105.7" fill="none" stroke="var(--color-text-subtle)" stroke-width="2" stroke-linejoin="round" />
  <polyline points="486.7,105.7 560.0,62.6" fill="none" stroke="var(--color-text-subtle)" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 5" />
  <circle cx="56.0" cy="266.0" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="92.4" cy="266.0" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="129.3" cy="263.9" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="165.7" cy="261.9" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="202.6" cy="257.8" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="239.0" cy="255.7" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="276.0" cy="249.6" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="312.5" cy="243.4" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="349.5" cy="194.1" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="385.8" cy="167.4" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="422.8" cy="161.2" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="459.2" cy="116.0" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <circle cx="486.7" cy="105.7" r="3.5" fill="var(--color-text-subtle)" fill-opacity="0.4" stroke="var(--color-text-subtle)" stroke-width="1.5" />
  <text x="570.0" y="66.5" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">about 100 MB</text>
  <polyline points="56.0,266.0 92.4,266.0 129.3,263.9 165.7,263.9 202.6,263.9 239.0,261.9 276.0,261.9 312.5,259.8 349.5,216.7 385.8,198.2 422.8,196.1 459.2,159.2 486.7,202.3" fill="none" stroke="var(--color-accent)" stroke-width="2" stroke-linejoin="round" />
  <polyline points="486.7,202.3 560.0,194.1" fill="none" stroke="var(--color-accent)" stroke-width="2" stroke-linejoin="round" stroke-dasharray="6 5" />
  <circle cx="56.0" cy="266.0" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="92.4" cy="266.0" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="129.3" cy="263.9" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="165.7" cy="263.9" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="202.6" cy="263.9" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="239.0" cy="261.9" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="276.0" cy="261.9" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="312.5" cy="259.8" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="349.5" cy="216.7" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="385.8" cy="198.2" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="422.8" cy="196.1" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="459.2" cy="159.2" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <circle cx="486.7" cy="202.3" r="3.5" fill="var(--color-accent)" fill-opacity="1" stroke="var(--color-accent)" stroke-width="1.5" />
  <text x="570.0" y="198.4" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">about 35 MB</text>
  <line x1="64.0" y1="14.0" x2="86.0" y2="14.0" stroke="var(--color-text-subtle)" stroke-width="2.5" /><text x="94.0" y="18.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="start">full clone</text>
  <line x1="216.0" y1="14.0" x2="238.0" y2="14.0" stroke="var(--color-accent)" stroke-width="2.5" /><text x="246.0" y="18.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="start">shallow clone of the latest commit</text>
</svg>
  </div>
  <figcaption class="exhibit-caption">Measured every six months from the repository's history, rounded to the nearest MB; dashed lines continue the average growth since late 2024 for one more year.</figcaption>
</figure>

Since late 2024 a full clone has grown by about 1.7 MB a month on average,
steps included. If that continues, it reaches about 100 MB a year from now,
or anywhere from about 90 to 105 MB if the average is taken over a longer or
shorter stretch of history. Feeding that growth into the same timing line,
with plan activity held at the six-month average, gives a forecast for the
time spent cloning:

<figure class="concept-diagram" data-concept-diagram>
  <div class="diagram-exhibit" data-exhibit>
    <div class="diagram-exhibit-label">PROJECTED CLONE TIME PER MONTH</div>
<svg viewBox="0 0 680 290" role="img" aria-label="Projected hours of module cloning per month for the next twelve months, with plan activity held at the six-month average. Full clone: 14 hours a month today, 17 in a year, about 185 hours over the year. Shallow clone: 3 to 6 hours a month, about 40 to 75 hours over the year, depending on whether stacks stay on their current tags or move to the newest. Registry: about 12 minutes a month.">
  <line x1="56.0" y1="256.0" x2="530.0" y2="256.0" stroke="var(--color-border)" stroke-width="1" />
  <text x="48.0" y="260.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">0</text>
  <line x1="56.0" y1="202.0" x2="530.0" y2="202.0" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="206.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">6 h</text>
  <line x1="56.0" y1="148.0" x2="530.0" y2="148.0" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="152.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">12 h</text>
  <line x1="56.0" y1="94.0" x2="530.0" y2="94.0" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="98.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">18 h</text>
  <line x1="56.0" y1="40.0" x2="530.0" y2="40.0" stroke="var(--color-border-subtle)" stroke-width="1" />
  <text x="48.0" y="44.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="end">24 h</text>
  <text x="56.0" y="276.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">today</text>
  <text x="174.5" y="276.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">+3 months</text>
  <text x="293.0" y="276.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">+6</text>
  <text x="411.5" y="276.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">+9</text>
  <text x="530.0" y="276.0" font-family="var(--font-mono)" font-size="12" fill="var(--color-text-muted)" text-anchor="middle">+12</text>
  <polygon points="56.0,203.8 95.5,203.4 135.0,203.0 174.5,202.6 214.0,202.1 253.5,201.7 293.0,201.3 332.5,200.9 372.0,200.4 411.5,200.0 451.0,199.6 490.5,199.2 530.0,198.8 530.0,227.2 490.5,227.2 451.0,227.2 411.5,227.2 372.0,227.2 332.5,227.2 293.0,227.2 253.5,227.2 214.0,227.2 174.5,227.2 135.0,227.2 95.5,227.2 56.0,227.2" fill="var(--color-accent)" fill-opacity="0.18" stroke="none" />
  <polyline points="56.0,227.2 95.5,227.2 135.0,227.2 174.5,227.2 214.0,227.2 253.5,227.2 293.0,227.2 332.5,227.2 372.0,227.2 411.5,227.2 451.0,227.2 490.5,227.2 530.0,227.2" fill="none" stroke="var(--color-accent)" stroke-width="2" stroke-linejoin="round" />
  <polyline points="56.0,203.8 95.5,203.4 135.0,203.0 174.5,202.6 214.0,202.1 253.5,201.7 293.0,201.3 332.5,200.9 372.0,200.4 411.5,200.0 451.0,199.6 490.5,199.2 530.0,198.8" fill="none" stroke="var(--color-accent)" stroke-width="2" stroke-linejoin="round" />
  <polyline points="56.0,133.9 95.5,131.3 135.0,128.7 174.5,126.1 214.0,123.5 253.5,120.9 293.0,118.3 332.5,115.7 372.0,113.1 411.5,110.5 451.0,107.9 490.5,105.3 530.0,102.7" fill="none" stroke="var(--color-text-subtle)" stroke-width="2.5" stroke-linejoin="round" />
  <polyline points="56.0,254.2 95.5,254.2 135.0,254.2 174.5,254.2 214.0,254.2 253.5,254.2 293.0,254.2 332.5,254.2 372.0,254.2 411.5,254.2 451.0,254.2 490.5,254.2 530.0,254.2" fill="none" stroke="var(--color-text)" stroke-width="1.5" stroke-linejoin="round" />
  <text x="540.0" y="106.7" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">full: 17 h</text>
  <text x="540.0" y="202.8" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">newest tags: 6 h</text>
  <text x="540.0" y="231.2" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">current tags: 3 h</text>
  <text x="540.0" y="258.2" font-family="var(--font-mono)" font-size="12" fill="var(--color-text)" text-anchor="start">registry: 12 min</text>
  <line x1="64.0" y1="14.0" x2="86.0" y2="14.0" stroke="var(--color-text-subtle)" stroke-width="2.5" /><text x="94.0" y="18.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="start">full clone</text>
  <rect x="191.0" y="9.0" width="22" height="10" fill="var(--color-accent)" fill-opacity="0.18" stroke="var(--color-accent)" stroke-width="1.5" /><text x="221.0" y="18.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="start">shallow clone</text>
  <line x1="346.0" y1="14.0" x2="368.0" y2="14.0" stroke="var(--color-text)" stroke-width="2.5" /><text x="376.0" y="18.0" font-family="var(--font-body)" font-size="13" fill="var(--color-text)" text-anchor="start">registry</text>
</svg>
  </div>
  <figcaption class="exhibit-caption">At laptop speed, with plan activity held at the six-month average. The shallow-clone band runs from every stack staying on its current tags to every stack on the newest tag.</figcaption>
</figure>

At today's repository size, a month of cold inits costs about 14 hours of full
clones, a little more than the six-month average because the repository is
bigger now than it was in the spring. A year from now it would be about 17
hours a month, and the year in between would add up to roughly 185 hours.

Shallow clones get a band rather than a line, because their cost depends on
which tags the stacks pin, and a tag never changes. Many stacks still pin
older tags, whose trees are small, so the average shallow clone today is
about 16 MB and a month costs about 3 hours. A stack that stays where it is
costs the same next year; that's the bottom of the band. A stack that moves
to a newer tag, which is the whole point of releasing modules, inherits the
larger tree, and if every stack were on the newest tag a month would cost
about 6 hours; that's the top. Over the coming year, shallow clones land
somewhere between about 40 and 75 hours, depending on how quickly stacks
move.

The registry line stays flat by construction, because a module archive
contains one module and doesn't grow when the rest of the repository does.
At a second or so per module, the whole year comes to about two and a half
hours.

These are projections, and simple ones. They assume the repository keeps
growing as it has, and that plan activity stays at the six-month average.
Neither assumption will hold exactly, but together they show which way each
option is heading.

## What a registry asks of you

None of this makes a registry free. Every module version has to be published, so
the release process that cuts module tags today needs an upload step as well,
and that step has to be reliable, because a stack can't use a version that was
tagged but never uploaded. Modules also have to be able to stand on their own. A
module that calls a sibling module with `source = "../secret"` works from a Git
clone, because the sibling happens to be on disk next to it, but an archive
contains only the one module, and Terraform stops with "Local module path
escapes module package". Those calls have to become registry sources too.

There is also a new piece of infrastructure in the path of every plan. If
the registry requires authentication, Terraform and tools such as Renovate
need credentials for it, and if it is down, cold inits fail, much as they do
today when GitHub can't be reached. Those are real costs, but they are the
ordinary costs of running any internal service, and they don't grow with the
repository.

Finally, the registry numbers in this post are projections. None of this
repository's modules has been served from a registry. The minutes above come
from fetch times estimated with a public archive and public registry lookups,
multiplied by the number of fetches replayed from six months of plans, not
from a migration that has actually happened.

## Where to from here?

The root of all this is a small detail in how Terraform treats module
sources: it downloads packages, not modules, and for a Git source the package
is the whole repository. In a small repository that detail never matters. In
a busy monorepo of a few hundred stacks it adds up to tens of gigabytes a
month, which at laptop speed is hours of cloning. And because Git keeps
everything it has ever been given, that number only goes one way.

Shallow clones need one argument added to each source, take away between half
and three quarters of the cost, and are cheap enough to do first. But they still
download the repository's tree, so what they leave behind grows with that tree
and rises as stacks move to newer tags. An internal registry that serves each
module as its own archive changes what a package is, and with it the cost of a
cold init, from a clone of everything to a download of just the module that was
asked for. For a monorepo that expects to keep growing, I think that's the
better place to end up.
