diff --git a/cli/command/image/build.go b/cli/command/image/build.go
index 409b6cda18..cb5292be85 100644
--- a/cli/command/image/build.go
+++ b/cli/command/image/build.go
@@ -15,6 +15,7 @@ import (
"strings"
"github.com/distribution/reference"
+ "github.com/docker/cli-docs-tool/annotation"
"github.com/docker/cli/cli"
"github.com/docker/cli/cli/command"
"github.com/docker/cli/cli/command/image/build"
@@ -104,7 +105,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
},
Annotations: map[string]string{
"category-top": "4",
- "aliases": "docker image build, docker build, docker buildx build, docker builder build",
+ "aliases": "docker image build, docker build, docker builder build",
},
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
return nil, cobra.ShellCompDirectiveFilterDirs
@@ -114,9 +115,12 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags := cmd.Flags()
flags.VarP(&options.tags, "tag", "t", `Name and optionally a tag in the "name:tag" format`)
+ flags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#tag"})
flags.Var(&options.buildArgs, "build-arg", "Set build-time variables")
+ flags.SetAnnotation("build-arg", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg"})
flags.Var(options.ulimits, "ulimit", "Ulimit options")
flags.StringVarP(&options.dockerfileName, "file", "f", "", `Name of the Dockerfile (Default is "PATH/Dockerfile")`)
+ flags.SetAnnotation("file", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#file"})
flags.VarP(&options.memory, "memory", "m", "Memory limit")
flags.Var(&options.memorySwap, "memory-swap", `Swap limit equal to memory plus swap: -1 to enable unlimited swap`)
flags.Var(&options.shmSize, "shm-size", `Size of "/dev/shm"`)
@@ -126,6 +130,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags.StringVar(&options.cpuSetCpus, "cpuset-cpus", "", "CPUs in which to allow execution (0-3, 0,1)")
flags.StringVar(&options.cpuSetMems, "cpuset-mems", "", "MEMs in which to allow execution (0-3, 0,1)")
flags.StringVar(&options.cgroupParent, "cgroup-parent", "", `Set the parent cgroup for the "RUN" instructions during build`)
+ flags.SetAnnotation("cgroup-parent", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent"})
flags.StringVar(&options.isolation, "isolation", "", "Container isolation technology")
flags.Var(&options.labels, "label", "Set metadata for an image")
flags.BoolVar(&options.noCache, "no-cache", false, "Do not use cache when building the image")
@@ -138,8 +143,11 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
flags.StringSliceVar(&options.securityOpt, "security-opt", []string{}, "Security options")
flags.StringVar(&options.networkMode, "network", "default", "Set the networking mode for the RUN instructions during build")
flags.SetAnnotation("network", "version", []string{"1.25"})
+ flags.SetAnnotation("network", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#network"})
flags.Var(&options.extraHosts, "add-host", `Add a custom host-to-IP mapping ("host:ip")`)
+ flags.SetAnnotation("add-host", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#add-host"})
flags.StringVar(&options.target, "target", "", "Set the target build stage to build.")
+ flags.SetAnnotation("target", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#target"})
flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to the file")
command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md
index c0dd7a6768..e2f4765a44 100644
--- a/docs/reference/commandline/build.md
+++ b/docs/reference/commandline/build.md
@@ -5,42 +5,42 @@ Build an image from a Dockerfile
### Aliases
-`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
+`docker image build`, `docker build`, `docker builder build`
### Options
-| Name | Type | Default | Description |
-|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
-| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
-| `--build-arg` | `list` | | Set build-time variables |
-| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
-| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build |
-| `--compress` | | | Compress the build context using gzip |
-| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
-| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
-| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
-| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
-| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
-| `--disable-content-trust` | `bool` | `true` | Skip image verification |
-| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
-| `--force-rm` | | | Always remove intermediate containers |
-| `--iidfile` | `string` | | Write the image ID to the file |
-| `--isolation` | `string` | | Container isolation technology |
-| `--label` | `list` | | Set metadata for an image |
-| `-m`, `--memory` | `bytes` | `0` | Memory limit |
-| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
-| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build |
-| `--no-cache` | | | Do not use cache when building the image |
-| `--platform` | `string` | | Set platform if server is multi-platform capable |
-| `--pull` | | | Always attempt to pull a newer version of the image |
-| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
-| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
-| `--security-opt` | `stringSlice` | | Security options |
-| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
-| `--squash` | | | Squash newly built layers into a single new layer |
-| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format |
-| `--target` | `string` | | Set the target build stage to build. |
-| `--ulimit` | `ulimit` | | Ulimit options |
+| Name | Type | Default | Description |
+|:-----------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
+| [`--add-host`](https://docs.docker.com/reference/cli/docker/buildx/build/#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
+| [`--build-arg`](https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg) | `list` | | Set build-time variables |
+| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
+| [`--cgroup-parent`](https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
+| `--compress` | | | Compress the build context using gzip |
+| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
+| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
+| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
+| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
+| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
+| `--disable-content-trust` | `bool` | `true` | Skip image verification |
+| [`-f`](https://docs.docker.com/reference/cli/docker/buildx/build/#file), [`--file`](https://docs.docker.com/reference/cli/docker/buildx/build/#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
+| `--force-rm` | | | Always remove intermediate containers |
+| `--iidfile` | `string` | | Write the image ID to the file |
+| `--isolation` | `string` | | Container isolation technology |
+| `--label` | `list` | | Set metadata for an image |
+| `-m`, `--memory` | `bytes` | `0` | Memory limit |
+| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
+| [`--network`](https://docs.docker.com/reference/cli/docker/buildx/build/#network) | `string` | `default` | Set the networking mode for the RUN instructions during build |
+| `--no-cache` | | | Do not use cache when building the image |
+| `--platform` | `string` | | Set platform if server is multi-platform capable |
+| `--pull` | | | Always attempt to pull a newer version of the image |
+| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
+| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
+| `--security-opt` | `stringSlice` | | Security options |
+| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
+| `--squash` | | | Squash newly built layers into a single new layer |
+| [`-t`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
+| [`--target`](https://docs.docker.com/reference/cli/docker/buildx/build/#target) | `string` | | Set the target build stage to build. |
+| `--ulimit` | `ulimit` | | Ulimit options |
diff --git a/docs/reference/commandline/builder_build.md b/docs/reference/commandline/builder_build.md
index b972d573fa..53da887d9c 100644
--- a/docs/reference/commandline/builder_build.md
+++ b/docs/reference/commandline/builder_build.md
@@ -5,42 +5,42 @@ Build an image from a Dockerfile
### Aliases
-`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
+`docker image build`, `docker build`, `docker builder build`
### Options
-| Name | Type | Default | Description |
-|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
-| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
-| `--build-arg` | `list` | | Set build-time variables |
-| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
-| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build |
-| `--compress` | | | Compress the build context using gzip |
-| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
-| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
-| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
-| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
-| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
-| `--disable-content-trust` | `bool` | `true` | Skip image verification |
-| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
-| `--force-rm` | | | Always remove intermediate containers |
-| `--iidfile` | `string` | | Write the image ID to the file |
-| `--isolation` | `string` | | Container isolation technology |
-| `--label` | `list` | | Set metadata for an image |
-| `-m`, `--memory` | `bytes` | `0` | Memory limit |
-| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
-| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build |
-| `--no-cache` | | | Do not use cache when building the image |
-| `--platform` | `string` | | Set platform if server is multi-platform capable |
-| `--pull` | | | Always attempt to pull a newer version of the image |
-| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
-| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
-| `--security-opt` | `stringSlice` | | Security options |
-| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
-| `--squash` | | | Squash newly built layers into a single new layer |
-| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format |
-| `--target` | `string` | | Set the target build stage to build. |
-| `--ulimit` | `ulimit` | | Ulimit options |
+| Name | Type | Default | Description |
+|:-----------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
+| [`--add-host`](https://docs.docker.com/reference/cli/docker/buildx/build/#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
+| [`--build-arg`](https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg) | `list` | | Set build-time variables |
+| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
+| [`--cgroup-parent`](https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
+| `--compress` | | | Compress the build context using gzip |
+| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
+| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
+| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
+| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
+| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
+| `--disable-content-trust` | `bool` | `true` | Skip image verification |
+| [`-f`](https://docs.docker.com/reference/cli/docker/buildx/build/#file), [`--file`](https://docs.docker.com/reference/cli/docker/buildx/build/#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
+| `--force-rm` | | | Always remove intermediate containers |
+| `--iidfile` | `string` | | Write the image ID to the file |
+| `--isolation` | `string` | | Container isolation technology |
+| `--label` | `list` | | Set metadata for an image |
+| `-m`, `--memory` | `bytes` | `0` | Memory limit |
+| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
+| [`--network`](https://docs.docker.com/reference/cli/docker/buildx/build/#network) | `string` | `default` | Set the networking mode for the RUN instructions during build |
+| `--no-cache` | | | Do not use cache when building the image |
+| `--platform` | `string` | | Set platform if server is multi-platform capable |
+| `--pull` | | | Always attempt to pull a newer version of the image |
+| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
+| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
+| `--security-opt` | `stringSlice` | | Security options |
+| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
+| `--squash` | | | Squash newly built layers into a single new layer |
+| [`-t`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
+| [`--target`](https://docs.docker.com/reference/cli/docker/buildx/build/#target) | `string` | | Set the target build stage to build. |
+| `--ulimit` | `ulimit` | | Ulimit options |
diff --git a/docs/reference/commandline/image_build.md b/docs/reference/commandline/image_build.md
index bae3c5a900..a971d12967 100644
--- a/docs/reference/commandline/image_build.md
+++ b/docs/reference/commandline/image_build.md
@@ -1,439 +1,125 @@
-# build
+# build (legacy builder)
Build an image from a Dockerfile
### Aliases
-`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
+`docker image build`, `docker build`, `docker builder build`
### Options
-| Name | Type | Default | Description |
-|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
-| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
-| [`--build-arg`](#build-arg) | `list` | | Set build-time variables |
-| [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources |
-| [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
-| `--compress` | | | Compress the build context using gzip |
-| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
-| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
-| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
-| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
-| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
-| `--disable-content-trust` | `bool` | `true` | Skip image verification |
-| [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
-| `--force-rm` | | | Always remove intermediate containers |
-| `--iidfile` | `string` | | Write the image ID to the file |
-| [`--isolation`](#isolation) | `string` | | Container isolation technology |
-| `--label` | `list` | | Set metadata for an image |
-| `-m`, `--memory` | `bytes` | `0` | Memory limit |
-| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
-| [`--network`](#network) | `string` | `default` | Set the networking mode for the RUN instructions during build |
-| `--no-cache` | | | Do not use cache when building the image |
-| `--platform` | `string` | | Set platform if server is multi-platform capable |
-| `--pull` | | | Always attempt to pull a newer version of the image |
-| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
-| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
-| [`--security-opt`](#security-opt) | `stringSlice` | | Security options |
-| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
-| [`--squash`](#squash) | | | Squash newly built layers into a single new layer |
-| [`-t`](#tag), [`--tag`](#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
-| [`--target`](#target) | `string` | | Set the target build stage to build. |
-| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options |
+| Name | Type | Default | Description |
+|:-----------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
+| [`--add-host`](https://docs.docker.com/reference/cli/docker/buildx/build/#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
+| [`--build-arg`](https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg) | `list` | | Set build-time variables |
+| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
+| [`--cgroup-parent`](https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
+| `--compress` | | | Compress the build context using gzip |
+| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
+| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
+| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
+| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
+| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
+| `--disable-content-trust` | `bool` | `true` | Skip image verification |
+| [`-f`](https://docs.docker.com/reference/cli/docker/buildx/build/#file), [`--file`](https://docs.docker.com/reference/cli/docker/buildx/build/#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
+| `--force-rm` | | | Always remove intermediate containers |
+| `--iidfile` | `string` | | Write the image ID to the file |
+| [`--isolation`](#isolation) | `string` | | Container isolation technology |
+| `--label` | `list` | | Set metadata for an image |
+| `-m`, `--memory` | `bytes` | `0` | Memory limit |
+| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
+| [`--network`](https://docs.docker.com/reference/cli/docker/buildx/build/#network) | `string` | `default` | Set the networking mode for the RUN instructions during build |
+| `--no-cache` | | | Do not use cache when building the image |
+| `--platform` | `string` | | Set platform if server is multi-platform capable |
+| `--pull` | | | Always attempt to pull a newer version of the image |
+| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
+| `--rm` | `bool` | `true` | Remove intermediate containers after a successful build |
+| [`--security-opt`](#security-opt) | `stringSlice` | | Security options |
+| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
+| [`--squash`](#squash) | | | Squash newly built layers into a single new layer |
+| [`-t`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag), [`--tag`](https://docs.docker.com/reference/cli/docker/buildx/build/#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
+| [`--target`](https://docs.docker.com/reference/cli/docker/buildx/build/#target) | `string` | | Set the target build stage to build. |
+| `--ulimit` | `ulimit` | | Ulimit options |
## Description
-The `docker build` command builds Docker images from a Dockerfile and a
-"context". A build's context is the set of files located in the specified
-`PATH` or `URL`. The build process can refer to any of the files in the
-context. For example, your build can use a [*COPY*](https://docs.docker.com/reference/dockerfile/#copy)
-instruction to reference a file in the context.
-
-The `URL` parameter can refer to three kinds of resources: Git repositories,
-pre-packaged tarball contexts, and plain text files.
-
-### Git repositories
-
-When the `URL` parameter points to the location of a Git repository, the
-repository acts as the build context. The system recursively fetches the
-repository and its submodules. The commit history isn't preserved. A
-repository is first pulled into a temporary directory on your local host. After
-that succeeds, the command sends the directory to the Docker daemon as the context.
-Local copy gives you the ability to access private repositories using local
-user credentials, VPNs, and so forth.
-
> **Note**
>
-> If the `URL` parameter contains a fragment the system recursively clones
-> the repository and its submodules.
+> This page refers to the **legacy implementation** of `docker build`,
+> using the legacy (pre-BuildKit) build backend.
+> This configuration is only relevant if you're building Windows containers.
+>
+> For information about the default `docker build`, using Buildx,
+> see [`docker buildx build`](https://docs.docker.com/reference/cli/docker/build/).
-Git URLs accept context configuration in their fragment section, separated by a
-colon (`:`). The first part represents the reference that Git checks out,
-and can be either a branch, a tag, or a remote reference. The second part
-represents a subdirectory inside the repository used as a build
-context.
+When building with legacy builder, images are created from a Dockerfile by
+running a sequence of [commits](./container_commit.md). This process is
+inefficient and slow compared to using BuildKit, which is why this build
+strategy is deprecated for all use cases except for building Windows
+containers. It's still useful for building Windows containers because BuildKit
+doesn't yet have full feature parity for Windows.
-For example, run this command to use a directory called `docker` in the branch
-`container`:
+Builds invoked with `docker build` use Buildx (and BuildKit) by default, unless:
+
+- You're running Docker Engine in Windows container mode
+- You explicitly opt out of using BuildKit by setting the environment variable `DOCKER_BUILDKIT=0`.
+
+The descriptions on this page only covers information that's exclusive to the
+legacy builder, and cases where behavior in the legacy builder deviates from
+behavior in BuildKit. For information about features and flags that are common
+between the legacy builder and BuildKit, such as `--tag` and `--target`, refer
+to the documentation for [`docker buildx build`](https://docs.docker.com/reference/cli/docker/buildx/build/).
+
+### Build context with the legacy builder
+
+The build context is the positional argument you pass when invoking the build
+command. In the following example, the context is `.`, meaning current the
+working directory.
```console
-$ docker build https://github.com/docker/rootfs.git#container:docker
+$ docker build .
```
-The following table represents all the valid suffixes with their build
-contexts:
+When using the legacy builder, the build context is sent over to the daemon in
+its entirety. With BuildKit, only the files you use in your builds are
+transmitted. The legacy builder doesn't calculate which files it needs
+beforehand. This means that for builds with a large context, context transfer
+can take a long time, even if you're only using a subset of the files included
+in the context.
-| Build Syntax Suffix | Commit Used | Build Context Used |
-|--------------------------------|-----------------------|--------------------|
-| `myrepo.git` | `refs/heads/master` | `/` |
-| `myrepo.git#mytag` | `refs/tags/mytag` | `/` |
-| `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` |
-| `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` |
-| `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` |
-| `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` |
-| `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` |
-| `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` |
+When using the legacy builder, it's therefore extra important that you
+carefully consider what files you include in the context you specify. Use a
+[`.dockerignore`](https://docs.docker.com/build/building/context/#dockerignore-files)
+file to exclude files and directories that you don't require in your build from
+being sent as part of the build context.
-### Tarball contexts
+#### Accessing paths outside the build context
-If you pass a URL to a remote tarball, the command sends the URL itself to the
-daemon:
+The legacy builder will error out if you try to access files outside of the
+build context using relative paths in your Dockerfile.
+
+```dockerfile
+FROM alpine
+COPY ../../some-dir .
+```
```console
-$ docker build http://server/context.tar.gz
+$ docker build .
+...
+Step 2/2 : COPY ../../some-dir .
+COPY failed: forbidden path outside the build context: ../../some-dir ()
```
-The host running the Docker daemon performs the download operation,
-which isn't necessarily the same host that issued the build command.
-The Docker daemon fetches `context.tar.gz` and uses it as the
-build context. Tarball contexts must be tar archives conforming to the standard
-`tar` Unix format and can be compressed with any one of the `xz`, `bzip2`,
-`gzip` or `identity` (no compression) formats.
-
-### Text files
-
-Instead of specifying a context, you can pass a single `Dockerfile` in the
-`URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`:
-
-```console
-$ docker build - < Dockerfile
-```
-
-With PowerShell on Windows, you run:
-
-```powershell
-Get-Content Dockerfile | docker build -
-```
-
-If you use `STDIN` or specify a `URL` pointing to a plain text file, the daemon
-places the contents into a `Dockerfile`, and ignores any `-f`, `--file`
-option. In this scenario, there is no context.
-
-By default the `docker build` command looks for a `Dockerfile` at the root
-of the build context. The `-f`, `--file`, option lets you specify the path to
-an alternative file to use instead. This is useful in cases that use the same
-set of files for multiple builds. The path must be to a file within the
-build context. Relative path are interpreted as relative to the root of the
-context.
-
-In most cases, it's best to put each Dockerfile in an empty directory. Then,
-add to that directory only the files needed for building the Dockerfile. To
-increase the build's performance, you can exclude files and directories by
-adding a `.dockerignore` file to that directory as well. For information on
-creating one, see the [.dockerignore file](https://docs.docker.com/reference/dockerfile/#dockerignore-file).
-
-If the Docker client loses connection to the daemon, it cancels the build.
-This happens if you interrupt the Docker client with `CTRL-c` or if the Docker
-client is killed for any reason. If the build initiated a pull which is still
-running at the time the build is cancelled, the client also cancels the pull.
-
-## Return code
-
-Successful builds return exit code `0`. When the build fails, the command
-returns a non-zero exit code and prints an error message to `STDERR`:
-
-```console
-$ docker build -t fail .
-
-Sending build context to Docker daemon 2.048 kB
-Sending build context to Docker daemon
-Step 1/3 : FROM busybox
- ---> 4986bf8c1536
-Step 2/3 : RUN exit 13
- ---> Running in e26670ec7a0a
-INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
-$ echo $?
-1
-```
-
-See also:
-
-[*Dockerfile Reference*](https://docs.docker.com/reference/dockerfile/).
+BuildKit on the other hand strips leading relative paths that traverse outside
+of the build context. Re-using the previous example, the path `COPY
+../../some-dir .` evaluates to `COPY some-dir .` with BuildKit.
## Examples
-### Build with PATH
-
-```console
-$ docker build .
-
-Uploading context 10240 bytes
-Step 1/3 : FROM busybox
-Pulling repository busybox
- ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
-Step 2/3 : RUN ls -lh /
- ---> Running in 9c9e81692ae9
-total 24
-drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin
-drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev
-drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc
-drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
-lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
-dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
-lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
-dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys
-drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp
-drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
- ---> b35f4035db3f
-Step 3/3 : CMD echo Hello world
- ---> Running in 02071fceb21b
- ---> f52f38b7823e
-Successfully built f52f38b7823e
-Removing intermediate container 9c9e81692ae9
-Removing intermediate container 02071fceb21b
-```
-
-This example specifies that the `PATH` is `.`, and so `tar`s all the files in the
-local directory and sends them to the Docker daemon. The `PATH` specifies
-where to find the files for the "context" of the build on the Docker daemon.
-Remember that the daemon could be running on a remote machine and that no
-parsing of the Dockerfile happens at the client side (where you're running
-`docker build`). That means that all the files at `PATH` are sent, not just
-the ones listed to [`ADD`](https://docs.docker.com/reference/dockerfile/#add)
-in the Dockerfile.
-
-The transfer of context from the local machine to the Docker daemon is what the
-`docker` client means when you see the "Sending build context" message.
-
-If you wish to keep the intermediate containers after the build is complete,
-you must use `--rm=false`. This doesn't affect the build cache.
-
-### Build with URL
-
-```console
-$ docker build github.com/creack/docker-firefox
-```
-
-This clones the GitHub repository, using the cloned repository as context,
-and the Dockerfile at the root of the repository. You can
-specify an arbitrary Git repository by using the `git://` or `git@` scheme.
-
-```console
-$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz
-
-Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B
-Step 1/3 : FROM busybox
- ---> 8c2e06607696
-Step 2/3 : ADD ctx/container.cfg /
- ---> e7829950cee3
-Removing intermediate container b35224abf821
-Step 3/3 : CMD /bin/ls
- ---> Running in fbc63d321d73
- ---> 3286931702ad
-Removing intermediate container fbc63d321d73
-Successfully built 377c409b35e4
-```
-
-This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which
-downloads and extracts the referenced tarball. The `-f ctx/Dockerfile`
-parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` used
-to build the image. Any `ADD` commands in that `Dockerfile` that refer to local
-paths must be relative to the root of the contents inside `ctx.tar.gz`. In the
-example above, the tarball contains a directory `ctx/`, so the `ADD
-ctx/container.cfg /` operation works as expected.
-
-### Build with `-`
-
-```console
-$ docker build - < Dockerfile
-```
-
-This example reads a Dockerfile from `STDIN` without context. Due to the lack of a
-context, the command doesn't send contents of any local directory to the Docker daemon.
-Since there is no context, a Dockerfile `ADD` only works if it refers to a
-remote URL.
-
-```console
-$ docker build - < context.tar.gz
-```
-
-This example builds an image for a compressed context read from `STDIN`.
-Supported formats are: `bzip2`, `gzip` and `xz`.
-
-### Use a .dockerignore file
-
-```console
-$ docker build .
-
-Uploading context 18.829 MB
-Uploading context
-Step 1/2 : FROM busybox
- ---> 769b9341d937
-Step 2/2 : CMD echo Hello world
- ---> Using cache
- ---> 99cc1ad10469
-Successfully built 99cc1ad10469
-$ echo ".git" > .dockerignore
-$ docker build .
-Uploading context 6.76 MB
-Uploading context
-Step 1/2 : FROM busybox
- ---> 769b9341d937
-Step 2/2 : CMD echo Hello world
- ---> Using cache
- ---> 99cc1ad10469
-Successfully built 99cc1ad10469
-```
-
-This example shows the use of the `.dockerignore` file to exclude the `.git`
-directory from the context. You can see its effect in the changed size of the
-uploaded context. The builder reference contains detailed information on
-[creating a .dockerignore file](https://docs.docker.com/reference/dockerfile/#dockerignore-file).
-
-When using the [BuildKit backend](https://docs.docker.com/build/buildkit/),
-`docker build` searches for a `.dockerignore` file relative to the Dockerfile
-name. For example, running `docker build -f myapp.Dockerfile .` first looks
-for an ignore file named `myapp.Dockerfile.dockerignore`. If it can't find such a file,
-if present, it uses the `.dockerignore` file. Using a Dockerfile based
-`.dockerignore` is useful if a project contains multiple Dockerfiles that expect
-to ignore different sets of files.
-
-### Tag an image (-t, --tag)
-
-```console
-$ docker build -t vieux/apache:2.0 .
-```
-
-This examples builds in the same way as the previous example, but it then tags the resulting
-image. The repository name will be `vieux/apache` and the tag `2.0`.
-
-[Read more about valid tags](image_tag.md).
-
-You can apply multiple tags to an image. For example, you can apply the `latest`
-tag to a newly built image and add another tag that references a specific
-version.
-
-For example, to tag an image both as `whenry/fedora-jboss:latest` and
-`whenry/fedora-jboss:v2.1`, use the following:
-
-```console
-$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
-```
-
-### Specify a Dockerfile (-f, --file)
-
-```console
-$ docker build -f Dockerfile.debug .
-```
-
-This uses a file called `Dockerfile.debug` for the build instructions
-instead of `Dockerfile`.
-
-```console
-$ curl example.com/remote/Dockerfile | docker build -f - .
-```
-
-The above command uses the current directory as the build context and reads
-a Dockerfile from stdin.
-
-```console
-$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
-$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .
-```
-
-The above commands build the current build context (as specified by the
-`.`) twice. Once using a debug version of a `Dockerfile` and once using a
-production version.
-
-```console
-$ cd /home/me/myapp/some/dir/really/deep
-$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
-$ docker build -f ../../../../dockerfiles/debug /home/me/myapp
-```
-
-These two `docker build` commands do the exact same thing. They both use the
-contents of the `debug` file instead of looking for a `Dockerfile` and use
-`/home/me/myapp` as the root of the build context. Note that `debug` is in the
-directory structure of the build context, regardless of how you refer to it on
-the command line.
-
-> **Note**
->
-> `docker build` returns a `no such file or directory` error if the
-> file or directory doesn't exist in the uploaded context. This may
-> happen if there is no context, or if you specify a file that's
-> elsewhere on the Host system. The context is limited to the current
-> directory (and its children) for security reasons, and to ensure
-> repeatable builds on remote Docker hosts. This is also the reason why
-> `ADD ../file` doesn't work.
-
-### Use a custom parent cgroup (--cgroup-parent)
-
-When you run `docker build` with the `--cgroup-parent` option, the daemon runs the containers
-used in the build with the [corresponding `docker run` flag](container_run.md#cgroup-parent).
-
-### Set ulimits in container (--ulimit)
-
-Using the `--ulimit` option with `docker build` causes the daemon to start each build step's
-container using those [`--ulimit` flag values](container_run.md#ulimit).
-
-### Set build-time variables (--build-arg)
-
-You can use `ENV` instructions in a Dockerfile to define variable values. These
-values persist in the built image. Often persistence isn't what you want. Users
-want to specify variables differently depending on which host they build an
-image on.
-
-A good example is `http_proxy` or source versions for pulling intermediate
-files. The `ARG` instruction lets Dockerfile authors define values that users
-can set at build-time using the `--build-arg` flag:
-
-```console
-$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .
-```
-
-This flag allows you to pass the build-time variables that are
-accessed like regular environment variables in the `RUN` instruction of the
-Dockerfile. These values don't persist in the intermediate or final images
-like `ENV` values do. You must add `--build-arg` for each build argument.
-
-Using this flag doesn't alter the output you see when the build process echoes the`ARG` lines from the
-Dockerfile.
-
-For detailed information on using `ARG` and `ENV` instructions, see the
-[Dockerfile reference](https://docs.docker.com/reference/dockerfile/).
-
-You can also use the `--build-arg` flag without a value, in which case the daemon
-propagates the value from the local environment into the Docker container it's building:
-
-```console
-$ export HTTP_PROXY=http://10.20.30.2:1234
-$ docker build --build-arg HTTP_PROXY .
-```
-
-This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](container_run.md#env)
-for more information.
-
-### Optional security options (--security-opt)
-
-This flag is only supported on a daemon running on Windows, and only supports
-the `credentialspec` option. The `credentialspec` must be in the format
-`file://spec.txt` or `registry://keyname`.
-
### Specify isolation technology for container (--isolation)
This option is useful in situations where you are running Docker containers on
@@ -450,199 +136,11 @@ Linux namespaces. On Microsoft Windows, you can specify these values:
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
-### Add entries to container hosts file (--add-host)
+### Optional security options (--security-opt)
-You can add other hosts into a build container's `/etc/hosts` file by using one
-or more `--add-host` flags. This example adds static addresses for hosts named
-`my-hostname` and `my_hostname_v6`:
-
-```console
-$ docker build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .
-```
-
-If you need your build to connect to services running on the host, you can use
-the special `host-gateway` value for `--add-host`. In the following example,
-build containers resolve `host.docker.internal` to the host's gateway IP.
-
-```console
-$ docker build --add-host host.docker.internal=host-gateway .
-```
-
-You can wrap an IPv6 address in square brackets.
-`=` and `:` are both valid separators.
-Both formats in the following example are valid:
-
-```console
-$ docker build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .
-```
-
-### Specifying target build stage (--target)
-
-When building a Dockerfile with multiple build stages, you can use the `--target`
-option to specify an intermediate build stage by name as a final stage for the
-resulting image. The daemon skips commands after the target stage.
-
-```dockerfile
-FROM debian AS build-env
-# ...
-
-FROM alpine AS production-env
-# ...
-```
-
-```console
-$ docker build -t mybuildimage --target build-env .
-```
-
-### Custom build outputs (--output)
-
-> **Note**
->
-> This feature requires the BuildKit backend. You can either
-> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
-> use the [buildx](https://github.com/docker/buildx) plugin which provides more
-> output type options.
-
-By default, a local container image is created from the build result. The
-`--output` (or `-o`) flag allows you to override this behavior, and specify a
-custom exporter. Custom exporters allow you to export the build
-artifacts as files on the local filesystem instead of a Docker image, which can
-be useful for generating local binaries, code generation etc.
-
-The value for `--output` is a CSV-formatted string defining the exporter type
-and options that supports `local` and `tar` exporters.
-
-The `local` exporter writes the resulting build files to a directory on the client side. The
-`tar` exporter is similar but writes the files as a single tarball (`.tar`).
-
-If you specify no type, the value defaults to the output directory of the local
-exporter. Use a hyphen (`-`) to write the output tarball to standard output
-(`STDOUT`).
-
-The following example builds an image using the current directory (`.`) as a build
-context, and exports the files to a directory named `out` in the current directory.
-If the directory does not exist, Docker creates the directory automatically:
-
-```console
-$ docker build -o out .
-```
-
-The example above uses the short-hand syntax, omitting the `type` options, and
-thus uses the default (`local`) exporter. The example below shows the equivalent
-using the long-hand CSV syntax, specifying both `type` and `dest` (destination
-path):
-
-```console
-$ docker build --output type=local,dest=out .
-```
-
-Use the `tar` type to export the files as a `.tar` archive:
-
-```console
-$ docker build --output type=tar,dest=out.tar .
-```
-
-The example below shows the equivalent when using the short-hand syntax. In this
-case, `-` is specified as destination, which automatically selects the `tar` type,
-and writes the output tarball to standard output, which is then redirected to
-the `out.tar` file:
-
-```console
-$ docker build -o - . > out.tar
-```
-
-The `--output` option exports all files from the target stage. A common pattern
-for exporting only specific files is to do multi-stage builds and to copy the
-desired files to a new scratch stage with [`COPY --from`](https://docs.docker.com/reference/dockerfile/#copy).
-
-The example, the `Dockerfile` below uses a separate stage to collect the
-build artifacts for exporting:
-
-```dockerfile
-FROM golang AS build-stage
-RUN go get -u github.com/LK4D4/vndr
-
-FROM scratch AS export-stage
-COPY --from=build-stage /go/bin/vndr /
-```
-
-When building the Dockerfile with the `-o` option, the command only exports the files from the final
-stage to the `out` directory, in this case, the `vndr` binary:
-
-```console
-$ docker build -o out .
-
-[+] Building 2.3s (7/7) FINISHED
- => [internal] load build definition from Dockerfile 0.1s
- => => transferring dockerfile: 176B 0.0s
- => [internal] load .dockerignore 0.0s
- => => transferring context: 2B 0.0s
- => [internal] load metadata for docker.io/library/golang:latest 1.6s
- => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s
- => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s
- => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s
- => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s
- => exporting to client 0.4s
- => => copying files 10.30MB 0.3s
-
-$ ls ./out
-vndr
-```
-
-### Specifying external cache sources (--cache-from)
-
-> **Note**
->
-> This feature requires the BuildKit backend. You can either
-> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
-> use the [buildx](https://github.com/docker/buildx) plugin. The previous
-> builder has limited support for reusing cache from pre-pulled images.
-
-In addition to local build cache, the builder can reuse the cache generated from
-previous builds with the `--cache-from` flag pointing to an image in the registry.
-
-To use an image as a cache source, cache metadata needs to be written into the
-image on creation. You can do this by setting `--build-arg BUILDKIT_INLINE_CACHE=1`
-when building the image. After that, you can use the built image as a cache source
-for subsequent builds.
-
-Upon importing the cache, the builder only pulls the JSON metadata from the
-registry and determine possible cache hits based on that information. If there
-is a cache hit, the builder pulls the matched layers into the local environment.
-
-In addition to images, the cache can also be pulled from special cache manifests
-generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI
-(`buildctl`). These manifests (when built with the `type=registry` and `mode=max`
-options) allow pulling layer data for intermediate stages in multi-stage builds.
-
-The following example builds an image with inline-cache metadata and pushes it
-to a registry, then uses the image as a cache source on another machine:
-
-```console
-$ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 .
-$ docker push myname/myapp
-```
-
-After pushing the image, the image is used as cache source on another machine.
-BuildKit automatically pulls the image from the registry if needed.
-
-On another machine:
-
-```console
-$ docker build --cache-from myname/myapp .
-```
-
-### Set the networking mode for the RUN instructions during build (--network)
-
-#### Overview
-
-Available options for the networking mode are:
-
-- `default` (default): Run in the default network.
-- `none`: Run with no network access.
-- `host`: Run in the host’s network environment.
-
-Find more details in the [Dockerfile documentation](https://docs.docker.com/reference/dockerfile/#run---network).
+This flag is only supported on a daemon running on Windows, and only supports
+the `credentialspec` option. The `credentialspec` must be in the format
+`file://spec.txt` or `registry://keyname`.
### Squash an image's layers (--squash) (experimental)
diff --git a/vendor.mod b/vendor.mod
index 3fc88579b1..569580a460 100644
--- a/vendor.mod
+++ b/vendor.mod
@@ -11,6 +11,7 @@ require (
github.com/containerd/platforms v0.2.1
github.com/creack/pty v1.1.21
github.com/distribution/reference v0.6.0
+ github.com/docker/cli-docs-tool v0.7.0
github.com/docker/distribution v2.8.3+incompatible
github.com/docker/docker v27.0.3+incompatible
github.com/docker/docker-credential-helpers v0.8.2
diff --git a/vendor.sum b/vendor.sum
index e7b8d1b48b..05d34f20e9 100644
--- a/vendor.sum
+++ b/vendor.sum
@@ -54,6 +54,8 @@ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
github.com/denisenkom/go-mssqldb v0.0.0-20191128021309-1d7a30a10f73/go.mod h1:xbL0rPBG9cCiLr28tMa8zpbdarY27NDyej4t/EjAShU=
github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/cli-docs-tool v0.7.0 h1:M2Da98Unz2kz3A5d4yeSGbhyOge2mfYSNjAFt01Rw0M=
+github.com/docker/cli-docs-tool v0.7.0/go.mod h1:zMjqTFCU361PRh8apiXzeAZ1Q/xupbIwTusYpzCXS/o=
github.com/docker/distribution v2.7.1+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk=
github.com/docker/distribution v2.8.3+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
diff --git a/vendor/github.com/docker/cli-docs-tool/LICENSE b/vendor/github.com/docker/cli-docs-tool/LICENSE
new file mode 100644
index 0000000000..d645695673
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/vendor/github.com/docker/cli-docs-tool/annotation/annotation.go b/vendor/github.com/docker/cli-docs-tool/annotation/annotation.go
new file mode 100644
index 0000000000..021846af6e
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/annotation/annotation.go
@@ -0,0 +1,25 @@
+// Copyright 2021 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package annotation
+
+const (
+ // ExternalURL specifies an external link annotation
+ ExternalURL = "docs.external.url"
+ // CodeDelimiter specifies the char that will be converted as code backtick.
+ // Can be used on cmd for inheritance or a specific flag.
+ CodeDelimiter = "docs.code-delimiter"
+ // DefaultValue specifies the default value for a flag.
+ DefaultValue = "docs.default-value"
+)
diff --git a/vendor/modules.txt b/vendor/modules.txt
index 0274c2a5ec..19e76b46cd 100644
--- a/vendor/modules.txt
+++ b/vendor/modules.txt
@@ -36,6 +36,9 @@ github.com/creack/pty
# github.com/distribution/reference v0.6.0
## explicit; go 1.20
github.com/distribution/reference
+# github.com/docker/cli-docs-tool v0.7.0
+## explicit; go 1.18
+github.com/docker/cli-docs-tool/annotation
# github.com/docker/distribution v2.8.3+incompatible
## explicit
github.com/docker/distribution