From dbf2f9dd5237cb7353383d0a1bdf4881d04f2133 Mon Sep 17 00:00:00 2001 From: Sunmin Lee <134378502+sunm2n@users.noreply.github.com> Date: Thu, 27 Aug 2026 13:10:47 +0900 Subject: [PATCH 1/2] docs: document tag parameter for local cache backend Signed-off-by: Sunmin Lee <134378502+sunm2n@users.noreply.github.com> --- content/manuals/build/cache/backends/local.md | 25 ++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/content/manuals/build/cache/backends/local.md b/content/manuals/build/cache/backends/local.md index 69f32107c3d5..9170751d6c57 100644 --- a/content/manuals/build/cache/backends/local.md +++ b/content/manuals/build/cache/backends/local.md @@ -28,6 +28,7 @@ The following table describes the available CSV parameters that you can pass to |---------------------|--------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------| | `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. | | `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. | +| `tag` | `cache-to`,`cache-from` | String | `latest` | Tag of the cache manifest, see [cache versioning][4]. | | `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | | `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][1]. | | `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | @@ -47,10 +48,28 @@ build continues. ## Cache versioning - - This section describes how versioning works for caches on a local filesystem, -and how you can use the `digest` parameter to use older versions of cache. +and how you can use the `digest` and `tag` parameters to select which version of +the cache to use. + +Cache exports are annotated with a tag, which defaults to `latest`. Use the +`tag` parameter to scope exports, which lets you keep multiple cache versions 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 . +``` + +To import a specific version, pass the same tag to `--cache-from`: + +```console +$ docker buildx build --cache-from type=local,src=path/to/local/dir,tag=v1 . +``` + +If you specify `digest`, the `tag` parameter is ignored. Use `digest` to pin the +cache to an exact manifest, and `tag` when you want a stable name that you can +update over time. If you inspect the cache directory manually, you can see the resulting OCI image layout: From a342870f88e2dab9fae72079a40146fda7b1e71f Mon Sep 17 00:00:00 2001 From: Sunmin Lee <134378502+sunm2n@users.noreply.github.com> Date: Fri, 28 Aug 2026 13:48:44 +0900 Subject: [PATCH 2/2] docs: restructure local cache versioning section Rewrite the section around how tags, digests, and stored blobs relate, as suggested in review. Also corrects two errors in the existing text: - The digest import example used ref=, which fails with "local cache importer requires src". The parameter is src=. - The text said cache gets replaced on export by replacing index.json. Since moby/buildkit#3111, index.json merges: exporting a new tag keeps manifests referenced by other tags. Drops the moby/buildkit#1896 reference, which is closed as completed. Signed-off-by: Sunmin Lee <134378502+sunm2n@users.noreply.github.com> --- content/manuals/build/cache/backends/local.md | 61 ++++++------------- 1 file changed, 18 insertions(+), 43 deletions(-) diff --git a/content/manuals/build/cache/backends/local.md b/content/manuals/build/cache/backends/local.md index 9170751d6c57..577e94566867 100644 --- a/content/manuals/build/cache/backends/local.md +++ b/content/manuals/build/cache/backends/local.md @@ -48,66 +48,41 @@ build continues. ## Cache versioning -This section describes how versioning works for caches on a local filesystem, -and how you can use the `digest` and `tag` parameters to select which version of -the cache to use. +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. -Cache exports are annotated with a tag, which defaults to `latest`. Use the -`tag` parameter to scope exports, which lets you keep multiple cache versions in -the same directory: +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 . ``` -To import a specific version, pass the same tag to `--cache-from`: +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 . ``` -If you specify `digest`, the `tag` parameter is ignored. Use `digest` to pin the -cache to an exact manifest, and `tag` when you want a stable name that you can -update over time. - -If you inspect the cache directory manually, you can see the resulting OCI image -layout: +A digest identifies an exact cache manifest. BuildKit reports the digest of +each exported manifest in the build output. Use `digest` instead of `tag` when +you need a specific manifest: ```console -$ ls cache -blobs index.json ingest -$ cat cache/index.json | jq -{ - "schemaVersion": 2, - "manifests": [ - { - "mediaType": "application/vnd.oci.image.index.v1+json", - "digest": "sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707", - "size": 1560, - "annotations": { - "org.opencontainers.image.ref.name": "latest" - } - } - ] -} +$ docker buildx build \ + --cache-from type=local,src=path/to/local/dir,digest=sha256: . ``` -Like other cache types, local cache gets replaced on export, by replacing the -contents of the `index.json` file. However, previous caches will still be -available in the `blobs` directory. These old caches are addressable by digest, -and kept indefinitely. Therefore, the size of the local cache will continue to -grow (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896) -for more information). - -When importing cache using `--cache-from`, you can specify the `digest` parameter -to force loading an older version of the cache, for example: +If you specify both `digest` and `tag`, BuildKit uses `digest`. -```console -$ docker buildx build --push -t / \ - --cache-to type=local,dest=path/to/local/dir \ - --cache-from type=local,ref=path/to/local/dir,digest=sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707 . -``` +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. ## Further reading