Add descriptions and examples for buildx history commands

Signed-off-by: sarahsanders-docker <sarah.sanders@docker.com>

Author: sarahsanders-docker

docs/reference/buildx_history_export.md

@@ -15,3 +15,31 @@ Export a build into Docker Desktop bundle
 
 <!---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
+
+### 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
+```

docs/reference/buildx_history_import.md

@@ -14,3 +14,28 @@ Import a build into Docker Desktop
 
 <!---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 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
+```

docs/reference/buildx_history_inspect.md

@@ -21,8 +21,20 @@ 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 a build and print metadata
+
+```console
+docker buildx history inspect mybuild
+```
+
 ### <a name="format"></a> Format the output (--format)
 
 The formatting options (`--format`) pretty-prints the output to `pretty` (default),

docs/reference/buildx_history_inspect_attachment.md

@@ -15,3 +15,24 @@ Inspect a build 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
+
+### 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
+```

docs/reference/buildx_history_logs.md

@@ -14,3 +14,34 @@ Print the logs of a build
 
 <!---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 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
+```

docs/reference/buildx_history_ls.md

@@ -17,3 +17,48 @@ List build records
 
 <!---MARKER_GEN_END-->
 
+## 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}}'
+```

docs/reference/buildx_history_open.md

@@ -13,3 +13,20 @@ 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
+```
+
+### Open a specific build by name
+
+```console
+docker buildx history open mybuild
+```

docs/reference/buildx_history_rm.md

@@ -14,3 +14,28 @@ 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 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
+```

docs/reference/buildx_history_trace.md

@@ -15,3 +15,36 @@ Show the OpenTelemetry trace of a build record
 
 <!---MARKER_GEN_END-->
 
+## 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
+```