cli: make buildx build the canonical build

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

content/build/building/best-practices.md

@@ -607,7 +607,7 @@ as part of your build. `ADD` is better than manually adding files using
 something like `wget` and `tar`, because it ensures a more precise build cache.
 `ADD` also has built-in support for checksum validation of the remote
 resources, and a protocol for parsing branches, tags, and subdirectories from
-[Git URLs](../../reference/cli/docker/image/build.md#git-repositories).
+[Git URLs](../../reference/cli/docker/buildx/build.md#git-repositories).
 
 The following example uses `ADD` to download a .NET installer. Combined with
 multi-stage builds, only the .NET runtime remains in the final stage, no

content/build/building/packaging.md

@@ -39,7 +39,7 @@ Some projects may need distinct Dockerfiles for specific purposes. A common
 convention is to name these `<something>.Dockerfile`. You can specify the
 Dockerfile filename using the `--file` flag for the `docker build` command.
 Refer to the
-[`docker build` CLI reference](../../reference/cli/docker/image/build.md#file)
+[`docker build` CLI reference](../../reference/cli/docker/buildx/build.md#file)
 to learn about the `--file` flag.
 
 > **Note**

content/build/building/variables.md

@@ -117,7 +117,7 @@ $ docker build --build-arg NODE_VERSION=current .
 For more information on how to use build arguments, refer to:
 
 - [`ARG` Dockerfile reference](../../reference/dockerfile.md#arg)
-- [`docker build --build-arg` reference](../../reference/cli/docker/image/build.md#build-arg)
+- [`docker build --build-arg` reference](../../reference/cli/docker/buildx/build.md#build-arg)
 
 ## `ENV` usage example
 

content/build/guide/export.md

@@ -103,7 +103,7 @@ This is explored later on in this guide.
 
 Related information:
 
-- [`docker build --output` CLI reference](../../reference/cli/docker/image/build.md#output)
+- [`docker build --output` CLI reference](../../reference/cli/docker/buildx/build.md#output)
 - [Build exporters](../exporters/index.md)
 
 ## Next steps

content/build/guide/intro.md

@@ -160,7 +160,7 @@ container image and created a container from it.
 Related information:
 
 - [Dockerfile reference](../../reference/dockerfile.md)
-- [`docker build` CLI reference](../../reference/cli/docker/image/build.md)
+- [`docker build` CLI reference](../../reference/cli/docker/buildx/build.md)
 - [`docker run` CLI reference](../../reference/cli/docker/container/run.md)
 
 ## Next steps

content/docker-hub/builds/advanced.md

@@ -115,11 +115,11 @@ $ docker build --build-arg CUSTOM=$VAR -f $DOCKERFILE_PATH -t $IMAGE_NAME .
 
 > **Important**
 >
-> A `hooks/build` file overrides the basic [docker build](../../reference/cli/docker/image/build.md) command used by the builder, so you must include a similar build command in the hook or
+> A `hooks/build` file overrides the basic `docker build` command used by the builder, so you must include a similar build command in the hook or
 the automated build fails.
 { .important }
 
-Refer to the [docker build documentation](../../reference/cli/docker/image/build.md#build-arg)
+Refer to the [docker build documentation](../../reference/cli/docker/buildx/build.md#build-arg)
 to learn more about Docker build-time variables.
 
 #### Push to multiple repositories

content/guides/use-case/nlp/language-translation.md

@@ -262,7 +262,7 @@ To run the application using Docker:
      this case) is sent to the Docker daemon to enable the build. It includes
      all the files and subdirectories in the specified directory.
 
-   For more details, see the [docker build CLI reference](/reference/cli/docker/image/build/).
+   For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/).
 
    Docker outputs several logs to your console as it builds the image. You'll
    see it download and install the dependencies. Depending on your network

content/guides/use-case/nlp/named-entity-recognition.md

@@ -269,7 +269,7 @@ To run the application using Docker:
      this case) is sent to the Docker daemon to enable the build. It includes
      all the files and subdirectories in the specified directory.
 
-   For more details, see the [docker build CLI reference](/reference/cli/docker/image/build/).
+   For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/).
 
    Docker outputs several logs to your console as it builds the image. You'll
    see it download and install the dependencies. Depending on your network

content/guides/use-case/nlp/sentiment-analysis.md

@@ -287,7 +287,7 @@ To run the application using Docker:
    feature, so subsequent builds can be faster. The console will
    return to the prompt when it's complete.
 
-   For more details, see the [docker build CLI reference](/reference/cli/docker/image/build/).
+   For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/).
 
 2. Run the image as a container.
 

content/guides/use-case/nlp/text-classification.md

@@ -341,7 +341,7 @@ To run the application using Docker:
      this case) is sent to the Docker daemon to enable the build. It includes
      all the files and subdirectories in the specified directory.
 
-   For more details, see the [docker build CLI reference](/reference/cli/docker/image/build/).
+   For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/).
 
    Docker outputs several logs to your console as it builds the image. You'll
    see it download and install the dependencies. Depending on your network

content/guides/use-case/nlp/text-summarization.md

@@ -276,7 +276,7 @@ To run the application using Docker:
      this case) is sent to the Docker daemon to enable the build. It includes
      all the files and subdirectories in the specified directory.
 
-   For more details, see the [docker build CLI reference](/reference/cli/docker/image/build/).
+   For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/).
 
    Docker outputs several logs to your console as it builds the image. You'll
    see it download and install the dependencies. Depending on your network

content/language/rust/build-images.md

@@ -174,7 +174,7 @@ Related information:
  - [Dockerfile reference](../../reference/dockerfile.md)
  - [.dockerignore file](../../reference/dockerfile.md#dockerignore-file)
  - [docker init CLI reference](../../reference/cli/docker/init.md)
- - [docker build CLI reference](../../reference/cli/docker/image/build.md)
+ - [docker build CLI reference](../../reference/cli/docker/buildx/build.md)
 
 
 ## Next steps

content/reference/cli/docker/build-legacy.md

@@ -2,14 +2,7 @@
 datafolder: engine-cli
 datafile: docker_image_build
 linkTitle: docker build
-title: docker image build
+title: docker build (legacy builder)
-aliases:
-- /edge/engine/reference/commandline/image_build/
-- /engine/reference/commandline/image_build/
-- /engine/reference/commandline/build/
-- /engine/reference/commandline/builder_build/
-- /reference/cli/docker/build/
-- /reference/cli/docker/builder/build/
 layout: cli
 ---
 

content/reference/cli/docker/buildx/build.md

@@ -5,6 +5,13 @@ title: docker buildx build
 layout: cli
 aliases:
 - /engine/reference/commandline/buildx_build/
+- /edge/engine/reference/commandline/image_build/
+- /engine/reference/commandline/image_build/
+- /engine/reference/commandline/build/
+- /engine/reference/commandline/builder_build/
+- /reference/cli/docker/build/
+- /reference/cli/docker/builder/build/
+- /reference/cli/docker/image/build/
 ---
 
 <!--

data/engine-cli/docker_build.yaml

@@ -1,5 +1,5 @@
 command: docker build
-aliases: docker image build, docker build, docker buildx build, docker builder build
+aliases: docker image build, docker build, docker builder build
 short: Build an image from a Dockerfile
 long: Build an image from a Dockerfile
 usage: docker build [OPTIONS] PATH | URL | -
@@ -9,6 +9,7 @@ options:
     - option: add-host
       value_type: list
       description: Add a custom host-to-IP mapping (`host:ip`)
+      details_url: /reference/cli/docker/buildx/build/#add-host
       deprecated: false
       hidden: false
       experimental: false
@@ -18,6 +19,7 @@ options:
     - option: build-arg
       value_type: list
       description: Set build-time variables
+      details_url: /reference/cli/docker/buildx/build/#build-arg
       deprecated: false
       hidden: false
       experimental: false
@@ -37,6 +39,7 @@ options:
     - option: cgroup-parent
       value_type: string
       description: Set the parent cgroup for the `RUN` instructions during build
+      details_url: /reference/cli/docker/buildx/build/#cgroup-parent
       deprecated: false
       hidden: false
       experimental: false
@@ -116,6 +119,7 @@ options:
       shorthand: f
       value_type: string
       description: Name of the Dockerfile (Default is `PATH/Dockerfile`)
+      details_url: /reference/cli/docker/buildx/build/#file
       deprecated: false
       hidden: false
       experimental: false
@@ -184,6 +188,7 @@ options:
       value_type: string
       default_value: default
       description: Set the networking mode for the RUN instructions during build
+      details_url: /reference/cli/docker/buildx/build/#network
       deprecated: false
       hidden: false
       min_api_version: "1.25"
@@ -277,6 +282,7 @@ options:
       shorthand: t
       value_type: list
       description: Name and optionally a tag in the `name:tag` format
+      details_url: /reference/cli/docker/buildx/build/#tag
       deprecated: false
       hidden: false
       experimental: false
@@ -286,6 +292,7 @@ options:
     - option: target
       value_type: string
       description: Set the target build stage to build.
+      details_url: /reference/cli/docker/buildx/build/#target
       deprecated: false
       hidden: false
       experimental: false

data/engine-cli/docker_builder_build.yaml

@@ -1,5 +1,5 @@
 command: docker builder build
-aliases: docker image build, docker build, docker buildx build, docker builder build
+aliases: docker image build, docker build, docker builder build
 short: Build an image from a Dockerfile
 long: |
     See [docker build](/reference/cli/docker/image/build/) for more information.
@@ -10,6 +10,7 @@ options:
     - option: add-host
       value_type: list
       description: Add a custom host-to-IP mapping (`host:ip`)
+      details_url: /reference/cli/docker/buildx/build/#add-host
       deprecated: false
       hidden: false
       experimental: false
@@ -19,6 +20,7 @@ options:
     - option: build-arg
       value_type: list
       description: Set build-time variables
+      details_url: /reference/cli/docker/buildx/build/#build-arg
       deprecated: false
       hidden: false
       experimental: false
@@ -38,6 +40,7 @@ options:
     - option: cgroup-parent
       value_type: string
       description: Set the parent cgroup for the `RUN` instructions during build
+      details_url: /reference/cli/docker/buildx/build/#cgroup-parent
       deprecated: false
       hidden: false
       experimental: false
@@ -117,6 +120,7 @@ options:
       shorthand: f
       value_type: string
       description: Name of the Dockerfile (Default is `PATH/Dockerfile`)
+      details_url: /reference/cli/docker/buildx/build/#file
       deprecated: false
       hidden: false
       experimental: false
@@ -185,6 +189,7 @@ options:
       value_type: string
       default_value: default
       description: Set the networking mode for the RUN instructions during build
+      details_url: /reference/cli/docker/buildx/build/#network
       deprecated: false
       hidden: false
       min_api_version: "1.25"
@@ -278,6 +283,7 @@ options:
       shorthand: t
       value_type: list
       description: Name and optionally a tag in the `name:tag` format
+      details_url: /reference/cli/docker/buildx/build/#tag
       deprecated: false
       hidden: false
       experimental: false
@@ -287,6 +293,7 @@ options:
     - option: target
       value_type: string
       description: Set the target build stage to build.
+      details_url: /reference/cli/docker/buildx/build/#target
       deprecated: false
       hidden: false
       experimental: false

data/engine-cli/docker_image_build.yaml

@@ -1,110 +1,77 @@
 command: docker image build
-aliases: docker image build, docker build, docker buildx build, docker builder build
+aliases: docker image build, docker build, docker builder build
 short: Build an image from a Dockerfile
 long: |-
-    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*](/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
+    > This page refers to the **legacy implementation** of `docker build`,
-    > the repository and its submodules.
+    > 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`](/reference/cli/docker/build/).
 
-    Git URLs accept context configuration in their fragment section, separated by a
+    When building with legacy builder, images are created from a Dockerfile by
-    colon (`:`).  The first part represents the reference that Git checks out,
+    running a sequence of [commits](/reference/cli/docker/container/commit/). This process is
-    and can be either a branch, a tag, or a remote reference. The second part
+    inefficient and slow compared to using BuildKit, which is why this build
-    represents a subdirectory inside the repository used as a build
+    strategy is deprecated for all use cases except for building Windows
-    context.
+    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
+    Builds invoked with `docker build` use Buildx (and BuildKit) by default, unless:
-    `container`:
+
+    - 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`](/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
+    When using the legacy builder, the build context is sent over to the daemon in
-    contexts:
+    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 |
+    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
-    | `myrepo.git`                   | `refs/heads/master`   | `/`                |
+    [`.dockerignore`](/build/building/context/#dockerignore-files)
-    | `myrepo.git#mytag`             | `refs/tags/mytag`     | `/`                |
+    file to exclude files and directories that you don't require in your build from
-    | `myrepo.git#mybranch`          | `refs/heads/mybranch` | `/`                |
+    being sent as part of the build context.
-    | `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
+    #### Accessing paths outside the build context
 
-    If you pass a URL to a remote tarball, the command sends the URL itself to the
+    The legacy builder will error out if you try to access files outside of the
-    daemon:
+    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,
+    BuildKit on the other hand strips leading relative paths that traverse outside
-    which isn't necessarily the same host that issued the build command.
+    of the build context. Re-using the previous example, the path `COPY
-    The Docker daemon fetches `context.tar.gz` and uses it as the
+    ../../some-dir .` evaluates to `COPY some-dir .` with BuildKit.
-    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](/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.
 usage: docker image build [OPTIONS] PATH | URL | -
 pname: docker image
 plink: docker_image.yaml
@@ -112,7 +79,7 @@ options:
     - option: add-host
       value_type: list
       description: Add a custom host-to-IP mapping (`host:ip`)
-      details_url: '#add-host'
+      details_url: /reference/cli/docker/buildx/build/#add-host
       deprecated: false
       hidden: false
       experimental: false
@@ -122,7 +89,7 @@ options:
     - option: build-arg
       value_type: list
       description: Set build-time variables
-      details_url: '#build-arg'
+      details_url: /reference/cli/docker/buildx/build/#build-arg
       deprecated: false
       hidden: false
       experimental: false
@@ -133,7 +100,6 @@ options:
       value_type: stringSlice
       default_value: '[]'
       description: Images to consider as cache sources
-      details_url: '#cache-from'
       deprecated: false
       hidden: false
       experimental: false
@@ -143,7 +109,7 @@ options:
     - option: cgroup-parent
       value_type: string
       description: Set the parent cgroup for the `RUN` instructions during build
-      details_url: '#cgroup-parent'
+      details_url: /reference/cli/docker/buildx/build/#cgroup-parent
       deprecated: false
       hidden: false
       experimental: false
@@ -223,7 +189,7 @@ options:
       shorthand: f
       value_type: string
       description: Name of the Dockerfile (Default is `PATH/Dockerfile`)
-      details_url: '#file'
+      details_url: /reference/cli/docker/buildx/build/#file
       deprecated: false
       hidden: false
       experimental: false
@@ -293,7 +259,7 @@ options:
       value_type: string
       default_value: default
       description: Set the networking mode for the RUN instructions during build
-      details_url: '#network'
+      details_url: /reference/cli/docker/buildx/build/#network
       deprecated: false
       hidden: false
       min_api_version: "1.25"
@@ -389,7 +355,7 @@ options:
       shorthand: t
       value_type: list
       description: Name and optionally a tag in the `name:tag` format
-      details_url: '#tag'
+      details_url: /reference/cli/docker/buildx/build/#tag
       deprecated: false
       hidden: false
       experimental: false
@@ -399,7 +365,7 @@ options:
     - option: target
       value_type: string
       description: Set the target build stage to build.
-      details_url: '#target'
+      details_url: /reference/cli/docker/buildx/build/#target
       deprecated: false
       hidden: false
       experimental: false
@@ -410,7 +376,6 @@ options:
       value_type: ulimit
       default_value: '[]'
       description: Ulimit options
-      details_url: '#ulimit'
       deprecated: false
       hidden: false
       experimental: false
@@ -429,264 +394,6 @@ inherited_options:
       kubernetes: false
       swarm: false
 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`](/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](/reference/dockerfile/#dockerignore-file).
-
-    When using the [BuildKit backend](/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) {#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](/reference/cli/docker/image/tag/).
-
-    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) {#file}
-
-    ```console
-    $ docker build -f Dockerfile.debug .
-    ```
-
-    This uses a file called `Dockerfile.debug` for the build instructions
-    instead of `Dockerfile`.
-
-    ```console
-    $ curl example.com/remote/Dockerfile | docker build -f - .
-    ```
-
-    The above command uses the current directory as the build context and reads
-    a Dockerfile from stdin.
-
-    ```console
-    $ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
-    $ docker build -f dockerfiles/Dockerfile.prod  -t myapp_prod .
-    ```
-
-    The above commands build the current build context (as specified by the
-    `.`) twice. Once using a debug version of a `Dockerfile` and once using a
-    production version.
-
-    ```console
-    $ cd /home/me/myapp/some/dir/really/deep
-    $ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
-    $ docker build -f ../../../../dockerfiles/debug /home/me/myapp
-    ```
-
-    These two `docker build` commands do the exact same thing. They both use the
-    contents of the `debug` file instead of looking for a `Dockerfile` and use
-    `/home/me/myapp` as the root of the build context. Note that `debug` is in the
-    directory structure of the build context, regardless of how you refer to it on
-    the command line.
-
-    > **Note**
-    >
-    > `docker build` returns a `no such file or directory` error if the
-    > file or directory doesn't exist in the uploaded context. This may
-    > happen if there is no context, or if you specify a file that's
-    > elsewhere on the Host system. The context is limited to the current
-    > directory (and its children) for security reasons, and to ensure
-    > repeatable builds on remote Docker hosts. This is also the reason why
-    > `ADD ../file` doesn't work.
-
-    ### Use a custom parent cgroup (--cgroup-parent) {#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](/reference/cli/docker/container/run/#cgroup-parent).
-
-    ### Set ulimits in container (--ulimit) {#ulimit}
-
-    Using the `--ulimit` option with `docker build` causes the daemon to start each build step's
-    container using those [`--ulimit` flag values](/reference/cli/docker/container/run/#ulimit).
-
-    ### Set build-time variables (--build-arg) {#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](/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](/reference/cli/docker/container/run/#env)
-    for more information.
-
-    ### Optional security options (--security-opt) {#security-opt}
-
-    This flag is only supported on a daemon running on Windows, and only supports
-    the `credentialspec` option. The `credentialspec` must be in the format
-    `file://spec.txt` or `registry://keyname`.
-
     ### Specify isolation technology for container (--isolation) {#isolation}
 
     This option is useful in situations where you are running Docker containers on
@@ -703,199 +410,11 @@ examples: |-
 
     Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
 
-    ### Add entries to container hosts file (--add-host) {#add-host}
+    ### Optional security options (--security-opt) {#security-opt}
 
-    You can add other hosts into a build container's `/etc/hosts` file by using one
+    This flag is only supported on a daemon running on Windows, and only supports
-    or more `--add-host` flags. This example adds static addresses for hosts named
+    the `credentialspec` option. The `credentialspec` must be in the format
-    `my-hostname` and `my_hostname_v6`:
+    `file://spec.txt` or `registry://keyname`.
-
-    ```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) {#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) {#output}
-
-    > **Note**
-    >
-    > This feature requires the BuildKit backend. You can either
-    > [enable BuildKit](/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`](/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) {#cache-from}
-
-    > **Note**
-    >
-    > This feature requires the BuildKit backend. You can either
-    > [enable BuildKit](/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) {#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](/reference/dockerfile/#run---network).
 
     ### Squash an image's layers (--squash) (experimental) {#squash}
 

data/toc.yaml

@@ -340,6 +340,8 @@ Reference:
     title: docker (base command)
   - path: /reference/cli/docker/build/
     title: docker build
+  - path: /reference/cli/docker/build-legacy/
+    title: docker build (legacy builder)
   - sectiontitle: docker builder
     section:
       - path: /reference/cli/docker/builder/