Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5227 from dvdksn/backport_buildx_canonical 

[27.0 backport] docs: make buildx build the canonical reference doc
This commit is contained in:
Paweł Gronowski 2024-07-04 11:20:46 +02:00 committed by GitHub
parent 71b756be32 27bf78d335
commit 59fb099da2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 401 additions and 662 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
cli/command/image/build.go
View File

@ -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())

66
docs/reference/commandline/build.md
View File

@ -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 |
<!---MARKER_GEN_END-->

66
docs/reference/commandline/builder_build.md
View File

@ -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 |
<!---MARKER_GEN_END-->

688
docs/reference/commandline/image_build.md
View File

@ -1,439 +1,125 @@
# build
# build (legacy builder)
<!---MARKER_GEN_START-->
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 |
<!---MARKER_GEN_END-->
## 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.
### <a name="tag"></a> 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 .
```
### <a name="file"></a> 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.
### <a name="cgroup-parent"></a> 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).
### <a name="ulimit"></a> 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).
### <a name="build-arg"></a> 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.
### <a name="security-opt"></a> 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`.
### <a name="isolation"></a> 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"`.
### <a name="add-host"></a> Add entries to container hosts file (--add-host)
### <a name="security-opt"></a> 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] .
```
### <a name="target"></a> 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 .
```
### <a name="output"></a> 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
```
### <a name="cache-from"></a> 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 .
```
### <a name="network"></a> 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`.
### <a name="squash"></a> Squash an image's layers (--squash) (experimental)

1
vendor.mod
View File

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

2
vendor.sum
View File

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

202
vendor/github.com/docker/cli-docs-tool/LICENSE generated vendored Normal file
View File

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

25
vendor/github.com/docker/cli-docs-tool/annotation/annotation.go generated vendored Normal file
View File

@ -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"
)

3
vendor/modules.txt vendored
View File

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