From 27bf78d33580924a2965462662bd36947ed5d84f Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 10 Apr 2024 12:10:10 +0200
Subject: [PATCH] docs: make buildx build the canonical reference doc
Move common flag descriptions to the buildx build reference, and make
that page the canonical page in docs. Also rewrite some content in
image_build to make clear that this page is only for the legacy builder.
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
(cherry picked from commit e91f0ded9c386dc8e29f298dd697e228cdd28aa3)
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
cli/command/image/build.go | 10 +-
docs/reference/commandline/build.md | 66 +-
docs/reference/commandline/builder_build.md | 66 +-
docs/reference/commandline/image_build.md | 674 +++---------------
vendor.mod | 1 +
vendor.sum | 2 +
.../github.com/docker/cli-docs-tool/LICENSE | 202 ++++++
.../cli-docs-tool/annotation/annotation.go | 25 +
vendor/modules.txt | 3 +
9 files changed, 394 insertions(+), 655 deletions(-)
create mode 100644 vendor/github.com/docker/cli-docs-tool/LICENSE
create mode 100644 vendor/github.com/docker/cli-docs-tool/annotation/annotation.go
diff --git a/cli/command/image/build.go b/cli/command/image/build.go
index 409b6cda18f1..cb5292be85c0 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 c0dd7a676897..e2f4765a4408 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 b972d573fac1..53da887d9c84 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 bae3c5a90035..a971d12967c7 100644
--- a/docs/reference/commandline/image_build.md
+++ b/docs/reference/commandline/image_build.md
@@ -1,438 +1,124 @@
-# 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.
-
-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.
-
-For example, run this command to use a directory called `docker` in the branch
-`container`:
-
-```console
-$ docker build https://github.com/docker/rootfs.git#container:docker
-```
-
-The following table represents all the valid suffixes with their build
-contexts:
-
-| 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` |
-
-### Tarball contexts
-
-If you pass a URL to a remote tarball, the command sends the URL itself to the
-daemon:
-
-```console
-$ docker build http://server/context.tar.gz
-```
-
-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
+> 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/).
-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`:
+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.
-```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
-```
+Builds invoked with `docker build` use Buildx (and BuildKit) by default, unless:
-See also:
+- You're running Docker Engine in Windows container mode
+- You explicitly opt out of using BuildKit by setting the environment variable `DOCKER_BUILDKIT=0`.
-[*Dockerfile Reference*](https://docs.docker.com/reference/dockerfile/).
+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/).
-## Examples
+### Build context with the legacy builder
-### Build with PATH
+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 .
-
-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.
+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.
-```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.
+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.
-### Build with `-`
-
-```console
-$ docker build - < Dockerfile
-```
+#### Accessing paths outside the build context
-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.
+The legacy builder will error out if you try to access files outside of the
+build context using relative paths in your Dockerfile.
-```console
-$ docker build - < context.tar.gz
+```dockerfile
+FROM alpine
+COPY ../../some-dir .
```
-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
+...
+Step 2/2 : COPY ../../some-dir .
+COPY failed: forbidden path outside the build context: ../../some-dir ()
```
-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 .
-```
+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.
-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`.
+## Examples
### Specify isolation technology for container (--isolation)
@@ -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)
-
-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.
+### Optional security options (--security-opt)
-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 1e8df33a7c9d..a915e230e1ac 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.2+incompatible
github.com/docker/docker-credential-helpers v0.8.2
diff --git a/vendor.sum b/vendor.sum
index a10e2c966411..f4b87c8c8b83 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 000000000000..d64569567334
--- /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 000000000000..021846af6e07
--- /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 064fe88e457a..7c3b68ffd25d 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