reference: update buildx reference docs for v0.7.1

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

_data/buildx/docker_buildx.yaml

@@ -1,6 +1,6 @@
 command: docker buildx
-short: Build with BuildKit
+short: Docker Buildx
-long: Build with BuildKit
+long: Extended build capabilities with BuildKit
 pname: docker
 plink: docker.yaml
 cname:
@@ -33,11 +33,16 @@ options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  You can also use the `BUILDX_BUILDER` environment variable.
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_bake.yaml

@@ -4,6 +4,13 @@ short: Build from a file
 long: |-
   Bake is a high-level build command. Each specified target will run in parallel
   as part of the build.
+
+  Read [High-level build options](https://github.com/docker/buildx#high-level-build-options)
+  for introduction.
+
+  Please note that `buildx bake` command may receive backwards incompatible
+  features in the future if needed. We are looking for feedback on improving the
+  command and extending the functionality further.
 usage: docker buildx bake [OPTIONS] [TARGET...]
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -22,7 +29,15 @@ options:
 - option: load
   value_type: bool
   default_value: "false"
-  description: Shorthand for --set=*.output=type=docker
+  description: Shorthand for `--set=*.output=type=docker`
+  deprecated: false
+  experimental: false
+  experimentalcli: false
+  kubernetes: false
+  swarm: false
+- option: metadata-file
+  value_type: string
+  description: Write build result metadata to the file
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -52,7 +67,7 @@ options:
   value_type: string
   default_value: auto
   description: |
-    Set type of progress output (auto, plain, tty). Use plain to show container output
+    Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output
   details_url: '#progress'
   deprecated: false
   experimental: false
@@ -72,7 +87,7 @@ options:
 - option: push
   value_type: bool
   default_value: "false"
-  description: Shorthand for --set=*.output=type=registry
+  description: Shorthand for `--set=*.output=type=registry`
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -81,7 +96,7 @@ options:
 - option: set
   value_type: stringArray
   default_value: '[]'
-  description: 'Override target value (eg: targetpattern.key=value)'
+  description: Override target value (e.g., `targetpattern.key=value`)
   details_url: '#set'
   deprecated: false
   experimental: false
@@ -92,16 +107,21 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
 examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
+
   ### Specify a build definition file (-f, --file) {#file}
 
-  By default, `buildx bake` looks for build definition files in the current directory,
+  By default, `buildx bake` looks for build definition files in the current
-  the following are parsed:
+  directory, the following are parsed:
 
   - `docker-compose.yml`
   - `docker-compose.yaml`
@@ -147,34 +167,157 @@ examples: |-
    ...
   ```
 
+  You can also use a remote `git` bake definition:
+
+  ```console
+  $ docker buildx bake "git://github.com/docker/cli#v20.10.11" --print
+  #1 [internal] load git source git://github.com/docker/cli#v20.10.11
+  #1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7       refs/tags/v20.10.11
+  #1 2.022 From git://github.com/docker/cli
+  #1 2.022  * [new tag]         v20.10.11  -> v20.10.11
+  #1 DONE 2.9s
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "binary"
+        ]
+      }
+    },
+    "target": {
+      "binary": {
+        "context": "git://github.com/docker/cli#v20.10.11",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "BASE_VARIANT": "alpine",
+          "GO_STRIP": "",
+          "VERSION": ""
+        },
+        "target": "binary",
+        "platforms": [
+          "local"
+        ],
+        "output": [
+          "build"
+        ]
+      }
+    }
+  }
+  ```
+
+  As you can see the context is fixed to `git://github.com/docker/cli` even if
+  [no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26)
+  in the definition.
+
+  If you want to access the main context for bake command from a bake file
+  that has been imported remotely, you can use the `BAKE_CMD_CONTEXT` builtin var:
+
+  ```console
+  $ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl
+  target "default" {
+    context = BAKE_CMD_CONTEXT
+    dockerfile-inline = <<EOT
+  FROM alpine
+  WORKDIR /src
+  COPY . .
+  RUN ls -l && stop
+  EOT
+  }
+  ```
+
+  ```console
+  $ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" --print
+  {
+    "target": {
+      "default": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
+      }
+    }
+  }
+  ```
+
+  ```console
+  $ touch foo bar
+  $ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test"
+  ...
+   > [4/4] RUN ls -l && stop:
+  #8 0.101 total 0
+  #8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 bar
+  #8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 foo
+  #8 0.102 /bin/sh: stop: not found
+  ```
+
+  ```console
+  $ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#v20.10.11" --print
+  #1 [internal] load git source git://github.com/tonistiigi/buildx#remote-test
+  #1 0.429 577303add004dd7efeb13434d69ea030d35f7888       refs/heads/remote-test
+  #1 CACHED
+  {
+    "target": {
+      "default": {
+        "context": "git://github.com/docker/cli#v20.10.11",
+        "dockerfile": "Dockerfile",
+        "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
+      }
+    }
+  }
+  ```
+
+  ```console
+  $ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#v20.10.11"
+  ...
+   > [4/4] RUN ls -l && stop:
+  #8 0.136 drwxrwxrwx    5 root     root          4096 Jul 27 18:31 kubernetes
+  #8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 man
+  #8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 opts
+  #8 0.136 -rw-rw-rw-    1 root     root          1893 Jul 27 18:31 poule.yml
+  #8 0.136 drwxrwxrwx    7 root     root          4096 Jul 27 18:31 scripts
+  #8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 service
+  #8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 templates
+  #8 0.136 drwxrwxrwx   10 root     root          4096 Jul 27 18:31 vendor
+  #8 0.136 -rwxrwxrwx    1 root     root          9620 Jul 27 18:31 vendor.conf
+  #8 0.136 /bin/sh: stop: not found
+  ```
+
   ### Do not use cache when building the image (--no-cache) {#no-cache}
 
   Same as `build --no-cache`. Do not use cache when building the image.
 
   ### Print the options without building (--print) {#print}
 
-  Prints the resulting options of the targets desired to be built, in a JSON format,
+  Prints the resulting options of the targets desired to be built, in a JSON
-  without starting a build.
+  format, without starting a build.
 
   ```console
   $ docker buildx bake -f docker-bake.hcl --print db
   {
-     "target": {
+    "group": {
-        "db": {
+      "default": {
-           "context": "./",
+        "targets": [
-           "dockerfile": "Dockerfile",
+          "db"
-           "tags": [
+        ]
-              "docker.io/tiborvass/db"
+      }
-           ]
+    },
-        }
+    "target": {
-     }
+      "db": {
+        "context": "./",
+        "dockerfile": "Dockerfile",
+        "tags": [
+          "docker.io/tiborvass/db"
+        ]
+      }
+    }
   }
   ```
 
   ### Set type of progress output (--progress) {#progress}
 
-  Same as `build --progress`. Set type of progress output (auto, plain, tty). Use
+  Same as [`build --progress`](buildx_build.md#progress). Set type of progress
-  plain to show container output (default "auto").
+  output (auto, plain, tty). Use plain to show container output (default "auto").
+
+  > You can also use the `BUILDKIT_PROGRESS` environment variable to set its value.
 
   The following example uses `plain` output during the build:
 
@@ -203,8 +346,9 @@ examples: |-
   --set targetpattern.key[.subkey]=value
   ```
 
-  Override target configurations from command line. The pattern matching syntax is
+  Override target configurations from command line. The pattern matching syntax
-  defined in https://golang.org/pkg/path/#Match.
+  is defined in https://golang.org/pkg/path/#Match.
+
 
   **Examples**
 
@@ -217,8 +361,8 @@ examples: |-
   ```
 
   Complete list of overridable fields:
-  args, cache-from, cache-to, context, dockerfile, labels, no-cache, output, platform,
+  `args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `labels`, `no-cache`,
-  pull, secrets, ssh, tags, target
+  `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
 
   ### File definition
 
@@ -269,18 +413,101 @@ examples: |-
   `args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `inherits`, `labels`,
   `no-cache`, `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
 
+  ### Global scope attributes
+
+  You can define global scope attributes in HCL/JSON and use them for code reuse
+  and setting values for variables. This means you can do a "data-only" HCL file
+  with the values you want to set/override and use it in the list of regular
+  output files.
+
+  ```hcl
+  # docker-bake.hcl
+  variable "FOO" {
+      default = "abc"
+  }
+
+  target "app" {
+      args = {
+          v1 = "pre-${FOO}"
+      }
+  }
+  ```
+
+  You can use this file directly:
+
+  ```console
+  $ docker buildx bake --print app
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "app"
+        ]
+      }
+    },
+    "target": {
+      "app": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "v1": "pre-abc"
+        }
+      }
+    }
+  }
+  ```
+
+  Or create an override configuration file:
+
+  ```hcl
+  # env.hcl
+  WHOAMI="myuser"
+  FOO="def-${WHOAMI}"
+  ```
+
+  And invoke bake together with both of the files:
+
+  ```console
+  $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "app"
+        ]
+      }
+    },
+    "target": {
+      "app": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "v1": "pre-def-myuser"
+        }
+      }
+    }
+  }
+  ```
+
   ### HCL variables and functions
 
   Similar to how Terraform provides a way to [define variables](https://www.terraform.io/docs/configuration/variables.html#declaring-an-input-variable),
   the HCL file format also supports variable block definitions. These can be used
-  to define variables with values provided by the current environment, or a default
+  to define variables with values provided by the current environment, or a
-  value when unset.
+  default value when unset.
 
+  A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go)
+  provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib)
+  are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc)
+  are also supported.
 
-  Example of using interpolation to tag an image with the git sha:
+  #### Using interpolation to tag an image with the git sha
 
-  ```console
+  Bake supports variable blocks which are assigned to matching environment
-  $ cat <<'EOF' > docker-bake.hcl
+  variables or default values.
+
+  ```hcl
+  # docker-bake.hcl
   variable "TAG" {
       default = "latest"
   }
@@ -292,45 +519,59 @@ examples: |-
   target "webapp" {
       tags = ["docker.io/username/webapp:${TAG}"]
   }
-  EOF
+  ```
 
+  ```console
   $ docker buildx bake --print webapp
   {
-     "target": {
+    "group": {
-        "webapp": {
+      "default": {
-           "context": ".",
+        "targets": [
-           "dockerfile": "Dockerfile",
+          "webapp"
-           "tags": [
+        ]
-              "docker.io/username/webapp:latest"
+      }
-           ]
+    },
-        }
+    "target": {
-     }
+      "webapp": {
-  }
+        "context": ".",
-
+        "dockerfile": "Dockerfile",
-  $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
+        "tags": [
-  {
+          "docker.io/username/webapp:latest"
-     "target": {
+        ]
-        "webapp": {
+      }
-           "context": ".",
+    }
-           "dockerfile": "Dockerfile",
-           "tags": [
-              "docker.io/username/webapp:985e9e9"
-           ]
-        }
-     }
   }
   ```
 
-
-  A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hcl.go#L19-L65)
-  provided by [go-cty](https://github.com/zclconf/go-cty/tree/master/cty/function/stdlib)
-  are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/hcl2/ext/userfunc)
-  are also supported.
-
-  Example of using the `add` function:
-
   ```console
-  $ cat <<'EOF' > docker-bake.hcl
+  $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "webapp"
+        ]
+      }
+    },
+    "target": {
+      "webapp": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "tags": [
+          "docker.io/username/webapp:985e9e9"
+        ]
+      }
+    }
+  }
+  ```
+
+  #### Using the `add` function
+
+  You can use [`go-cty` stdlib functions](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib).
+  Here we are using the `add` function.
+
+  ```hcl
+  # docker-bake.hcl
   variable "TAG" {
       default = "latest"
   }
@@ -344,26 +585,37 @@ examples: |-
           buildno = "${add(123, 1)}"
       }
   }
-  EOF
+  ```
 
+  ```console
   $ docker buildx bake --print webapp
   {
-     "target": {
+    "group": {
-        "webapp": {
+      "default": {
-           "context": ".",
+        "targets": [
-           "dockerfile": "Dockerfile",
+          "webapp"
-           "args": {
+        ]
-              "buildno": "124"
+      }
-           }
+    },
+    "target": {
+      "webapp": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "buildno": "124"
         }
-     }
+      }
+    }
   }
   ```
 
-  Example of defining an `increment` function:
+  #### Defining an `increment` function
 
-  ```console
+  It also supports [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc).
-  $ cat <<'EOF' > docker-bake.hcl
+  The following example defines a simple an `increment` function.
+
+  ```hcl
+  # docker-bake.hcl
   function "increment" {
       params = [number]
       result = number + 1
@@ -378,27 +630,37 @@ examples: |-
           buildno = "${increment(123)}"
       }
   }
-  EOF
+  ```
 
+  ```console
   $ docker buildx bake --print webapp
   {
-     "target": {
+    "group": {
-        "webapp": {
+      "default": {
-           "context": ".",
+        "targets": [
-           "dockerfile": "Dockerfile",
+          "webapp"
-           "args": {
+        ]
-              "buildno": "124"
+      }
-           }
+    },
+    "target": {
+      "webapp": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "buildno": "124"
         }
-     }
+      }
+    }
   }
   ```
 
-  Example of only adding tags if a variable is not empty using an `notequal`
+  #### Only adding tags if a variable is not empty using an `notequal`
-  function:
 
-  ```console
+  Here we are using the conditional `notequal` function which is just for
-  $ cat <<'EOF' > docker-bake.hcl
+  symmetry with the `equal` one.
+
+  ```hcl
+  # docker-bake.hcl
   variable "TAG" {default="" }
 
   group "default" {
@@ -415,21 +677,296 @@ examples: |-
           notequal("",TAG) ? "my-image:${TAG}": "",
       ]
   }
-  EOF
+  ```
 
+  ```console
   $ docker buildx bake --print webapp
   {
-     "target": {
+    "group": {
-        "webapp": {
+      "default": {
-           "context": ".",
+        "targets": [
-           "dockerfile": "Dockerfile",
+          "webapp"
-           "tags": [
+        ]
-              "my-image:latest"
+      }
-           ]
+    },
-        }
+    "target": {
-     }
+      "webapp": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "tags": [
+          "my-image:latest"
+        ]
+      }
+    }
   }
   ```
+
+  #### Using variables in functions
+
+  You can refer variables to other variables like the target blocks can. Stdlib
+  functions can also be called but user functions can't at the moment.
+
+  ```hcl
+  # docker-bake.hcl
+  variable "REPO" {
+      default = "user/repo"
+  }
+
+  function "tag" {
+      params = [tag]
+      result = ["${REPO}:${tag}"]
+  }
+
+  target "webapp" {
+      tags = tag("v1")
+  }
+  ```
+
+  ```console
+  $ docker buildx bake --print webapp
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "webapp"
+        ]
+      }
+    },
+    "target": {
+      "webapp": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "tags": [
+          "user/repo:v1"
+        ]
+      }
+    }
+  }
+  ```
+
+  #### Using variables in variables across files
+
+  When multiple files are specified, one file can use variables defined in
+  another file.
+
+  ```hcl
+  # docker-bake1.hcl
+  variable "FOO" {
+      default = upper("${BASE}def")
+  }
+
+  variable "BAR" {
+      default = "-${FOO}-"
+  }
+
+  target "app" {
+      args = {
+          v1 = "pre-${BAR}"
+      }
+  }
+  ```
+
+  ```hcl
+  # docker-bake2.hcl
+  variable "BASE" {
+      default = "abc"
+  }
+
+  target "app" {
+      args = {
+          v2 = "${FOO}-post"
+      }
+  }
+  ```
+
+  ```console
+  $ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "app"
+        ]
+      }
+    },
+    "target": {
+      "app": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "v1": "pre--ABCDEF-",
+          "v2": "ABCDEF-post"
+        }
+      }
+    }
+  }
+  ```
+
+  #### Using typed variables
+
+  Non-string variables are also accepted. The value passed with env is parsed
+  into suitable type first.
+
+  ```hcl
+  # docker-bake.hcl
+  variable "FOO" {
+      default = 3
+  }
+
+  variable "IS_FOO" {
+      default = true
+  }
+
+  target "app" {
+      args = {
+          v1 = FOO > 5 ? "higher" : "lower"
+          v2 = IS_FOO ? "yes" : "no"
+      }
+  }
+  ```
+
+  ```console
+  $ docker buildx bake --print app
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "app"
+        ]
+      }
+    },
+    "target": {
+      "app": {
+        "context": ".",
+        "dockerfile": "Dockerfile",
+        "args": {
+          "v1": "lower",
+          "v2": "yes"
+        }
+      }
+    }
+  }
+  ```
+
+  ### Extension field with Compose
+
+  [Special extension](https://github.com/compose-spec/compose-spec/blob/master/spec.md#extension)
+  field `x-bake` can be used in your compose file to evaluate fields that are not
+  (yet) available in the [build definition](https://github.com/compose-spec/compose-spec/blob/master/build.md#build-definition).
+
+  ```yaml
+  # docker-compose.yml
+  services:
+    addon:
+      image: ct-addon:bar
+      build:
+        context: .
+        dockerfile: ./Dockerfile
+        args:
+          CT_ECR: foo
+          CT_TAG: bar
+        x-bake:
+          tags:
+            - ct-addon:foo
+            - ct-addon:alp
+          platforms:
+            - linux/amd64
+            - linux/arm64
+          cache-from:
+            - user/app:cache
+            - type=local,src=path/to/cache
+          cache-to: type=local,dest=path/to/cache
+          pull: true
+
+    aws:
+      image: ct-fake-aws:bar
+      build:
+        dockerfile: ./aws.Dockerfile
+        args:
+          CT_ECR: foo
+          CT_TAG: bar
+        x-bake:
+          secret:
+            - id=mysecret,src=./secret
+            - id=mysecret2,src=./secret2
+          platforms: linux/arm64
+          output: type=docker
+          no-cache: true
+  ```
+
+  ```console
+  $ docker buildx bake --print
+  {
+    "group": {
+      "default": {
+        "targets": [
+          "aws",
+          "addon"
+        ]
+      }
+    },
+    "target": {
+      "addon": {
+        "context": ".",
+        "dockerfile": "./Dockerfile",
+        "args": {
+          "CT_ECR": "foo",
+          "CT_TAG": "bar"
+        },
+        "tags": [
+          "ct-addon:foo",
+          "ct-addon:alp"
+        ],
+        "cache-from": [
+          "user/app:cache",
+          "type=local,src=path/to/cache"
+        ],
+        "cache-to": [
+          "type=local,dest=path/to/cache"
+        ],
+        "platforms": [
+          "linux/amd64",
+          "linux/arm64"
+        ],
+        "pull": true
+      },
+      "aws": {
+        "context": ".",
+        "dockerfile": "./aws.Dockerfile",
+        "args": {
+          "CT_ECR": "foo",
+          "CT_TAG": "bar"
+        },
+        "tags": [
+          "ct-fake-aws:bar"
+        ],
+        "secret": [
+          "id=mysecret,src=./secret",
+          "id=mysecret2,src=./secret2"
+        ],
+        "platforms": [
+          "linux/arm64"
+        ],
+        "output": [
+          "type=docker"
+        ],
+        "no-cache": true
+      }
+    }
+  }
+  ```
+
+  Complete list of valid fields for `x-bake`:
+
+  `tags`, `cache-from`, `cache-to`, `secret`, `ssh`, `platforms`, `output`,
+  `pull`, `no-cache`
+
+  ### Built-in variables
+
+  * `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command
+  from a bake file that has been [imported remotely](#file).
+  * `BAKE_LOCAL_PLATFORM` returns the current platform's default platform
+  specification (e.g. `linux/amd64`).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_build.yaml

@@ -15,7 +15,7 @@ options:
 - option: add-host
   value_type: stringSlice
   default_value: '[]'
-  description: Add a custom host-to-IP mapping (host:ip)
+  description: 'Add a custom host-to-IP mapping (format: `host:ip`)'
   details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host
   deprecated: false
   experimental: false
@@ -26,7 +26,7 @@ options:
   value_type: stringSlice
   default_value: '[]'
   description: |
-    Allow extra privileged entitlement, e.g. network.host, security.insecure
+    Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`)
   details_url: '#allow'
   deprecated: false
   experimental: false
@@ -47,7 +47,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: |
-    External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
+    External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`)
   details_url: '#cache-from'
   deprecated: false
   experimental: false
@@ -58,7 +58,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: |
-    Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
+    Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`)
   details_url: '#cache-to'
   deprecated: false
   experimental: false
@@ -68,6 +68,7 @@ options:
 - option: cgroup-parent
   value_type: string
   description: Optional parent cgroup for the container
+  details_url: /engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -112,7 +113,7 @@ options:
   swarm: false
 - option: cpuset-cpus
   value_type: string
-  description: CPUs in which to allow execution (0-3, 0,1)
+  description: CPUs in which to allow execution (`0-3`, `0,1`)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -120,7 +121,7 @@ options:
   swarm: false
 - option: cpuset-mems
   value_type: string
-  description: MEMs in which to allow execution (0-3, 0,1)
+  description: MEMs in which to allow execution (`0-3`, `0,1`)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -129,7 +130,7 @@ options:
 - option: file
   shorthand: f
   value_type: string
-  description: Name of the Dockerfile (Default is 'PATH/Dockerfile')
+  description: 'Name of the Dockerfile (default: `PATH/Dockerfile`)'
   details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f
   deprecated: false
   experimental: false
@@ -173,7 +174,7 @@ options:
 - option: load
   value_type: bool
   default_value: "false"
-  description: Shorthand for --output=type=docker
+  description: Shorthand for `--output=type=docker`
   details_url: '#load'
   deprecated: false
   experimental: false
@@ -192,7 +193,15 @@ options:
 - option: memory-swap
   value_type: string
   description: |
-    Swap limit equal to memory plus swap: '-1' to enable unlimited swap
+    Swap limit equal to memory plus swap: `-1` to enable unlimited swap
+  deprecated: false
+  experimental: false
+  experimentalcli: false
+  kubernetes: false
+  swarm: false
+- option: metadata-file
+  value_type: string
+  description: Write build result metadata to the file
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -201,8 +210,7 @@ options:
 - option: network
   value_type: string
   default_value: default
-  description: |
+  description: Set the networking mode for the RUN instructions during build
-    Set the networking mode for the RUN instructions during build
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -221,7 +229,7 @@ options:
   shorthand: o
   value_type: stringArray
   default_value: '[]'
-  description: 'Output destination (format: type=local,dest=path)'
+  description: 'Output destination (format: `type=local,dest=path`)'
   details_url: '#output'
   deprecated: false
   experimental: false
@@ -242,7 +250,8 @@ options:
   value_type: string
   default_value: auto
   description: |
-    Set type of progress output (auto, plain, tty). Use plain to show container output
+    Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output
+  details_url: '#progress'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -260,7 +269,7 @@ options:
 - option: push
   value_type: bool
   default_value: "false"
-  description: Shorthand for --output=type=registry
+  description: Shorthand for `--output=type=registry`
   details_url: '#push'
   deprecated: false
   experimental: false
@@ -290,7 +299,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: |
-    Secret file to expose to the build: id=mysecret,src=/local/secret
+    Secret file to expose to the build (format: `id=mysecret,src=/local/secret`)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -306,8 +315,10 @@ options:
   kubernetes: false
   swarm: false
 - option: shm-size
-  value_type: string
+  value_type: bytes
-  description: Size of /dev/shm
+  default_value: "0"
+  description: Size of `/dev/shm`
+  details_url: '#shm-size'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -326,7 +337,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: |
-    SSH agent socket or keys to expose to the build (format: default|<id>[=<socket>|<key>[,<key>]])
+    SSH agent socket or keys to expose to the build (format: `default|<id>[=<socket>|<key>[,<key>]]`)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -336,7 +347,7 @@ options:
   shorthand: t
   value_type: stringArray
   default_value: '[]'
-  description: Name and optionally a tag in the 'name:tag' format
+  description: 'Name and optionally a tag (format: `name:tag`)'
   details_url: /engine/reference/commandline/build/#tag-an-image--t
   deprecated: false
   experimental: false
@@ -353,8 +364,10 @@ options:
   kubernetes: false
   swarm: false
 - option: ulimit
-  value_type: string
+  value_type: ulimit
+  default_value: '[]'
   description: Ulimit options
+  details_url: '#ulimit'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -364,12 +377,17 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
 examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
+
   ### Set the target platforms for the build (--platform) {#platform}
 
   ```
@@ -411,6 +429,33 @@ examples: |-
   $ docker buildx build --platform=darwin .
   ```
 
+  ### Set type of progress output (--progress) {#progress}
+
+  ```
+  --progress=VALUE
+  ```
+
+  Set type of progress output (auto, plain, tty). Use plain to show container
+  output (default "auto").
+
+  > You can also use the `BUILDKIT_PROGRESS` environment variable to set
+  > its value.
+
+  The following example uses `plain` output during the build:
+
+  ```console
+  $ docker buildx build --load --progress=plain .
+
+  #1 [internal] load build definition from Dockerfile
+  #1 transferring dockerfile: 227B 0.0s done
+  #1 DONE 0.1s
+
+  #2 [internal] load .dockerignore
+  #2 transferring context: 129B 0.0s done
+  #2 DONE 0.0s
+  ...
+  ```
+
   ### Set the export action for the build result (-o, --output) {#output}
 
   ```
@@ -519,10 +564,17 @@ examples: |-
   --cache-from=[NAME|type=TYPE[,KEY=VALUE]]
   ```
 
-  Use an external cache source for a build. Supported types are `registry` and `local`.
+  Use an external cache source for a build. Supported types are `registry`,
-  The `registry` source can import cache from a cache manifest or (special) image
+  `local` and `gha`.
-  configuration on the registry. The `local` source can import cache from local
+
-  files previously exported with `--cache-to`.
+  - [`registry` source](https://github.com/moby/buildkit#registry-push-image-and-cache-separately)
+  can import cache from a cache manifest or (special) image configuration on the
+  registry.
+  - [`local` source](https://github.com/moby/buildkit#local-directory-1) can
+  import cache from local files previously exported with `--cache-to`.
+  - [`gha` source](https://github.com/moby/buildkit#github-actions-cache-experimental)
+  can import cache from a previously exported cache with `--cache-to` in your
+  GitHub repository
 
   If no type is specified, `registry` exporter is used with a specified reference.
 
@@ -535,18 +587,27 @@ examples: |-
   $ docker buildx build --cache-from=user/app .
   $ docker buildx build --cache-from=type=registry,ref=user/app .
   $ docker buildx build --cache-from=type=local,src=path/to/cache .
+  $ docker buildx build --cache-from=type=gha .
   ```
 
+  More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
+
   ### Export build cache to an external cache destination (--cache-to) {#cache-to}
 
   ```
   --cache-to=[NAME|type=TYPE[,KEY=VALUE]]
   ```
 
-  Export build cache to an external cache destination. Supported types are `registry`,
+  Export build cache to an external cache destination. Supported types are
-  `local` and `inline`. Registry exports build cache to a cache manifest in the
+  `registry`, `local`, `inline` and `gha`.
-  registry, local exports cache to a local directory on the client and inline writes
+
-  the cache metadata into the image configuration.
+  - [`registry` type](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) exports build cache to a cache manifest in the registry.
+  - [`local` type](https://github.com/moby/buildkit#local-directory-1) type
+  exports cache to a local directory on the client.
+  - [`inline` type](https://github.com/moby/buildkit#inline-push-image-and-cache-together)
+  type writes the cache metadata into the image configuration.
+  - [`gha` type](https://github.com/moby/buildkit#github-actions-cache-experimental)
+  type exports cache through the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication).
 
   `docker` driver currently only supports exporting inline cache metadata to image
   configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used
@@ -554,8 +615,8 @@ examples: |-
 
   Attribute key:
 
-  - `mode` - Specifies how many layers are exported with the cache. “min” on only
+  - `mode` - Specifies how many layers are exported with the cache. `min` on only
-  exports layers already in the final build stage, “max” exports layers for
+  exports layers already in the final build stage, `max` exports layers for
   all stages. Metadata is always exported for the whole build.
 
   **Examples**
@@ -565,8 +626,11 @@ examples: |-
   $ docker buildx build --cache-to=type=inline .
   $ docker buildx build --cache-to=type=registry,ref=user/app .
   $ docker buildx build --cache-to=type=local,dest=path/to/cache .
+  $ docker buildx build --cache-to=type=gha .
   ```
 
+  More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
+
   ### Allow extra privileged entitlement (--allow) {#allow}
 
   ```
@@ -588,6 +652,27 @@ examples: |-
   $ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
   $ docker buildx build --allow security.insecure .
   ```
+
+  ### Size of `/dev/shm` (--shm-size) {#shm-size}
+
+  The format is `<number><unit>`. `number` must be greater than `0`. Unit is
+  optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`
+  (gigabytes). If you omit the unit, the system uses bytes.
+
+  ### Set ulimits (--ulimit) {#ulimit}
+
+  `--ulimit` is specified with a soft and hard limit as such:
+  `<type>=<soft limit>[:<hard limit>]`, for example:
+
+  ```console
+  $ docker buildx build --ulimit nofile=1024:1024 .
+  ```
+
+  > **Note**
+  >
+  > If you do not provide a `hard limit`, the `soft limit` is used
+  > for both values. If no `ulimits` are set, they are inherited from
+  > the default `ulimits` set on the daemon.
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_create.yaml

@@ -24,6 +24,15 @@ options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+- option: bootstrap
+  value_type: bool
+  default_value: "false"
+  description: Boot builder after creation
+  deprecated: false
+  experimental: false
+  experimentalcli: false
+  kubernetes: false
+  swarm: false
 - option: buildkitd-flags
   value_type: string
   description: Flags for buildkitd daemon
@@ -44,7 +53,8 @@ options:
   swarm: false
 - option: driver
   value_type: string
-  description: 'Driver to use (available: [])'
+  description: |
+    Driver to use (available: `docker`, `docker-container`, `kubernetes`)
   details_url: '#driver'
   deprecated: false
   experimental: false
@@ -161,6 +171,11 @@ examples: |-
   can be overridden by [`--buildkitd-flags`](#buildkitd-flags).
   See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md).
 
+  Note that if you create a `docker-container` builder and have specified
+  certificates for registries in the `buildkitd.toml` configuration, the files
+  will be copied into the container under `/etc/buildkit/certs` and configuration
+  will be updated to reflect that.
+
   ### Set the builder driver to use (--driver) {#driver}
 
   ```
@@ -170,17 +185,30 @@ examples: |-
   Sets the builder driver to be used. There are two available drivers, each have
   their own specificities.
 
-  - `docker` - Uses the builder that is built into the docker daemon. With this
+  #### `docker` driver
-    driver, the [`--load`](buildx_build.md#load) flag is implied by default on
-    `buildx build`. However, building multi-platform images or exporting cache is
-    not currently supported.
-  - `docker-container` - Uses a buildkit container that will be spawned via docker.
-    With this driver, both building multi-platform images and exporting cache are
-    supported. However, images built will not automatically appear in `docker images`
-    (see [`build --load`](buildx_build.md#load)).
-  - `kubernetes` - Uses a kubernetes pods. With this driver, you can spin up pods
-    with defined buildkit container image to build your images.
 
+  Uses the builder that is built into the docker daemon. With this driver,
+  the [`--load`](buildx_build.md#load) flag is implied by default on
+  `buildx build`. However, building multi-platform images or exporting cache is
+  not currently supported.
+
+  #### `docker-container` driver
+
+  Uses a BuildKit container that will be spawned via docker. With this driver,
+  both building multi-platform images and exporting cache are supported.
+
+  Unlike `docker` driver, built images will not automatically appear in
+  `docker images` and [`build --load`](buildx_build.md#load) needs to be used
+  to achieve that.
+
+  #### `kubernetes` driver
+
+  Uses a kubernetes pods. With this driver, you can spin up pods with defined
+  BuildKit container image to build your images.
+
+  Unlike `docker` driver, built images will not automatically appear in
+  `docker images` and [`build --load`](buildx_build.md#load) needs to be used
+  to achieve that.
 
   ### Set additional driver-specific options (--driver-opt) {#driver-opt}
 
@@ -194,18 +222,44 @@ examples: |-
   - `docker-container`
       - `image=IMAGE` - Sets the container image to be used for running buildkit.
       - `network=NETMODE` - Sets the network mode for running the buildkit container.
-      - Example:
+      - `cgroup-parent=CGROUP` - Sets the cgroup parent of the buildkit container if docker is using the "cgroupfs" driver. Defaults to `/docker/buildx`.
-
-        ```console
-        --driver docker-container --driver-opt image=moby/buildkit:master,network=host
-        ```
   - `kubernetes`
       - `image=IMAGE` - Sets the container image to be used for running buildkit.
       - `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace.
       - `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1.
+      - `requests.cpu` - Sets the request CPU value specified in units of Kubernetes CPU. Example `requests.cpu=100m`, `requests.cpu=2`
+      - `requests.memory` - Sets the request memory value specified in bytes or with a valid suffix. Example `requests.memory=500Mi`, `requests.memory=4G`
+      - `limits.cpu` - Sets the limit CPU value specified in units of Kubernetes CPU. Example `limits.cpu=100m`, `limits.cpu=2`
+      - `limits.memory` - Sets the limit memory value specified in bytes or with a valid suffix. Example `limits.memory=500Mi`, `limits.memory=4G`
       - `nodeselector="label1=value1,label2=value2"` - Sets the kv of `Pod` nodeSelector. No Defaults. Example `nodeselector=kubernetes.io/arch=arm64`
       - `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false.
       - `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky"
+      - `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support.
+      - `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest`
+
+  **Examples**
+
+  #### Use a custom network
+
+  ```console
+  $ docker network create foonet
+  $ docker buildx create --name builder --driver docker-container --driver-opt network=foonet --use
+  $ docker buildx inspect --bootstrap
+  $ docker inspect buildx_buildkit_builder0 --format={{.NetworkSettings.Networks}}
+  map[foonet:0xc00018c0c0]
+  ```
+
+  #### OpenTelemetry support
+
+  To capture the trace to [Jaeger](https://github.com/jaegertracing/jaeger), set
+  `JAEGER_TRACE` environment variable to the collection address using the `driver-opt`:
+
+  ```console
+  $ docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one
+  $ docker buildx create --name builder --driver docker-container --driver-opt network=host --driver-opt env.JAEGER_TRACE=localhost:6831 --use
+  $ docker buildx inspect --bootstrap
+  # buildx command should be traced at http://127.0.0.1:16686/
+  ```
 
   ### Remove a node from a builder (--leave) {#leave}
 

_data/buildx/docker_buildx_du.yaml

@@ -26,11 +26,16 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_imagetools.yaml

@@ -15,11 +15,16 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_imagetools_create.yaml

@@ -58,6 +58,7 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -69,6 +70,10 @@ examples: |-
   Use the `--append` flag to append the new sources to an existing manifest list
   in the destination.
 
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
+
   ### Show final image instead of pushing (--dry-run) {#dry-run}
 
   Use the `--dry-run` flag to not push the image, just show it.
@@ -82,6 +87,19 @@ examples: |-
   Reads source from files. A source can be a manifest digest, manifest reference,
   or a JSON of OCI descriptor object.
 
+  In order to define annotations or additional platform properties like `os.version` and
+  `os.features` you need to add them in the OCI descriptor object encoded in JSON.
+
+  ```
+  docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json
+  docker buildx imagetools create -f descr.json myuser/image
+  ```
+
+  The descriptor in the file is merged with existing descriptor in the registry if it exists.
+
+  The supported fields for the descriptor are defined in [OCI spec](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) .
+
+
   ### Set reference for new image  (-t, --tag) {#tag}
 
   ```

_data/buildx/docker_buildx_imagetools_inspect.yaml

@@ -22,11 +22,6 @@ long: |-
     Platform:  linux/arm/v6
    ...
   ```
-
-  ### Show original, unformatted JSON manifest (--raw) {#raw}
-
-  Use the `--raw` option to print the original JSON bytes instead of the formatted
-  output.
 usage: docker buildx imagetools inspect [OPTIONS] NAME
 pname: docker buildx imagetools
 plink: docker_buildx_imagetools.yaml
@@ -45,11 +40,21 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
+
+  ### Show original, unformatted JSON manifest (--raw) {#raw}
+
+  Use the `--raw` option to print the original JSON bytes instead of the formatted
+  output.
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_inspect.yaml

@@ -19,12 +19,26 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
 examples: |-
+  ### Ensure that the builder is running before inspecting (--bootstrap) {#bootstrap}
+
+  Use the `--bootstrap` option to ensure that the builder is running before
+  inspecting it. If the driver is `docker-container`, then `--bootstrap` starts
+  the buildkit container and waits until it is operational. Bootstrapping is
+  automatically done during build, and therefore not necessary. The same BuildKit
+  container is used during the lifetime of the associated builder node (as
+  displayed in `buildx ls`).
+
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
+
   ### Get information about a builder instance
 
   By default, `inspect` shows information about the current builder. Specify the
@@ -49,15 +63,6 @@ examples: |-
   Status:    running
   Platforms: linux/arm64, linux/arm/v7, linux/arm/v6
   ```
-
-  ### Ensure that the builder is running before inspecting (--bootstrap) {#bootstrap}
-
-  Use the `--bootstrap` option to ensure that the builder is running before
-  inspecting it. If the driver is `docker-container`, then `--bootstrap` starts
-  the buildkit container and waits until it is operational. Bootstrapping is
-  automatically done during build, and therefore not necessary. The same BuildKit
-  container is used during the lifetime of the associated builder node (as
-  displayed in `buildx ls`).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_prune.yaml

@@ -17,7 +17,7 @@ options:
   swarm: false
 - option: filter
   value_type: filter
-  description: Provide filter values (e.g. 'until=24h')
+  description: Provide filter values (e.g., `until=24h`)
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -55,11 +55,16 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_rm.yaml

@@ -6,15 +6,36 @@ long: |-
 usage: docker buildx rm [NAME]
 pname: docker buildx
 plink: docker_buildx.yaml
-inherited_options:
+options:
-- option: builder
+- option: keep-state
-  value_type: string
+  value_type: bool
-  description: Override the configured builder instance
+  default_value: "false"
+  description: Keep BuildKit state
+  details_url: '#keep-state'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+inherited_options:
+- option: builder
+  value_type: string
+  description: Override the configured builder instance
+  details_url: '#builder'
+  deprecated: false
+  experimental: false
+  experimentalcli: false
+  kubernetes: false
+  swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
+
+  ### Keep BuildKit state (--keep-state) {#keep-state}
+
+  Keep BuildKit state, so it can be reused by a new builder with the same name.
+  Currently, only supported by the [`docker-container` driver](buildx_create.md#driver).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_stop.yaml

@@ -10,11 +10,16 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
 deprecated: false
 experimental: false
 experimentalcli: false

_data/buildx/docker_buildx_use.yaml

@@ -30,11 +30,16 @@ inherited_options:
 - option: builder
   value_type: string
   description: Override the configured builder instance
+  details_url: '#builder'
   deprecated: false
   experimental: false
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Override the configured builder instance (--builder) {#builder}
+
+  Same as [`buildx --builder`](buildx.md#builder).
 deprecated: false
 experimental: false
 experimentalcli: false