feedback + updated examples + added links for h3 headings

Author: sarahsanders-docker

docs/reference/buildx_history.md

@@ -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`

docs/reference/buildx_history_export.md

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

docs/reference/buildx_history_import.md

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

docs/reference/buildx_history_inspect.md

@@ -29,17 +29,53 @@ provenance, SBOMs, or other detailed information.
 
 ## Examples
 
-### Inspect a build and print metadata
+### <a name="inspect-most-recent-build"></a> 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/[email protected]?platform=linux%2Famd64        sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037
+pkg:docker/tonistiigi/[email protected]?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)
 
 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)

docs/reference/buildx_history_inspect_attachment.md

@@ -23,16 +23,60 @@ platform-specific.
 
 ## 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
-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": "[email protected]"
+  }
+}
 ```
 
-### Inspect a SBOM for linux/amd64
+### <a name="insepct-SBOM"></a> 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"
+    }
+  ]
+}
+```
+
+### <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.

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
+### <a name="print-logs-recent-build"></a> 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.
+
+### <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
-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
-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
-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
 ```