Merge pull request #16460 from thaJeztah/engine_reference_updates

engine: update reference docs to use new anchor tags

Author: thaJeztah

Dockerfile

@@ -66,12 +66,11 @@ EOT
 # htmlproofer checks for broken links
 FROM gem AS htmlproofer-base
 # FIXME(thaJeztah): remove temporary exclusion rule for buildx_build once anchor links are updated.
-# FIXME(thaJeztah): remove temporary exclusion rule for commandline/cli once https://github.com/docker/cli/pull/3525 is merged.
 RUN --mount=type=bind,from=generate,source=/out,target=_site <<EOF
   htmlproofer ./_site \
     --disable-external \
     --internal-domains="docs.docker.com,docs-stage.docker.com,localhost:4000" \
-    --file-ignore="/^./_site/engine/api/.*$/,./_site/registry/configuration/index.html,./_site/engine/reference/commandline/buildx_build/index.html,./_site/engine/reference/commandline/cli/index.html" \
+    --file-ignore="/^./_site/engine/api/.*$/,./_site/registry/configuration/index.html,./_site/engine/reference/commandline/buildx_build/index.html" \
     --url-ignore="/^/docker-hub/api/latest/.*$/,/^/engine/api/v.+/#.*$/,/^/glossary/.*$/" > /results 2>&1
   rc=$?
   if [[ $rc -eq 0 ]]; then

_data/engine-cli/docker_attach.yaml

@@ -26,12 +26,12 @@ long: |-
   > so.
 
   It is forbidden to redirect the standard input of a `docker attach` command
-  while attaching to a tty-enabled container (i.e.: launched with `-t`).
+  while attaching to a TTY-enabled container (using the `-i` and `-t` options).
 
-  While a client is connected to container's stdio using `docker attach`, Docker
-  uses a ~1MB memory buffer to maximize the throughput of the application. If
-  this buffer is filled, the speed of the API connection will start to have an
-  effect on the process output writing speed. This is similar to other
+  While a client is connected to container's `stdio` using `docker attach`, Docker
+  uses a ~1MB memory buffer to maximize the throughput of the application.
+  Once this buffer is full, the speed of the API connection is affected, and so
+  this impacts the output process' writing speed. This is similar to other
   applications like SSH. Because of this, it is not recommended to run
   performance critical applications that generate a lot of output in the
   foreground over a slow client connection. Instead, users should use the
@@ -93,45 +93,68 @@ options:
 examples: |-
   ### Attach to and detach from a running container
 
+  The following example starts an ubuntu container running `top` in detached mode,
+  then attaches to the container;
+
   ```console
-  $ docker run -d --name topdemo ubuntu /usr/bin/top -b
+  $ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b
 
   $ docker attach topdemo
 
-  top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
+  top - 12:27:44 up 3 days, 21:54,  0 users,  load average: 0.00, 0.00, 0.00
   Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-  Cpu(s):  0.1%us,  0.2%sy,  0.0%ni, 99.7%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-  Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
-  Swap:   786428k total,        0k used,   786428k free,   221740k cached
+  %Cpu(s):  0.1 us,  0.1 sy,  0.0 ni, 99.8 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
+  MiB Mem :   3934.3 total,    770.1 free,    674.2 used,   2490.1 buff/cache
+  MiB Swap:   1024.0 total,    839.3 free,    184.7 used.   2814.0 avail Mem
+
+    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+      1 root      20   0    7180   2896   2568 R   0.0   0.1   0:00.02 top
+  ```
 
-  PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-   1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
+  As the container was started without the `-i`, and `-t` options, signals are
+  forwarded to the attached process, which means that the default `CTRL-p CTRL-q`
+  detach key sequence produces no effect, but pressing `CTRL-c` terminates the
+  container:
 
-   top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
-   Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-   Cpu(s):  0.0%us,  0.2%sy,  0.0%ni, 99.8%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-   Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
-   Swap:   786428k total,        0k used,   786428k free,   221776k cached
+  ```console
+  <...>
+    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+      1 root      20   0    7180   2896   2568 R   0.0   0.1   0:00.02 top^P^Q
+  ^C
 
-     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-         1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
+  $ docker ps -a --filter name=topdemo
 
+  CONTAINER ID   IMAGE          COMMAND             CREATED              STATUS                          PORTS     NAMES
+  4cf0d0ebb079   ubuntu:22.04   "/usr/bin/top -b"   About a minute ago   Exited (0) About a minute ago             topdemo
+  ```
 
-   top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
-   Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-   Cpu(s):  0.2%us,  0.3%sy,  0.0%ni, 99.5%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-   Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
-   Swap:   786428k total,        0k used,   786428k free,   221776k cached
+  Repeating the example above, but this time with the `-i` and `-t` options set;
 
-   PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-        1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
-  ^C$
+  ```console
+  $ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b
+  ```
 
-  $ echo $?
-  0
-  $ docker ps -a | grep topdemo
+  Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read
+  escape sequence"), the Docker CLI is handling the detach sequence, and the
+  `attach` command is detached from the container. Checking the container's status
+  with `docker ps` shows that the container is still running in the background:
 
-  7998ac8581f9        ubuntu:14.04        "/usr/bin/top -b"   38 seconds ago      Exited (0) 21 seconds ago                          topdemo
+  ```console
+  $ docker attach topdemo2
+
+  top - 12:44:32 up 3 days, 22:11,  0 users,  load average: 0.00, 0.00, 0.00
+  Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
+  %Cpu(s): 50.0 us,  0.0 sy,  0.0 ni, 50.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
+  MiB Mem :   3934.3 total,    770.6 free,    672.4 used,   2491.4 buff/cache
+  MiB Swap:   1024.0 total,    839.3 free,    184.7 used.   2815.8 avail Mem
+
+    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+      1 root      20   0    7180   2776   2452 R   0.0   0.1   0:00.02 topread escape sequence
+
+  $ docker ps -a --filter name=topdemo2
+
+  CONTAINER ID   IMAGE          COMMAND             CREATED         STATUS         PORTS     NAMES
+  b1661dce0fc2   ubuntu:22.04   "/usr/bin/top -b"   2 minutes ago   Up 2 minutes             topdemo2
   ```
 
   ### Get the exit code of the container's command
@@ -140,20 +163,19 @@ examples: |-
   process is returned by the `docker attach` command to its caller too:
 
   ```console
-  $ docker run --name test -d -it debian
+  $ docker run --name test -dit alpine
   275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
 
   $ docker attach test
-  root@f38c87f2a42d:/# exit 13
-
-  exit
+  /# exit 13
 
   $ echo $?
   13
 
-  $ docker ps -a | grep test
+  $ docker ps -a --filter name=test
 
-  275c44472aeb        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
+  CONTAINER ID   IMAGE     COMMAND     CREATED              STATUS                       PORTS     NAMES
+  a2fe3fd886db   alpine    "/bin/sh"   About a minute ago   Exited (13) 40 seconds ago             test
   ```
 deprecated: false
 experimental: false

_data/engine-cli/docker_build.yaml

@@ -570,7 +570,7 @@ examples: |-
   expect to ignore different sets of files.
 
 
-  ### Tag an image (-t)
+  ### <a name="tag"></a> Tag an image (-t, --tag)
 
   ```console
   $ docker build -t vieux/apache:2.0 .
@@ -590,7 +590,7 @@ examples: |-
   $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
   ```
 
-  ### Specify a Dockerfile (-f)
+  ### <a name="file"></a> Specify a Dockerfile (-f, --file)
 
   ```console
   $ docker build -f Dockerfile.debug .
@@ -637,17 +637,17 @@ examples: |-
   > repeatable builds on remote Docker hosts. This is also the reason why
   > `ADD ../file` does not work.
 
-  ### Use a custom parent cgroup (--cgroup-parent)
+  ### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent)
 
   When `docker build` is run with the `--cgroup-parent` option the containers
   used in the build will be run with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups).
 
-  ### Set ulimits in container (--ulimit)
+  ### <a name="ulimit"></a> Set ulimits in container (--ulimit)
 
   Using the `--ulimit` option with `docker build` will cause each build step's
-  container to be started using those [`--ulimit` flag values](run.md#set-ulimits-in-container---ulimit).
+  container to be started using those [`--ulimit` flag values](run.md#ulimit).
 
-  ### Set build-time variables (--build-arg)
+  ### <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. However, often
@@ -682,16 +682,16 @@ examples: |-
   $ docker build --build-arg HTTP_PROXY .
   ```
 
-  This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)
+  This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env)
   for more information.
 
-  ### Optional security options (--security-opt)
+  ### <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`.
 
-  ### Specify isolation technology for container (--isolation)
+  ### <a name="isolation"></a> Specify isolation technology for container (--isolation)
 
   This option is useful in situations where you are running Docker containers on
   Windows. The `--isolation=<value>` option sets a container's isolation
@@ -707,15 +707,15 @@ examples: |-
 
   Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
 
-  ### Add entries to container hosts file (--add-host)
+  ### <a name="add-host"></a> Add entries to container hosts file (--add-host)
 
   You can add other hosts into a container's `/etc/hosts` file by using one or
   more `--add-host` flags. This example adds a static address for a host named
   `docker`:
 
       $ docker build --add-host=docker:10.180.0.1 .
 
-  ### Specifying target build stage (--target)
+  ### <a name="target"></a> Specifying target build stage (--target)
 
   When building a Dockerfile with multiple build stages, `--target` can be used to
   specify an intermediate build stage by name as a final stage for the resulting
@@ -733,7 +733,14 @@ examples: |-
   $ docker build -t mybuildimage --target build-env .
   ```
 
-  ### Custom build outputs
+  ### <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 a specify a
@@ -820,14 +827,14 @@ examples: |-
   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 which provides more
-  > output type options.
-
-  ### Specifying external cache sources
+  > 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.
@@ -863,14 +870,7 @@ examples: |-
   $ docker build --cache-from myname/myapp .
   ```
 
-  > **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.
-
-  ### Squash an image's layers (--squash) (experimental)
+  ### <a name="squash"></a> Squash an image's layers (--squash) (experimental)
 
   #### Overview
 

_data/engine-cli/docker_commit.yaml

@@ -66,8 +66,8 @@ examples: |-
   $ docker ps
 
   CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
-  c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
-  197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
+  c3f279d17e0a        ubuntu:22.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
+  197387f1b436        ubuntu:22.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
 
   $ docker commit c3f279d17e0a  svendowideit/testimage:version3
 
@@ -79,14 +79,14 @@ examples: |-
   svendowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
   ```
 
-  ### Commit a container with new configurations
+  ### <a name="change"></a> Commit a container with new configurations (--change)
 
   ```console
   $ docker ps
 
   CONTAINER ID       IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
-  c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
-  197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
+  c3f279d17e0a       ubuntu:22.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
+  197387f1b436       ubuntu:22.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
 
   $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a
 
@@ -107,8 +107,8 @@ examples: |-
   $ docker ps
 
   CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
-  c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
-  197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
+  c3f279d17e0a        ubuntu:22.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
+  197387f1b436        ubuntu:22.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
 
   $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a  svendowideit/testimage:version4
 
@@ -122,8 +122,8 @@ examples: |-
 
   CONTAINER ID        IMAGE               COMMAND                 CREATED             STATUS              PORTS              NAMES
   89373736e2e7        testimage:version4  "apachectl -DFOREGROU"  3 seconds ago       Up 2 seconds        80/tcp             distracted_fermat
-  c3f279d17e0a        ubuntu:12.04        /bin/bash               7 days ago          Up 25 hours                            desperate_dubinsky
-  197387f1b436        ubuntu:12.04        /bin/bash               7 days ago          Up 25 hours                            focused_hamilton
+  c3f279d17e0a        ubuntu:22.04        /bin/bash               7 days ago          Up 25 hours                            desperate_dubinsky
+  197387f1b436        ubuntu:22.04        /bin/bash               7 days ago          Up 25 hours                            focused_hamilton
   ```
 deprecated: false
 experimental: false

_data/engine-cli/docker_config_create.yaml

@@ -60,7 +60,7 @@ examples: |-
   dg426haahpi5ezmkkj5kyl3sn   my_config           7 seconds ago       7 seconds ago
   ```
 
-  ### Create a config with labels
+  ### <a name="label"></a> Create a config with labels (-l, --label)
 
   ```console
   $ docker config create \

_data/engine-cli/docker_config_inspect.yaml

@@ -80,7 +80,7 @@ examples: |-
   ]
   ```
 
-  ### Formatting
+  ### <a name="format"></a> Format the output (--format)
 
   You can use the --format option to obtain specific information about a
   config. The following example command outputs the creation time of the

_data/engine-cli/docker_config_ls.yaml

@@ -53,7 +53,7 @@ examples: |-
   mem02h8n73mybpgqjf0kfi1n0   test_config                 3 seconds ago       3 seconds ago
   ```
 
-  ### Filtering
+  ### <a name="filter"></a> Filtering (-f, --filter)
 
   The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
   than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
@@ -113,7 +113,7 @@ examples: |-
   mem02h8n73mybpgqjf0kfi1n0   test_config                 About an hour ago   About an hour ago
   ```
 
-  ### Format the output
+  ### <a name="format"></a> Format the output (--format)
 
   The formatting option (`--format`) pretty prints configs output
   using a Go template.

_data/engine-cli/docker_container_prune.yaml

@@ -37,7 +37,7 @@ examples: |-
   Total reclaimed space: 212 B
   ```
 
-  ### Filtering
+  ### <a name="filter"></a> Filtering (--filter)
 
   The filtering flag (`--filter`) format is of "key=value". If there is more
   than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)

_data/engine-cli/docker_context_create.yaml

@@ -65,7 +65,7 @@ examples: |-
       my-context
   ```
 
-  ### Create a context based on an existing context
+  ### <a name="from"></a> Create a context based on an existing context (--from)
 
   Use the `--from=<context-name>` option to create a new context from
   an existing context. The example below creates a new context named `my-context`

_data/engine-cli/docker_cp.yaml

@@ -111,7 +111,7 @@ examples: |-
   ### Corner cases
 
   It is not possible to copy certain system files such as resources under
-  `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by
+  `/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by
   the user in the container. However, you can still copy such files by manually
   running `tar` in `docker exec`. Both of the following examples do the same thing
   in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):