docs: document tag parameter and restructure local cache versioning

[sunm2n]

Description

The tag parameter for the local cache backend was added in
moby/buildkit#3111 but was
never documented. The page also carried a FIXME comment waiting on that
PR, which has long since been released.

Changes:

• Add tag to the parameter table
• Document tag-based scoping in the "Cache versioning" section
• Remove the stale FIXME comment

Verified against client/solve.go and by running builds locally:

• Exports are annotated with org.opencontainers.image.ref.name,
  defaulting to latest
• Different tags coexist in the same directory as separate manifests
• --cache-from with a matching tag restores the cache on a fresh builder
• When digest is set, tag is ignored

Reviews

• Technical review
• Editorial review

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	a342870
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a911499e8158c0008977ccf
😎 Deploy Preview	https://deploy-preview-25943--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[dvdksn]

The tag documentation is technically correct, but adding it to the existing explanation leaves the section difficult to follow. Could we restructure the whole section around the relationship between tags, digests, and stored blobs? For example:

## Cache versioning

A local cache directory uses an OCI image layout. Its `index.json` file
associates tags with cache manifests, while the `blobs` directory stores the
manifest and cache data.

By default, BuildKit exports and imports the cache tagged `latest`. Use
different tags to keep multiple caches in the same directory:

```console
$ docker buildx build --cache-to type=local,dest=path/to/local/dir,tag=v1 .
$ docker buildx build --cache-to type=local,dest=path/to/local/dir,tag=v2 .
```

Exporting another cache with the same tag updates that tag to reference the new
manifest. Manifests referenced by other tags remain unchanged.

Import a cache by specifying its tag:

```console
$ docker buildx build --cache-from type=local,src=path/to/local/dir,tag=v1 .
```

A digest identifies an exact cache manifest. Use `digest` instead of `tag` when
you need a specific manifest:

```console
$ docker buildx build \
  --cache-from type=local,src=path/to/local/dir,digest=sha256:<DIGEST> .
```

If you specify both `digest` and `tag`, BuildKit uses `digest`.

By default, updating a tag doesn't delete the blobs used by its previous
manifest. The previous manifest remains available by digest, so the local cache
directory grows over time.

This would also remove the large index.json dump, which exposes the storage
format without helping readers decide whether to use a tag or digest. It also
fixes the existing ref=... typo by using the correct src=... parameter.

Generated by Codex

[sunm2n]

Restructured the section as suggested. I verified the behavior against BuildKit before rewriting, and the checks turned up two errors in the existing text that the restructure now fixes:

ref= isn't a typo — the command fails outright.

$ docker buildx build --cache-from type=local,ref=./cache,digest=sha256:... .
ERROR: failed to build: local cache importer requires src

"local cache gets replaced on export" is no longer accurate. Since moby/buildkit#3111, index.json merges rather than being replaced. Exporting tag=v2 into a directory that already holds tag=v1 leaves the v1 manifest in place, and re-exporting the same tag updates only that tag's digest:

$ docker buildx build --cache-to type=local,dest=./cache,tag=v1 .
$ docker buildx build --cache-to type=local,dest=./cache,tag=v2 .
$ jq -r '.manifests[].annotations."org.opencontainers.image.ref.name"' cache/index.json
v1
v2

I think this is what made the section hard to follow — it contradicted the tag behavior being documented directly above it.

I also dropped the moby/buildkit#1896 reference, since that issue is closed as completed.

One addition to your draft: the digest example had no way to obtain <DIGEST>, so I noted that BuildKit reports it in the build output (writing cache image manifest sha256:...). Happy to drop that sentence if you'd rather keep the section shorter.

Separately, moby/buildkit#6612 added a reset=true attribute to the local cache exporter that removes unreferenced blobs after export (shipped in BuildKit v0.31.0). It isn't documented anywhere in this repo. That's a different feature from this PR, so I plan to open a follow-up rather than expand the scope here — let me know if you'd prefer it folded in.

[dvdksn]

Thank you @sunm2n