docker
/
buildx
mirror of https://github.com/docker/buildx.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3127 from sarahsanders-docker/docs-buildx-history 

docs: add descriptions and examples for buildx history commands
This commit is contained in:
Tõnis Tiigi 2025-05-05 15:00:01 -07:00 committed by GitHub
parent 9a48aca461 e1e8f5c68d
commit 9e17bc7a4c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 517 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/reference/buildx_history.md
View File

@ -27,3 +27,32 @@ Commands to work on build records
<!---MARKER_GEN_END-->
### Build references
Most `buildx history` subcommands accept a build reference to identify which
build to act on. You can specify the build in two ways:
- By build ID, fetched by `docker buildx history ls`:
```console
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output build.dockerbuild
```
- By relative offset, to refer to recent builds:
```console
docker buildx history export ^1 --output build.dockerbuild
```
- `^0` or no reference targets the most recent build
- `^1` refers to the build before the most recent
- `^2` refers to two builds back, and so on
Offset references are supported in the following `buildx history` commands:
- `logs`
- `inspect`
- `open`
- `trace`
- `export`
- `rm`

76
docs/reference/buildx_history_export.md
View File

@ -5,13 +5,77 @@ Export a build into Docker Desktop bundle
### Options
| Name | Type | Default | Description |
|:-----------------|:---------|:--------|:-----------------------------------------|
| `--all` | `bool` | | Export all records for the builder |
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `-o`, `--output` | `string` | | Output file path |
| Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-----------------------------------------|
| [`--all`](#all) | `bool` | | Export all records for the builder |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| [`-D`](#debug), [`--debug`](#debug) | `bool` | | Enable debug logging |
| [`-o`](#output), [`--output`](#output) | `string` | | Output file path |
<!---MARKER_GEN_END-->
## Description
Export one or more build records to `.dockerbuild` archive files. These archives
contain metadata, logs, and build outputs, and can be imported into Docker
Desktop or shared across environments.
## Examples
### <a name="output"></a> Export a single build to a custom file (--output)
```console
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
```
You can find build IDs by running:
```console
docker buildx history ls
```
### <a name="o"></a> Export multiple builds to individual `.dockerbuild` files (-o)
To export two builds to separate files:
```console
# Using build IDs
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild
# Or using relative offsets
docker buildx history export ^1 ^2 -o multi.dockerbuild
```
Or use shell redirection:
```console
docker buildx history export ^1 > mybuild.dockerbuild
docker buildx history export ^2 > backend-build.dockerbuild
```
### <a name="all"></a> Export all build records to a file (--all)
Use the `--all` flag and redirect the output:
```console
docker buildx history export --all > all-builds.dockerbuild
```
Or use the `--output` flag:
```console
docker buildx history export --all -o all-builds.dockerbuild
```
### <a name="builder"></a> Use a specific builder instance (--builder)
```console
docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
```
### <a name="debug"></a> Enable debug logging (--debug)
```console
docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild
```

41
docs/reference/buildx_history_import.md
View File

@ -5,12 +5,43 @@ Import a build into Docker Desktop
### Options
| Name | Type | Default | Description |
|:----------------|:--------------|:--------|:-----------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `-f`, `--file` | `stringArray` | | Import from a file path |
| Name | Type | Default | Description |
|:---------------------------------|:--------------|:--------|:-----------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`-f`](#file), [`--file`](#file) | `stringArray` | | Import from a file path |
<!---MARKER_GEN_END-->
## Description
Import a build record from a `.dockerbuild` archive into Docker Desktop. This
lets you view, inspect, and analyze builds created in other environments or CI
pipelines.
## Examples
### Import a `.dockerbuild` archive from standard input
```console
docker buildx history import < mybuild.dockerbuild
```
### <a name="file"></a> Import a build archive from a file (--file)
```console
docker buildx history import --file ./artifacts/backend-build.dockerbuild
```
### Open a build manually
By default, the `import` command automatically opens the imported build in Docker
Desktop. You don't need to run `open` unless you're opening a specific build
or re-opening it later.
If you've imported multiple builds, you can open one manually:
```console
docker buildx history open ci-build
```

51
docs/reference/buildx_history_inspect.md
View File

@ -21,13 +21,61 @@ Inspect a build
<!---MARKER_GEN_END-->
## Description
Inspect a build record to view metadata such as duration, status, build inputs,
platforms, outputs, and attached artifacts. You can also use flags to extract
provenance, SBOMs, or other detailed information.
## Examples
### Inspect the most recent build
```console
$ docker buildx history inspect
Name: buildx (binaries)
Context: .
Dockerfile: Dockerfile
VCS Repository: https://github.com/crazy-max/buildx.git
VCS Revision: f15eaa1ee324ffbbab29605600d27a84cab86361
Target: binaries
Platforms: linux/amd64
Keep Git Dir: true
Started: 2025-02-07 11:56:24
Duration: 1m 1s
Build Steps: 16/16 (25% cached)
Image Resolve Mode: local
Materials:
URI DIGEST
pkg:docker/docker/dockerfile@1 sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25
pkg:docker/golang@1.23-alpine3.21?platform=linux%2Famd64 sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037
pkg:docker/tonistiigi/xx@1.6.1?platform=linux%2Famd64 sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3
Attachments:
DIGEST PLATFORM TYPE
sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3 https://slsa.dev/provenance/v0.2
```
### Inspect a specific build
```console
# Using a build ID
docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history inspect ^1
```
### <a name="format"></a> Format the output (--format)
The formatting options (`--format`) pretty-prints the output to `pretty` (default),
`json` or using a Go template.
**Pretty output**
```console
$ docker buildx history inspect
Name: buildx (binaries)
@ -57,6 +105,7 @@ sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3
Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b
```
**JSON output**
```console
$ docker buildx history inspect --format json
@ -111,6 +160,8 @@ $ docker buildx history inspect --format json
}
```
**Go template output**
```console
$ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})"
buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361)

77
docs/reference/buildx_history_inspect_attachment.md
View File

@ -5,13 +5,78 @@ Inspect a build attachment
### Options
| Name | Type | Default | Description |
|:----------------|:---------|:--------|:-----------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `--platform` | `string` | | Platform of attachment |
| `--type` | `string` | | Type of attachment |
| Name | Type | Default | Description |
|:------------------|:---------|:--------|:-----------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `--platform` | `string` | | Platform of attachment |
| [`--type`](#type) | `string` | | Type of attachment |
<!---MARKER_GEN_END-->
## Description
Inspect a specific attachment from a build record, such as a provenance file or
SBOM. Attachments are optional artifacts stored with the build and may be
platform-specific.
## Examples
### <a name="type"></a> Inspect a provenance attachment from a build (--type)
Supported types include `provenance` and `sbom`.
```console
$ docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt --type provenance
{
"_type": "https://slsa.dev/provenance/v0.2",
"buildDefinition": {
"buildType": "https://build.docker.com/BuildKit@v1",
"externalParameters": {
"target": "app",
"platforms": ["linux/amd64"]
}
},
"runDetails": {
"builder": "docker",
"by": "ci@docker.com"
}
}
```
### Inspect a SBOM for linux/amd64
```console
$ docker buildx history inspect attachment ^0 \
--type sbom \
--platform linux/amd64
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"components": [
{
"type": "library",
"name": "alpine",
"version": "3.18.2"
}
]
}
```
### Inspect an attachment by digest
You can inspect an attachment directly using its digset, which you can get from
the `inspect` output:
```console
# Using a build ID
docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt sha256:abcdef123456...
# Or using a relative offset
docker buildx history inspect attachment ^0 sha256:abcdef123456...
```
Use `--type sbom` or `--type provenance` to filter attachments by type. To
inspect a specific attachment by digest, omit the `--type` flag.

59
docs/reference/buildx_history_logs.md
View File

@ -5,12 +5,61 @@ Print the logs of a build
### Options
| Name | Type | Default | Description |
|:----------------|:---------|:--------|:--------------------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `--progress` | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
| Name | Type | Default | Description |
|:--------------------------|:---------|:--------|:--------------------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--progress`](#progress) | `string` | `plain` | Set type of progress output (plain, rawjson, tty) |
<!---MARKER_GEN_END-->
## Description
Print the logs for a completed build. The output appears in the same format as
`--progress=plain`, showing the full logs for each step.
By default, this shows logs for the most recent build on the current builder.
You can also specify an earlier build using an offset. For example:
- `^1` shows logs for the build before the most recent
- `^2` shows logs for the build two steps back
## Examples
### Print logs for the most recent build
```console
$ docker buildx history logs
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 31B done
#1 DONE 0.0s
#2 [internal] load .dockerignore
#2 transferring context: 2B done
#2 DONE 0.0s
...
```
By default, this shows logs for the most recent build on the current builder.
### Print logs for a specific build
To print logs for a specific build, use a build ID or offset:
```console
# Using a build ID
docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history logs ^1
```
### <a name="progress"></a> Set type of progress output (--progress)
```console
$ docker buildx history logs ^1 --progress rawjson
{"id":"buildx_step_1","status":"START","timestamp":"2024-05-01T12:34:56.789Z","detail":"[internal] load build definition from Dockerfile"}
{"id":"buildx_step_1","status":"COMPLETE","timestamp":"2024-05-01T12:34:57.001Z","duration":212000000}
...
```

99
docs/reference/buildx_history_ls.md
View File

@ -5,15 +5,98 @@ List build records
### Options
| Name | Type | Default | Description |
|:----------------|:--------------|:--------|:---------------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `--filter` | `stringArray` | | Provide filter values (e.g., `status=error`) |
| `--format` | `string` | `table` | Format the output |
| `--local` | `bool` | | List records for current repository only |
| `--no-trunc` | `bool` | | Don't truncate output |
| Name | Type | Default | Description |
|:--------------------------|:--------------|:--------|:---------------------------------------------|
| `--builder` | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--filter`](#filter) | `stringArray` | | Provide filter values (e.g., `status=error`) |
| [`--format`](#format) | `string` | `table` | Format the output |
| [`--local`](#local) | `bool` | | List records for current repository only |
| [`--no-trunc`](#no-trunc) | `bool` | | Don't truncate output |
<!---MARKER_GEN_END-->
## Description
List completed builds recorded by the active builder. Each entry includes the
build ID, name, status, timestamp, and duration.
By default, only records for the current builder are shown. You can filter
results using flags.
## Examples
### List all build records for the current builder
```console
$ docker buildx history ls
BUILD ID NAME STATUS CREATED AT DURATION
qu2gsuo8ejqrwdfii23xkkckt .dev/2850 Completed 3 days ago 1.4s
qsiifiuf1ad9pa9qvppc0z1l3 .dev/2850 Completed 3 days ago 1.3s
g9808bwrjrlkbhdamxklx660b .dev/3120 Completed 5 days ago 2.1s
```
### <a name="filter"></a> List failed builds (--filter)
```console
docker buildx history ls --filter status=error
```
You can filter the list using the `--filter` flag. Supported filters include:
| Filter | Supported comparisons | Example |
|:-------|:----------------------|:--------|
| `ref`, `repository`, `status` | Support `=` and `!=` comparisons | `--filter status!=success` |
| `startedAt`, `completedAt`, `duration` | Support `<` and `>` comparisons with time values | `--filter duration>30s` |
You can combine multiple filters by repeating the `--filter` flag:
```console
docker buildx history ls --filter status=error --filter duration>30s
```
### <a name="local"></a> List builds from the current project (--local)
```console
docker buildx history ls --local
```
### <a name="no-trunc"></a> Display full output without truncation (--no-trunc)
```console
docker buildx history ls --no-trunc
```
### <a name="format"></a> Format output (--format)
**JSON output**
```console
$ docker buildx history ls --format json
[
{
"ID": "qu2gsuo8ejqrwdfii23xkkckt",
"Name": ".dev/2850",
"Status": "Completed",
"CreatedAt": "2025-04-15T12:33:00Z",
"Duration": "1.4s"
},
{
"ID": "qsiifiuf1ad9pa9qvppc0z1l3",
"Name": ".dev/2850",
"Status": "Completed",
"CreatedAt": "2025-04-15T12:29:00Z",
"Duration": "1.3s"
}
]
```
**Go template output**
```console
$ docker buildx history ls --format '{{.Name}} - {{.Duration}}'
.dev/2850 - 1.4s
.dev/2850 - 1.3s
.dev/3120 - 2.1s
```

24
docs/reference/buildx_history_open.md
View File

@ -13,3 +13,27 @@ Open a build in Docker Desktop
<!---MARKER_GEN_END-->
## Description
Open a build record in Docker Desktop for visual inspection. This requires
Docker Desktop to be installed and running on the host machine.
## Examples
### Open the most recent build in Docker Desktop
```console
docker buildx history open
```
By default, this opens the most recent build on the current builder.
### Open a specific build
```console
# Using a build ID
docker buildx history open qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history open ^1
```

33
docs/reference/buildx_history_rm.md
View File

@ -14,3 +14,36 @@ Remove build records
<!---MARKER_GEN_END-->
## Description
Remove one or more build records from the current builder’s history. You can
remove specific builds by ID or offset, or delete all records at once using
the `--all` flag.
## Examples
### Remove a specific build
```console
# Using a build ID
docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history rm ^1
```
### Remove multiple builds
```console
# Using build IDs
docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
# Or using relative offsets
docker buildx history rm ^1 ^2
```
### Remove all build records from the current builder
```console
docker buildx history rm --all
```

64
docs/reference/buildx_history_trace.md
View File

@ -5,13 +5,65 @@ Show the OpenTelemetry trace of a build record
### Options
| Name | Type | Default | Description |
|:----------------|:---------|:--------------|:-----------------------------------------|
| `--addr` | `string` | `127.0.0.1:0` | Address to bind the UI server |
| `--builder` | `string` | | Override the configured builder instance |
| `--compare` | `string` | | Compare with another build reference |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| Name | Type | Default | Description |
|:------------------------|:---------|:--------------|:-----------------------------------------|
| [`--addr`](#addr) | `string` | `127.0.0.1:0` | Address to bind the UI server |
| `--builder` | `string` | | Override the configured builder instance |
| [`--compare`](#compare) | `string` | | Compare with another build reference |
| `-D`, `--debug` | `bool` | | Enable debug logging |
<!---MARKER_GEN_END-->
## Description
View the OpenTelemetry trace for a completed build. This command loads the
trace into a Jaeger UI viewer and opens it in your browser.
This helps analyze build performance, step timing, and internal execution flows.
## Examples
### Open the OpenTelemetry trace for the most recent build
This command starts a temporary Jaeger UI server and opens your default browser
to view the trace.
```console
docker buildx history trace
```
### Open the trace for a specific build
```console
# Using a build ID
docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history trace ^1
```
### <a name="addr"></a> Run the Jaeger UI on a specific port (--addr)
```console
# Using a build ID
docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt --addr 127.0.0.1:16686
# Or using a relative offset
docker buildx history trace ^1 --addr 127.0.0.1:16686
```
### <a name="compare"></a> Compare two build traces (--compare)
Compare two specific builds by name:
```console
# Using build IDs
docker buildx history trace --compare=qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3
# Or using a single relative offset
docker buildx history trace --compare=^1
```
When you use a single reference with `--compare`, it compares that build
against the most recent one.