From 4dac5295a19fb2fde2cb722181dee2acef31ca7b Mon Sep 17 00:00:00 2001 From: sarahsanders-docker Date: Thu, 17 Apr 2025 14:50:58 -0400 Subject: [PATCH] Add descriptions and examples for buildx history commands Signed-off-by: sarahsanders-docker --- docs/reference/buildx_history_export.md | 28 ++++++++++++ docs/reference/buildx_history_import.md | 25 +++++++++++ docs/reference/buildx_history_inspect.md | 12 +++++ .../buildx_history_inspect_attachment.md | 21 +++++++++ docs/reference/buildx_history_logs.md | 31 +++++++++++++ docs/reference/buildx_history_ls.md | 45 +++++++++++++++++++ docs/reference/buildx_history_open.md | 17 +++++++ docs/reference/buildx_history_rm.md | 25 +++++++++++ docs/reference/buildx_history_trace.md | 33 ++++++++++++++ 9 files changed, 237 insertions(+) diff --git a/docs/reference/buildx_history_export.md b/docs/reference/buildx_history_export.md index 34b3bc2c..468cf405 100644 --- a/docs/reference/buildx_history_export.md +++ b/docs/reference/buildx_history_export.md @@ -15,3 +15,31 @@ Export a build into Docker Desktop bundle +## 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 + +### Export a single build to a custom file + +```console +docker buildx history export mybuild --output mybuild.dockerbuild +``` + +### Export multiple builds to individual `.dockerbuild` files + +This example writes `mybuild.dockerbuild` and `backend-build.dockerbuild` to +the current directory: + +```console +docker buildx history export mybuild backend-build +``` + +### Export all build records + +```console +docker buildx history export --all +``` diff --git a/docs/reference/buildx_history_import.md b/docs/reference/buildx_history_import.md index 618a485d..777238c0 100644 --- a/docs/reference/buildx_history_import.md +++ b/docs/reference/buildx_history_import.md @@ -14,3 +14,28 @@ Import a build into Docker Desktop +## 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 into Docker Desktop + +```console +docker buildx history import < mybuild.dockerbuild +``` + +### Import a file using a specific path + +```console +docker buildx history import --file ./artifacts/backend-build.dockerbuild +``` + +### Import a file and open it in Docker Desktop + +```console +docker buildx history import --file ./ci-build.dockerbuild && docker buildx history open ci-build +``` diff --git a/docs/reference/buildx_history_inspect.md b/docs/reference/buildx_history_inspect.md index bfad9661..3c47db27 100644 --- a/docs/reference/buildx_history_inspect.md +++ b/docs/reference/buildx_history_inspect.md @@ -21,8 +21,20 @@ Inspect a build +## 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 a build and print metadata + +```console +docker buildx history inspect mybuild +``` + ### Format the output (--format) The formatting options (`--format`) pretty-prints the output to `pretty` (default), diff --git a/docs/reference/buildx_history_inspect_attachment.md b/docs/reference/buildx_history_inspect_attachment.md index 453e02e2..be8eb920 100644 --- a/docs/reference/buildx_history_inspect_attachment.md +++ b/docs/reference/buildx_history_inspect_attachment.md @@ -15,3 +15,24 @@ Inspect a build attachment +## 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 + +### Inspect a provenance attachment from a build + +```console +docker buildx history inspect attachment mybuild --type https://slsa.dev/provenance/v0.2 +``` + +### Inspect a SBOM for linux/amd64 + +```console +docker buildx history inspect attachment mybuild \ + --type application/vnd.cyclonedx+json \ + --platform linux/amd64 +``` diff --git a/docs/reference/buildx_history_logs.md b/docs/reference/buildx_history_logs.md index 5418ce39..687aaece 100644 --- a/docs/reference/buildx_history_logs.md +++ b/docs/reference/buildx_history_logs.md @@ -14,3 +14,34 @@ 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. + +By default, this shows logs for the most recent build on the current builder. + +## Examples + +### Print logs for the most recent build + +```console +docker buildx history logs +``` + +### Print logs for a specific build + +```console +docker buildx history logs mybuild +``` + +### Print logs in JSON format + +```console +docker buildx history logs mybuild --progress rawjson +``` + +### Print logs in TTY format + +```console +docker buildx history logs mybuild --progress tty +``` diff --git a/docs/reference/buildx_history_ls.md b/docs/reference/buildx_history_ls.md index e63224b1..85f88225 100644 --- a/docs/reference/buildx_history_ls.md +++ b/docs/reference/buildx_history_ls.md @@ -17,3 +17,48 @@ 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. + +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 +``` + +### List only failed builds + +```console +docker buildx history ls --filter status=error +``` + +### List builds from the current directory + +```console +docker buildx history ls --local +``` + +### Display full output without truncation + +```console +docker buildx history ls --no-trunc +``` + +### Format output as JSON + +```console +docker buildx history ls --format json +``` + +### Use a Go template to print name and durations + +```console +docker buildx history ls --format '{{.Name}} - {{.Duration}}' +``` diff --git a/docs/reference/buildx_history_open.md b/docs/reference/buildx_history_open.md index 50ed35ff..f0c19cc6 100644 --- a/docs/reference/buildx_history_open.md +++ b/docs/reference/buildx_history_open.md @@ -13,3 +13,20 @@ 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. + +## Examples + +### Open the most recent build in Docker Desktop + +```console +docker buildx history open +``` + +### Open a specific build by name + +```console +docker buildx history open mybuild +``` diff --git a/docs/reference/buildx_history_rm.md b/docs/reference/buildx_history_rm.md index 34bbf14d..75687340 100644 --- a/docs/reference/buildx_history_rm.md +++ b/docs/reference/buildx_history_rm.md @@ -14,3 +14,28 @@ 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 +the `--all` flag. + +## Examples + +### Remove a specific build + +```console +docker buildx history rm mybuild +``` + +### Remove multiple builds + +```console +docker buildx history rm mybuild frontend-build backend-build +``` + +### 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 54362b1a..35bbf2e0 100644 --- a/docs/reference/buildx_history_trace.md +++ b/docs/reference/buildx_history_trace.md @@ -15,3 +15,36 @@ 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. + +This helps analyze build performance, step timing, and internal execution flows. + +## Examples + +### Open the OpenTelemetry trace for the most recent build + +```console +docker buildx history trace +``` + +### Open the trace for a specific build + +```console +docker buildx history trace mybuild +``` + +### Run the Jaeger UI on a specific port + +```console +docker buildx history trace mybuild --addr 127.0.0.1:16686 +``` + +### Compare two build traces + +```console +docker buildx history trace --compare mybuild:main mybuild:feature +```