Skip to content

Commit d873cae

Browse files
tonistiigitonistiigi
authored
Merge pull request #3392 from crazy-max/docs-du-filter
docs: list available filters for du and prune commands
2 parents 4df89d8 + ebe66a8 commit d873cae

File tree

3 files changed

+93
-24
lines changed

3 files changed

+93
-24
lines changed

‎commands/prune.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ func pruneCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
176176

177177
flags := cmd.Flags()
178178
flags.BoolVarP(&options.all, "all", "a", false, "Include internal/frontend images")
179-
flags.Var(&options.filter, "filter", `Provide filter values (e.g., "until=24h")`)
179+
flags.Var(&options.filter, "filter", `Provide filter values`)
180180
flags.Var(&options.reservedSpace, "reserved-space", "Amount of disk space always allowed to keep for cache")
181181
flags.Var(&options.minFreeSpace, "min-free-space", "Target amount of free disk space after pruning")
182182
flags.Var(&options.maxUsedSpace, "max-used-space", "Maximum amount of disk space allowed to keep for cache")

‎docs/reference/buildx_du.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Disk usage
1313
|:------------------------|:---------|:--------|:-----------------------------------------|
1414
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
1515
| `-D`, `--debug` | `bool` | | Enable debug logging |
16-
| `--filter` | `filter` | | Provide filter values |
16+
| [`--filter`](#filter) | `filter` | | Provide filter values |
1717
| [`--format`](#format) | `string` | | Format the output |
1818
| [`--verbose`](#verbose) | `bool` | | Shorthand for `--format=pretty` |
1919

@@ -62,6 +62,10 @@ The asterisks (\*) in the default output format indicate the following:
6262
If you prune such a record then you will lose build cache but only metadata
6363
will be deleted as the image still needs to actual storage layers.
6464

65+
### <a name="filter"></a> Provide filter values (--filter)
66+
67+
Same as [`buildx prune --filter`](buildx_prune.md#filter).
68+
6569
### <a name="format"></a> Format the output (--format)
6670

6771
The formatting options (`--format`) pretty-prints usage information output

‎docs/reference/buildx_prune.md‎

Lines changed: 87 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,17 @@ Remove build cache
99

1010
### Options
1111

12-
| Name | Type | Default | Description |
13-
|:------------------------|:---------|:--------|:-------------------------------------------------------|
14-
| `-a`, `--all` | `bool` | | Include internal/frontend images |
15-
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
16-
| `-D`, `--debug` | `bool` | | Enable debug logging |
17-
| `--filter` | `filter` | | Provide filter values (e.g., `until=24h`) |
18-
| `-f`, `--force` | `bool` | | Do not prompt for confirmation |
19-
| `--max-used-space` | `bytes` | `0` | Maximum amount of disk space allowed to keep for cache |
20-
| `--min-free-space` | `bytes` | `0` | Target amount of free disk space after pruning |
21-
| `--reserved-space` | `bytes` | `0` | Amount of disk space always allowed to keep for cache |
22-
| `--verbose` | `bool` | | Provide a more verbose output |
12+
| Name | Type | Default | Description |
13+
|:--------------------------------------|:---------|:--------|:-------------------------------------------------------|
14+
| [`-a`](#all), [`--all`](#all) | `bool` | | Include internal/frontend images |
15+
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
16+
| `-D`, `--debug` | `bool` | | Enable debug logging |
17+
| [`--filter`](#filter) | `filter` | | Provide filter values |
18+
| `-f`, `--force` | `bool` | | Do not prompt for confirmation |
19+
| [`--max-used-space`](#max-used-space) | `bytes` | `0` | Maximum amount of disk space allowed to keep for cache |
20+
| [`--min-free-space`](#min-free-space) | `bytes` | `0` | Target amount of free disk space after pruning |
21+
| [`--reserved-space`](#reserved-space) | `bytes` | `0` | Amount of disk space always allowed to keep for cache |
22+
| `--verbose` | `bool` | | Provide a more verbose output |
2323

2424

2525
<!---MARKER_GEN_END-->
@@ -28,23 +28,88 @@ Remove build cache
2828

2929
Clears the build cache of the selected builder.
3030

31-
You can finely control what cache data is kept using:
31+
## Examples
32+
33+
### <a name="all"></a> Include internal/frontend images (--all)
34+
35+
The `--all` flag to allow clearing internal helper images and frontend images
36+
set using the `#syntax=` directive or the `BUILDKIT_SYNTAX` build argument.
37+
38+
### <a name="filter"></a> Provide filter values (--filter)
39+
40+
You can finely control which cache records to delete using the `--filter` flag.
41+
42+
The filter format is in the form of `<key><op><value>`, known as selectors. All
43+
selectors must match the target object for the filter to be true. We define the
44+
operators `=` for equality, `!=` for not equal and `~=` for a regular
45+
expression.
46+
47+
Valid filter keys are:
48+
- `until` flag to keep records that have been used in the last duration time.
49+
Value is a duration string, e.g. `24h` or `2h30m`, with allowable units of
50+
`(h)ours`, `(m)inutes` and `(s)econds`.
51+
- `id` flag to target a specific image ID.
52+
- `parents` flag to target records that are parents of the
53+
specified image ID. Multiple parent IDs are separated by a semicolon (`;`).
54+
- `description` flag to target records whose description is the specified
55+
substring.
56+
- `inuse` flag to target records that are actively in use and therefore not
57+
reclaimable.
58+
- `mutable` flag to target records that are mutable.
59+
- `immutable` flag to target records that are immutable.
60+
- `shared` flag to target records that are shared with other resources,
61+
typically images.
62+
- `private` flag to target records that are not shared.
63+
- `type` flag to target records by type. Valid types are:
64+
- `internal`
65+
- `frontend`
66+
- `source.local`
67+
- `source.git.checkout`
68+
- `exec.cachemount`
69+
- `regular`
70+
71+
Examples:
72+
73+
```console
74+
docker buildx prune --filter "until=24h"
75+
docker buildx prune --filter "description~=golang"
76+
docker buildx prune --filter "parents=dpetmoi6n0yqanxjqrbnofz9n;kgoj0q6g57i35gdyrv546alz7"
77+
docker buildx prune --filter "type=source.local"
78+
docker buildx prune --filter "type!=exec.cachemount"
79+
```
3280

33-
- The `--filter=until=<duration>` flag to keep images that have been used in
34-
the last `<duration>` time.
81+
> [!NOTE]
82+
> Multiple `--filter` flags are ANDed together.
3583
36-
`<duration>` is a duration string, e.g. `24h` or `2h30m`, with allowable
37-
units of `(h)ours`, `(m)inutes` and `(s)econds`.
84+
### <a name="max-used-space"></a> Maximum amount of disk space allowed to keep for cache (--max-used-space)
3885

39-
- The `--keep-storage=<size>` flag to keep `<size>` bytes of data in the cache.
86+
The `--max-used-space` flag allows setting a maximum amount of disk space
87+
that the build cache can use. If the cache is using more disk space than this
88+
value, the least recently used cache records are deleted until the total
89+
used space is less than or equal to the specified value.
4090

41-
`<size>` is a human-readable memory string, e.g. `128mb`, `2gb`, etc. Units
42-
are case-insensitive.
91+
The value is specified in bytes. You can use a human-readable memory string,
92+
e.g. `128mb`, `2gb`, etc. Units are case-insensitive.
4393

44-
- The `--all` flag to allow clearing internal helper images and frontend images
45-
set using the `#syntax=` directive or the `BUILDKIT_SYNTAX` build argument.
94+
### <a name="min-free-space"></a> Target amount of free disk space after pruning (--min-free-space)
4695

47-
## Examples
96+
The `--min-free-space` flag allows setting a target amount of free disk space
97+
that should be available after pruning. If the available disk space is less
98+
than this value, the least recently used cache records are deleted until
99+
the available free space is greater than or equal to the specified value.
100+
101+
The value is specified in bytes. You can use a human-readable memory string,
102+
e.g. `128mb`, `2gb`, etc. Units are case-insensitive.
103+
104+
### <a name="reserved-space"></a> Amount of disk space always allowed to keep for cache (--reserved-space)
105+
106+
The `--reserved-space` flag allows setting an amount of disk space that
107+
should always be kept for the build cache. If the available disk space is less
108+
than this value, the least recently used cache records are deleted until
109+
the available free space is greater than or equal to the specified value.
110+
111+
The value is specified in bytes. You can use a human-readable memory string,
112+
e.g. `128mb`, `2gb`, etc. Units are case-insensitive.
48113

49114
### <a name="builder"></a> Override the configured builder instance (--builder)
50115

0 commit comments

Comments
 (0)