docker/buildx
1
0
Fork 0
mirror of https://gitea.com/Lydanne/buildx.git synced 2025-05-18 00:47:48 +08:00
Code Issues Packages Projects Releases 1 Wiki Activity

feedback + updated examples + added links for h3 headings

Browse Source 
Signed-off-by: sarahsanders-docker <sarah.sanders@docker.com>
This commit is contained in:
sarahsanders-docker 2025-04-22 12:14:51 -04:00 committed by Tonis Tiigi
parent 4dac5295a1
commit 23ce21c341
No known key found for this signature in database
GPG Key ID: AFA9DE5F8AB7AF39
10 changed files with 300 additions and 58 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--> <!---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`

44
docs/reference/buildx_history_export.md
View File

@ -23,23 +23,49 @@ Desktop or shared across environments.
## Examples ## Examples
### Export a single build to a custom file ### <a name="export-single-build"></a> Export a single build to a custom file
```console ```console
docker buildx history export mybuild --output mybuild.dockerbuild docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
``` ```
### Export multiple builds to individual `.dockerbuild` files You can find build IDs by running:
This example writes `mybuild.dockerbuild` and `backend-build.dockerbuild` to
the current directory:
```console ```console
docker buildx history export mybuild backend-build docker buildx history ls
``` ```
### Export all build records ### <a name="export-multiple-builds"></a> Export multiple builds to individual `.dockerbuild` files
To export two builds to separate files:
```console ```console
docker buildx history export --all # Using build IDs
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt -o mybuild.dockerbuild
docker buildx history export qsiifiuf1ad9pa9qvppc0z1l3 -o backend-build.dockerbuild
# Or using relative offsets
docker buildx history export ^1 -o mybuild.dockerbuild
docker buildx history export ^2 -o backend-build.dockerbuild
```
Or use shell redirection:
```console
docker buildx history export ^1 > mybuild.dockerbuild
docker buildx history export ^2 > backend-build.dockerbuild
```
### <a name="export-all-builds"></a> Export all build records to a file
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
``` ```

14
docs/reference/buildx_history_import.md
View File

@ -22,20 +22,26 @@ pipelines.
## Examples ## Examples
### Import a `.dockerbuild` archive into Docker Desktop ### <a name="import-dockerbuild"></a> Import a `.dockerbuild` archive from standard input
```console ```console
docker buildx history import < mybuild.dockerbuild docker buildx history import < mybuild.dockerbuild
``` ```
### Import a file using a specific path ### <a name="import-build-archive"></a> Import a build archive from a file
```console ```console
docker buildx history import --file ./artifacts/backend-build.dockerbuild docker buildx history import --file ./artifacts/backend-build.dockerbuild
``` ```
### Import a file and open it in Docker Desktop ### <a name="open-build-manually"></a> 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 ```console
docker buildx history import --file ./ci-build.dockerbuild && docker buildx history open ci-build docker buildx history open ci-build
``` ```

43
docs/reference/buildx_history_inspect.md
View File

@ -29,10 +29,44 @@ provenance, SBOMs, or other detailed information.
## Examples ## Examples
### Inspect a build and print metadata ### <a name="inspect-most-recent-build"></a> Inspect the most recent build
```console ```console
docker buildx history inspect mybuild $ 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
```
### <a name="inspect-specific-build"></a> 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) ### <a name="format"></a> Format the output (--format)
@ -40,6 +74,8 @@ docker buildx history inspect mybuild
The formatting options (`--format`) pretty-prints the output to `pretty` (default), The formatting options (`--format`) pretty-prints the output to `pretty` (default),
`json` or using a Go template. `json` or using a Go template.
**Pretty output**
```console ```console
$ docker buildx history inspect $ docker buildx history inspect
Name: buildx (binaries) Name: buildx (binaries)
@ -69,6 +105,7 @@ sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3
Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b
``` ```
**JSON output**
```console ```console
$ docker buildx history inspect --format json $ docker buildx history inspect --format json
@ -123,6 +160,8 @@ $ docker buildx history inspect --format json
} }
``` ```
**Go template output**
```console ```console
$ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})" $ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})"
buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361) buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361)

54
docs/reference/buildx_history_inspect_attachment.md
View File

@ -23,16 +23,60 @@ platform-specific.
## Examples ## Examples
### Inspect a provenance attachment from a build ### <a name="inspect-provenance-attachment"></a> Inspect a provenance attachment from a build
Supported types include `provenance` and `sbom`.
```console ```console
docker buildx history inspect attachment mybuild --type https://slsa.dev/provenance/v0.2 $ 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 ### <a name="insepct-SBOM"></a> Inspect a SBOM for linux/amd64
```console ```console
docker buildx history inspect attachment mybuild \ $ docker buildx history inspect attachment ^0 \
--type application/vnd.cyclonedx+json \ --type sbom \
--platform linux/amd64 --platform linux/amd64
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"components": [
{
"type": "library",
"name": "alpine",
"version": "3.18.2"
}
]
}
``` ```
### <a name="inspect-attachment-digest"></a> 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.

46
docs/reference/buildx_history_logs.md
View File

@ -16,32 +16,60 @@ Print the logs of a build
## Description ## 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 without multiplexing. 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. 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 ## Examples
### Print logs for the most recent build ### <a name="print-logs-recent-build"></a> Print logs for the most recent build
```console ```console
docker buildx history logs $ 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
...
``` ```
### Print logs for a specific build By default, this shows logs for the most recent build on the current builder.
### <a name="print-logs-specific-build"></a> Print logs for a specific build
To print logs for a specific build, use a build ID or offset:
```console ```console
docker buildx history logs mybuild # Using a build ID
docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history logs ^1
``` ```
### Print logs in JSON format ### <a name="print-logs-json"></a> Print logs in JSON format
```console ```console
docker buildx history logs mybuild --progress rawjson $ 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}
...
``` ```
### Print logs in TTY format ### <a name="print-logs-tty"></a> Print logs in TTY format
```console ```console
docker buildx history logs mybuild --progress tty # Using a build ID
docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt --progress tty
# Or using a relative offset
docker buildx history logs ^1 --progress tty
``` ```

56
docs/reference/buildx_history_ls.md
View File

@ -20,45 +20,81 @@ List build records
## Description ## Description
List completed builds recorded by the active builder. Each entry includes the List completed builds recorded by the active builder. Each entry includes the
build ID, name (if available), status, timestamp, and duration. build ID, name, status, timestamp, and duration.
By default, only records for the current builder are shown. You can filter By default, only records for the current builder are shown. You can filter
results using flags. results using flags.
## Examples ## Examples
### List all build records for the current builder ### <a name="list-build-records-current"></a> List all build records for the current builder
```console ```console
docker buildx history ls $ 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
``` ```
### List only failed builds ### <a name="list-failed-builds"></a> List only failed builds
```console ```console
docker buildx history ls --filter status=error docker buildx history ls --filter status=error
``` ```
### List builds from the current directory 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="list-builds-current-project"></a> List builds from the current project
```console ```console
docker buildx history ls --local docker buildx history ls --local
``` ```
### Display full output without truncation ### <a name="display-full-output"></a> Display full output without truncation
```console ```console
docker buildx history ls --no-trunc docker buildx history ls --no-trunc
``` ```
### Format output as JSON ### <a name="list-as-json"></a> Format output as JSON
```console ```console
docker buildx history ls --format json $ 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"
}
]
``` ```
### Use a Go template to print name and durations ### <a name="list-go-template"></a> Use a Go template to print name and durations
```console ```console
docker buildx history ls --format '{{.Name}} - {{.Duration}}' $ docker buildx history ls --format '{{.Name}} - {{.Duration}}'
.dev/2850 - 1.4s
.dev/2850 - 1.3s
.dev/3120 - 2.1s
``` ```

15
docs/reference/buildx_history_open.md
View File

@ -15,18 +15,25 @@ Open a build in Docker Desktop
## Description ## Description
Open a build record in Docker Desktop for visual inspection. This requires Docker Desktop to be installed and running on the host machine. Open a build record in Docker Desktop for visual inspection. This requires
Docker Desktop to be installed and running on the host machine.
## Examples ## Examples
### Open the most recent build in Docker Desktop ### <a name="open-most-recent-build"></a> Open the most recent build in Docker Desktop
```console ```console
docker buildx history open docker buildx history open
``` ```
### Open a specific build by name By default, this opens the most recent build on the current builder.
### <a name="open-specific-build"></a> Open a specific build
```console ```console
docker buildx history open mybuild # Using a build ID
docker buildx history open qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history open ^1
``` ```

20
docs/reference/buildx_history_rm.md
View File

@ -17,24 +17,32 @@ Remove build records
## Description ## Description
Remove one or more build records from the current builder’s history. You can Remove one or more build records from the current builder’s history. You can
remove specific builds by name or ID, or delete all records at once using remove specific builds by ID or offset, or delete all records at once using
the `--all` flag. the `--all` flag.
## Examples ## Examples
### Remove a specific build ### <a name="remove-specific-build"></a> Remove a specific build
```console ```console
docker buildx history rm mybuild # Using a build ID
docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history rm ^1
``` ```
### Remove multiple builds ### <a name="remove-multiple-builds"></a> Remove multiple builds
```console ```console
docker buildx history rm mybuild frontend-build backend-build # 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 ### <a name="remove-all-build-records"></a> Remove all build records from the current builder
```console ```console
docker buildx history rm --all docker buildx history rm --all

37
docs/reference/buildx_history_trace.md
View File

@ -18,33 +18,52 @@ Show the OpenTelemetry trace of a build record
## Description ## Description
View the OpenTelemetry trace for a completed build. This command loads the View the OpenTelemetry trace for a completed build. This command loads the
trace into a Jaeger UI running in a local container trace into a Jaeger UI viewer and opens it in your browser.
(or a custom instance if configured) and opens it in your browser.
This helps analyze build performance, step timing, and internal execution flows. This helps analyze build performance, step timing, and internal execution flows.
## Examples ## Examples
### Open the OpenTelemetry trace for the most recent build ### <a name="open-opentelemetry-trace"></a> 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 ```console
docker buildx history trace docker buildx history trace
``` ```
### Open the trace for a specific build ### <a name="open-trace-specific-build"></a> Open the trace for a specific build
```console ```console
docker buildx history trace mybuild # Using a build ID
docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt
# Or using a relative offset
docker buildx history trace ^1
``` ```
### Run the Jaeger UI on a specific port ### <a name="run-Jaegar-UI-port"></a> Run the Jaeger UI on a specific port
```console ```console
docker buildx history trace mybuild --addr 127.0.0.1:16686 # 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
``` ```
### Compare two build traces ### <a name="compare-traces"></a> Compare two build traces
Compare two specific builds by name:
```console ```console
docker buildx history trace --compare mybuild:main mybuild:feature # 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.