diff --git a/docs/reference/buildx_history.md b/docs/reference/buildx_history.md index 7eaa7c84..ef0cf8b1 100644 --- a/docs/reference/buildx_history.md +++ b/docs/reference/buildx_history.md @@ -27,3 +27,32 @@ Commands to work on build records +### 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` diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md index 468cf405..c24ab53c 100644 --- a/docs/reference/buildx_history_export.md +++ b/docs/reference/buildx_history_export.md @@ -23,23 +23,49 @@ Desktop or shared across environments. ## Examples -### Export a single build to a custom file +### Export a single build to a custom file ```console -docker buildx history export mybuild --output mybuild.dockerbuild +docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild ``` -### Export multiple builds to individual `.dockerbuild` files - -This example writes `mybuild.dockerbuild` and `backend-build.dockerbuild` to -the current directory: +You can find build IDs by running: ```console -docker buildx history export mybuild backend-build +docker buildx history ls ``` -### Export all build records +### Export multiple builds to individual `.dockerbuild` files + +To export two builds to separate files: ```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 +``` + +### 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 ``` diff --git a/docs/reference/buildx_history_import.md b/docs/reference/buildx_history_import.md index 777238c0..e890b7c1 100644 --- a/docs/reference/buildx_history_import.md +++ b/docs/reference/buildx_history_import.md @@ -22,20 +22,26 @@ pipelines. ## Examples -### Import a `.dockerbuild` archive into Docker Desktop +### Import a `.dockerbuild` archive from standard input ```console docker buildx history import < mybuild.dockerbuild ``` -### Import a file using a specific path +### Import a build archive from a file ```console docker buildx history import --file ./artifacts/backend-build.dockerbuild ``` -### Import a file and open it in Docker Desktop +### 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 import --file ./ci-build.dockerbuild && docker buildx history open ci-build +docker buildx history open ci-build ``` diff --git a/docs/reference/buildx_history_inspect.md b/docs/reference/buildx_history_inspect.md index 3c47db27..9246fbdd 100644 --- a/docs/reference/buildx_history_inspect.md +++ b/docs/reference/buildx_history_inspect.md @@ -29,10 +29,44 @@ provenance, SBOMs, or other detailed information. ## Examples -### Inspect a build and print metadata +### Inspect the most recent build ```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 +``` + +### Inspect a specific build + +```console +# Using a build ID +docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt + +# Or using a relative offset +docker buildx history inspect ^1 ``` ### Format the output (--format) @@ -40,6 +74,8 @@ docker buildx history inspect mybuild 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) @@ -69,6 +105,7 @@ sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3 Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b ``` +**JSON output** ```console $ docker buildx history inspect --format json @@ -123,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) diff --git a/docs/reference/buildx_history_inspect_attachment.md b/docs/reference/buildx_history_inspect_attachment.md index be8eb920..9377b865 100644 --- a/docs/reference/buildx_history_inspect_attachment.md +++ b/docs/reference/buildx_history_inspect_attachment.md @@ -23,16 +23,60 @@ platform-specific. ## Examples -### Inspect a provenance attachment from a build +### Inspect a provenance attachment from a build + +Supported types include `provenance` and `sbom`. ```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 +### Inspect a SBOM for linux/amd64 ```console -docker buildx history inspect attachment mybuild \ - --type application/vnd.cyclonedx+json \ +$ 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. diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md index 687aaece..9b917d66 100644 --- a/docs/reference/buildx_history_logs.md +++ b/docs/reference/buildx_history_logs.md @@ -16,32 +16,60 @@ Print the logs of a build ## 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. +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 +### Print logs for the most recent build ```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. + +### Print logs for a specific build + +To print logs for a specific build, use a build ID or offset: ```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 +### Print logs in JSON format ```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 +### Print logs in TTY format ```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 ``` diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md index 85f88225..9277cab5 100644 --- a/docs/reference/buildx_history_ls.md +++ b/docs/reference/buildx_history_ls.md @@ -20,45 +20,81 @@ List build records ## Description 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 results using flags. ## Examples -### List all build records for the current builder +### List all build records for the current builder ```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 +### List only failed builds ```console 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 +``` + +### List builds from the current project ```console docker buildx history ls --local ``` -### Display full output without truncation +### Display full output without truncation ```console docker buildx history ls --no-trunc ``` -### Format output as JSON +### Format output as JSON ```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 +### Use a Go template to print name and durations ```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 ``` diff --git a/docs/reference/buildx_history_open.md b/docs/reference/buildx_history_open.md index f0c19cc6..b9ed6f81 100644 --- a/docs/reference/buildx_history_open.md +++ b/docs/reference/buildx_history_open.md @@ -15,18 +15,25 @@ Open a build in Docker Desktop ## 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 -### Open the most recent build in Docker Desktop +### Open the most recent build in Docker Desktop ```console docker buildx history open ``` -### Open a specific build by name +By default, this opens the most recent build on the current builder. + +### Open a specific build ```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 ``` diff --git a/docs/reference/buildx_history_rm.md b/docs/reference/buildx_history_rm.md index 75687340..e7bbd1d8 100644 --- a/docs/reference/buildx_history_rm.md +++ b/docs/reference/buildx_history_rm.md @@ -17,24 +17,32 @@ Remove build records ## Description 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. ## Examples -### Remove a specific build +### Remove a specific build ```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 +### Remove multiple builds ```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 +### Remove all build records from the current builder ```console docker buildx history rm --all diff --git a/docs/reference/buildx_history_trace.md b/docs/reference/buildx_history_trace.md index 35bbf2e0..b95553d1 100644 --- a/docs/reference/buildx_history_trace.md +++ b/docs/reference/buildx_history_trace.md @@ -18,33 +18,52 @@ Show the OpenTelemetry trace of a build record ## Description View the OpenTelemetry trace for a completed build. This command loads the -trace into a Jaeger UI running in a local container -(or a custom instance if configured) and opens it in your browser. +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 +### 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 +### Open the trace for a specific build ```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 +### Run the Jaeger UI on a specific port ```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 +### Compare two build traces + +Compare two specific builds by name: ```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.