From 4ce9ed5f54c90ac33b736eee11db59fbdd0e7dad Mon Sep 17 00:00:00 2001
From: Sunmin Lee <134378502+sunm2n@users.noreply.github.com>
Date: Fri, 28 Aug 2026 16:22:05 +0900
Subject: [PATCH] docs: document reset parameter for local cache backend

The local cache exporter accepts reset=true, which deletes blobs that no
tag in the cache directory references. Blobs referenced by other tags are
kept, and manifests that no tag references can no longer be imported by
digest.

Added in moby/buildkit#6612, which changes the client only. The gate is
therefore the Buildx version rather than the BuildKit daemon version:
Buildx v0.35.0 is the first release to vendor moby/buildkit v0.31.0.

Fixes #25959

Signed-off-by: Sunmin Lee <134378502+sunm2n@users.noreply.github.com>
---
 content/manuals/build/cache/backends/local.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/content/manuals/build/cache/backends/local.md b/content/manuals/build/cache/backends/local.md
index 577e94566867..aebfe8cbd877 100644
--- a/content/manuals/build/cache/backends/local.md
+++ b/content/manuals/build/cache/backends/local.md
@@ -37,6 +37,7 @@ The following table describes the available CSV parameters that you can pass to
 | `compression-level` | `cache-to`   | `0..22`                 |         | Compression level, see [cache compression][3].                                                                                  |
 | `force-compression` | `cache-to`   | `true`,`false`          | `false` | Forcibly apply compression, see [cache compression][3].                                                                         |
 | `ignore-error`      | `cache-to`   | Boolean                 | `false` | Ignore errors caused by failed cache exports.                                                                                   |
+| `reset`             | `cache-to`   | `true`,`false`          | `false` | Delete blobs that no tag references, see [cache versioning][4].                                                                 |
 
 [1]: _index.md#cache-mode
 [2]: _index.md#oci-media-types
@@ -84,6 +85,16 @@ 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.
 
+Buildx version 0.35.0 and later supports `reset=true` on export, which deletes
+blobs that no tag references:
+
+```console
+$ docker buildx build --cache-to type=local,dest=path/to/local/dir,reset=true .
+```
+
+Blobs that other tags reference are kept. Manifests that no tag references are
+deleted, so you can no longer import them by digest.
+
 ## Further reading
 
 For an introduction to caching see [Docker build cache](../_index.md).