Skip to content

Commit 9e17bc7

Browse files
tonistiigitonistiigi
authored
Merge pull request #3127 from sarahsanders-docker/docs-buildx-history
docs: add descriptions and examples for buildx history commands
2 parents 9a48aca + e1e8f5c commit 9e17bc7

10 files changed

+517
-36
lines changed

‎docs/reference/buildx_history.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,32 @@ Commands to work on build records
2727

2828
<!---MARKER_GEN_END-->
2929

30+
### Build references
31+
32+
Most `buildx history` subcommands accept a build reference to identify which
33+
build to act on. You can specify the build in two ways:
34+
35+
- By build ID, fetched by `docker buildx history ls`:
36+
37+
```console
38+
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output build.dockerbuild
39+
```
40+
41+
- By relative offset, to refer to recent builds:
42+
43+
```console
44+
docker buildx history export ^1 --output build.dockerbuild
45+
```
46+
47+
- `^0` or no reference targets the most recent build
48+
- `^1` refers to the build before the most recent
49+
- `^2` refers to two builds back, and so on
50+
51+
Offset references are supported in the following `buildx history` commands:
52+
53+
- `logs`
54+
- `inspect`
55+
- `open`
56+
- `trace`
57+
- `export`
58+
- `rm`

‎docs/reference/buildx_history_export.md‎

Lines changed: 70 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,77 @@ Export a build into Docker Desktop bundle
55

66
### Options
77

8-
| Name | Type | Default | Description |
9-
|:-----------------|:---------|:--------|:-----------------------------------------|
10-
| `--all` | `bool` | | Export all records for the builder |
11-
| `--builder` | `string` | | Override the configured builder instance |
12-
| `-D`, `--debug` | `bool` | | Enable debug logging |
13-
| `-o`, `--output` | `string` | | Output file path |
8+
| Name | Type | Default | Description |
9+
|:---------------------------------------|:---------|:--------|:-----------------------------------------|
10+
| [`--all`](#all) | `bool` | | Export all records for the builder |
11+
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
12+
| [`-D`](#debug), [`--debug`](#debug) | `bool` | | Enable debug logging |
13+
| [`-o`](#output), [`--output`](#output) | `string` | | Output file path |
1414

1515

1616
<!---MARKER_GEN_END-->
1717

18+
## Description
19+
20+
Export one or more build records to `.dockerbuild` archive files. These archives
21+
contain metadata, logs, and build outputs, and can be imported into Docker
22+
Desktop or shared across environments.
23+
24+
## Examples
25+
26+
### <a name="output"></a> Export a single build to a custom file (--output)
27+
28+
```console
29+
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
30+
```
31+
32+
You can find build IDs by running:
33+
34+
```console
35+
docker buildx history ls
36+
```
37+
38+
### <a name="o"></a> Export multiple builds to individual `.dockerbuild` files (-o)
39+
40+
To export two builds to separate files:
41+
42+
```console
43+
# Using build IDs
44+
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild
45+
46+
# Or using relative offsets
47+
docker buildx history export ^1 ^2 -o multi.dockerbuild
48+
```
49+
50+
Or use shell redirection:
51+
52+
```console
53+
docker buildx history export ^1 > mybuild.dockerbuild
54+
docker buildx history export ^2 > backend-build.dockerbuild
55+
```
56+
57+
### <a name="all"></a> Export all build records to a file (--all)
58+
59+
Use the `--all` flag and redirect the output:
60+
61+
```console
62+
docker buildx history export --all > all-builds.dockerbuild
63+
```
64+
65+
Or use the `--output` flag:
66+
67+
```console
68+
docker buildx history export --all -o all-builds.dockerbuild
69+
```
70+
71+
### <a name="builder"></a> Use a specific builder instance (--builder)
72+
73+
```console
74+
docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
75+
```
76+
77+
### <a name="debug"></a> Enable debug logging (--debug)
78+
79+
```console
80+
docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild
81+
```

‎docs/reference/buildx_history_import.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,43 @@ Import a build into Docker Desktop
55

66
### Options
77

8-
| Name | Type | Default | Description |
9-
|:----------------|:--------------|:--------|:-----------------------------------------|
10-
| `--builder` | `string` | | Override the configured builder instance |
11-
| `-D`, `--debug` | `bool` | | Enable debug logging |
12-
| `-f`, `--file` | `stringArray` | | Import from a file path |
8+
| Name | Type | Default | Description |
9+
|:---------------------------------|:--------------|:--------|:-----------------------------------------|
10+
| `--builder` | `string` | | Override the configured builder instance |
11+
| `-D`, `--debug` | `bool` | | Enable debug logging |
12+
| [`-f`](#file), [`--file`](#file) | `stringArray` | | Import from a file path |
1313

1414

1515
<!---MARKER_GEN_END-->
1616

17+
## Description
18+
19+
Import a build record from a `.dockerbuild` archive into Docker Desktop. This
20+
lets you view, inspect, and analyze builds created in other environments or CI
21+
pipelines.
22+
23+
## Examples
24+
25+
### Import a `.dockerbuild` archive from standard input
26+
27+
```console
28+
docker buildx history import < mybuild.dockerbuild
29+
```
30+
31+
### <a name="file"></a> Import a build archive from a file (--file)
32+
33+
```console
34+
docker buildx history import --file ./artifacts/backend-build.dockerbuild
35+
```
36+
37+
### Open a build manually
38+
39+
By default, the `import` command automatically opens the imported build in Docker
40+
Desktop. You don't need to run `open` unless you're opening a specific build
41+
or re-opening it later.
42+
43+
If you've imported multiple builds, you can open one manually:
44+
45+
```console
46+
docker buildx history open ci-build
47+
```

‎docs/reference/buildx_history_inspect.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,61 @@ Inspect a build
2121

2222
<!---MARKER_GEN_END-->
2323

24+
## Description
25+
26+
Inspect a build record to view metadata such as duration, status, build inputs,
27+
platforms, outputs, and attached artifacts. You can also use flags to extract
28+
provenance, SBOMs, or other detailed information.
29+
2430
## Examples
2531

32+
### Inspect the most recent build
33+
34+
```console
35+
$ docker buildx history inspect
36+
Name: buildx (binaries)
37+
Context: .
38+
Dockerfile: Dockerfile
39+
VCS Repository: https://github.com/crazy-max/buildx.git
40+
VCS Revision: f15eaa1ee324ffbbab29605600d27a84cab86361
41+
Target: binaries
42+
Platforms: linux/amd64
43+
Keep Git Dir: true
44+
45+
Started: 2025-02-07 11:56:24
46+
Duration: 1m 1s
47+
Build Steps: 16/16 (25% cached)
48+
49+
Image Resolve Mode: local
50+
51+
Materials:
52+
URI DIGEST
53+
pkg:docker/docker/dockerfile@1 sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25
54+
pkg:docker/[email protected]?platform=linux%2Famd64 sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037
55+
pkg:docker/tonistiigi/[email protected]?platform=linux%2Famd64 sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3
56+
57+
Attachments:
58+
DIGEST PLATFORM TYPE
59+
sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3 https://slsa.dev/provenance/v0.2
60+
```
61+
62+
### Inspect a specific build
63+
64+
```console
65+
# Using a build ID
66+
docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt
67+
68+
# Or using a relative offset
69+
docker buildx history inspect ^1
70+
```
71+
2672
### <a name="format"></a> Format the output (--format)
2773

2874
The formatting options (`--format`) pretty-prints the output to `pretty` (default),
2975
`json` or using a Go template.
3076

77+
**Pretty output**
78+
3179
```console
3280
$ docker buildx history inspect
3381
Name: buildx (binaries)
@@ -57,6 +105,7 @@ sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3
57105

58106
Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b
59107
```
108+
**JSON output**
60109

61110
```console
62111
$ docker buildx history inspect --format json
@@ -111,6 +160,8 @@ $ docker buildx history inspect --format json
111160
}
112161
```
113162

163+
**Go template output**
164+
114165
```console
115166
$ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})"
116167
buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361)

‎docs/reference/buildx_history_inspect_attachment.md‎

Lines changed: 71 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,78 @@ Inspect a build attachment
55

66
### Options
77

8-
| Name | Type | Default | Description |
9-
|:----------------|:---------|:--------|:-----------------------------------------|
10-
| `--builder` | `string` | | Override the configured builder instance |
11-
| `-D`, `--debug` | `bool` | | Enable debug logging |
12-
| `--platform` | `string` | | Platform of attachment |
13-
| `--type` | `string` | | Type of attachment |
8+
| Name | Type | Default | Description |
9+
|:------------------|:---------|:--------|:-----------------------------------------|
10+
| `--builder` | `string` | | Override the configured builder instance |
11+
| `-D`, `--debug` | `bool` | | Enable debug logging |
12+
| `--platform` | `string` | | Platform of attachment |
13+
| [`--type`](#type) | `string` | | Type of attachment |
1414

1515

1616
<!---MARKER_GEN_END-->
1717

18+
## Description
19+
20+
Inspect a specific attachment from a build record, such as a provenance file or
21+
SBOM. Attachments are optional artifacts stored with the build and may be
22+
platform-specific.
23+
24+
## Examples
25+
26+
### <a name="type"></a> Inspect a provenance attachment from a build (--type)
27+
28+
Supported types include `provenance` and `sbom`.
29+
30+
```console
31+
$ docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt --type provenance
32+
{
33+
"_type": "https://slsa.dev/provenance/v0.2",
34+
"buildDefinition": {
35+
"buildType": "https://build.docker.com/BuildKit@v1",
36+
"externalParameters": {
37+
"target": "app",
38+
"platforms": ["linux/amd64"]
39+
}
40+
},
41+
"runDetails": {
42+
"builder": "docker",
43+
"by": "[email protected]"
44+
}
45+
}
46+
```
47+
48+
### Inspect a SBOM for linux/amd64
49+
50+
```console
51+
$ docker buildx history inspect attachment ^0 \
52+
--type sbom \
53+
--platform linux/amd64
54+
{
55+
"bomFormat": "CycloneDX",
56+
"specVersion": "1.5",
57+
"version": 1,
58+
"components": [
59+
{
60+
"type": "library",
61+
"name": "alpine",
62+
"version": "3.18.2"
63+
}
64+
]
65+
}
66+
```
67+
68+
### Inspect an attachment by digest
69+
70+
You can inspect an attachment directly using its digset, which you can get from
71+
the `inspect` output:
72+
73+
```console
74+
# Using a build ID
75+
docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt sha256:abcdef123456...
76+
77+
# Or using a relative offset
78+
docker buildx history inspect attachment ^0 sha256:abcdef123456...
79+
```
80+
81+
Use `--type sbom` or `--type provenance` to filter attachments by type. To
82+
inspect a specific attachment by digest, omit the `--type` flag.

‎docs/reference/buildx_history_logs.md‎

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,61 @@ Print the logs of a build
55

66
### Options
77

8-
| Name | Type | Default | Description |
9-
|:----------------|:---------|:--------|:--------------------------------------------------|
10-
| `--builder` | `string` | | Override the configured builder instance |
11-
| `-D`, `--debug` | `bool` | | Enable debug logging |
12-
| `--progress` | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
8+
| Name | Type | Default | Description |
9+
|:--------------------------|:---------|:--------|:--------------------------------------------------|
10+
| `--builder` | `string` | | Override the configured builder instance |
11+
| `-D`, `--debug` | `bool` | | Enable debug logging |
12+
| [`--progress`](#progress) | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
1313

1414

1515
<!---MARKER_GEN_END-->
1616

17+
## Description
18+
19+
Print the logs for a completed build. The output appears in the same format as
20+
`--progress=plain`, showing the full logs for each step.
21+
22+
By default, this shows logs for the most recent build on the current builder.
23+
24+
You can also specify an earlier build using an offset. For example:
25+
26+
- `^1` shows logs for the build before the most recent
27+
- `^2` shows logs for the build two steps back
28+
29+
## Examples
30+
31+
### Print logs for the most recent build
32+
33+
```console
34+
$ docker buildx history logs
35+
#1 [internal] load build definition from Dockerfile
36+
#1 transferring dockerfile: 31B done
37+
#1 DONE 0.0s
38+
#2 [internal] load .dockerignore
39+
#2 transferring context: 2B done
40+
#2 DONE 0.0s
41+
...
42+
```
43+
44+
By default, this shows logs for the most recent build on the current builder.
45+
46+
### Print logs for a specific build
47+
48+
To print logs for a specific build, use a build ID or offset:
49+
50+
```console
51+
# Using a build ID
52+
docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt
53+
54+
# Or using a relative offset
55+
docker buildx history logs ^1
56+
```
57+
58+
### <a name="progress"></a> Set type of progress output (--progress)
59+
60+
```console
61+
$ docker buildx history logs ^1 --progress rawjson
62+
{"id":"buildx_step_1","status":"START","timestamp":"2024-05-01T12:34:56.789Z","detail":"[internal] load build definition from Dockerfile"}
63+
{"id":"buildx_step_1","status":"COMPLETE","timestamp":"2024-05-01T12:34:57.001Z","duration":212000000}
64+
...
65+
```

0 commit comments

Comments
 (0)