Merge pull request #18899 from thaJeztah/update_cli_reference

update engine docs and cli reference

_vendor/modules.txt

@@ -2,6 +2,6 @@
 # github.com/moby/buildkit v0.13.0-beta1.0.20231113205014-1efcd30d9dd6
 # github.com/docker/buildx v0.12.0
 # github.com/docker/scout-cli v1.2.0
-# github.com/docker/cli v24.0.8-0.20231106123152-48ec4f339e2b+incompatible
+# github.com/docker/cli v24.0.8-0.20231211210310-fb2f337bc1b1+incompatible
 # github.com/compose-spec/compose-spec v0.0.0-20231121152139-478928e7c9f8
 # github.com/docker/compose/v2 v2.23.3

data/engine-cli/docker_build.yaml

@@ -141,7 +141,7 @@ options:
       swarm: false
     - option: cgroup-parent
       value_type: string
-      description: Optional parent cgroup for the container
+      description: Set the parent cgroup for the `RUN` instructions during build
       details_url: '#cgroup-parent'
       deprecated: false
       hidden: false

data/engine-cli/docker_builder_build.yaml

@@ -36,7 +36,7 @@ options:
       swarm: false
     - option: cgroup-parent
       value_type: string
-      description: Optional parent cgroup for the container
+      description: Set the parent cgroup for the `RUN` instructions during build
       deprecated: false
       hidden: false
       experimental: false

data/engine-cli/docker_config_inspect.yaml

@@ -6,7 +6,7 @@ long: |-
     By default, this renders all results in a JSON array. If a format is specified,
     the given template will be executed for each result.
 
-    Go's [text/template](https://golang.org/pkg/text/template/) package
+    Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).

data/engine-cli/docker_events.yaml

@@ -175,7 +175,7 @@ long: |-
 
     If a format (`--format`) is specified, the given template will be executed
     instead of the default
-    format. Go's [text/template](https://golang.org/pkg/text/template/) package
+    format. Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     If a format is set to `{{json .}}`, the events are streamed as valid JSON
@@ -196,7 +196,11 @@ options:
       swarm: false
     - option: format
       value_type: string
-      description: Format the output using the given Go template
+      description: |-
+        Format output using a custom template:
+        'json':             Print in JSON format
+        'TEMPLATE':         Print output using the given Go template.
+        Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates
       deprecated: false
       hidden: false
       experimental: false
@@ -432,15 +436,20 @@ examples: |-
 
     #### Format as JSON
 
+    To list events in JSON format, use the `json` directive, which is the equivalent
+    of `--format '{{ json . }}`.
+
     ```console
-    $ docker events --format '{{json .}}'
+    $ docker events --format json
 
     {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
     {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
     {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     ```
+
+    .
 deprecated: false
 experimental: false
 experimentalcli: false

data/engine-cli/docker_exec.yaml

@@ -162,10 +162,10 @@ examples: |-
 
     Next, set environment variables in the current bash session.
 
-    By default, the `docker exec` command, inherits the environment variables that
-    are set at the time the container is created. Use the `--env` (or the `-e` shorthand)
-    to override global environment variables, or to set additional environment variables
-    for the process started by `docker exec`.
+    The `docker exec` command inherits the environment variables that are set at the
+    time the container is created. Use the `--env` (or the `-e` shorthand) to
+    override global environment variables, or to set additional environment
+    variables for the process started by `docker exec`.
 
     The example below creates a new shell session in the container `mycontainer` with
     environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively.

data/engine-cli/docker_image_build.yaml

@@ -36,7 +36,7 @@ options:
       swarm: false
     - option: cgroup-parent
       value_type: string
-      description: Optional parent cgroup for the container
+      description: Set the parent cgroup for the `RUN` instructions during build
       deprecated: false
       hidden: false
       experimental: false

data/engine-cli/docker_info.yaml

@@ -8,7 +8,7 @@ long: |-
     under different names is counted only once.
 
     If a format is specified, the given template will be executed instead of the
-    default format. Go's [text/template](https://golang.org/pkg/text/template/) package
+    default format. Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     Depending on the storage driver in use, additional information can be shown, such

data/engine-cli/docker_inspect.yaml

@@ -9,7 +9,7 @@ long: |-
 
     If a format is specified, the given template will be executed for each result.
 
-    Go's [text/template](https://golang.org/pkg/text/template/) package describes
+    Go's [text/template](https://pkg.go.dev/text/template) package describes
     all the details of the format.
 
     ### Specify target type (--type) {#type}

data/engine-cli/docker_load.yaml

@@ -3,7 +3,7 @@ aliases: docker image load, docker load
 short: Load an image from a tar archive or STDIN
 long: |-
     Load an image or repository from a tar archive (even if compressed with gzip,
-    bzip2, or xz) from a file or STDIN. It restores both images and tags.
+    bzip2, xz or zstd) from a file or STDIN. It restores both images and tags.
 usage: docker load [OPTIONS]
 pname: docker
 plink: docker.yaml

data/engine-cli/docker_logs.yaml

@@ -13,7 +13,7 @@ long: |-
     Passing a negative number or a non-integer to `--tail` is invalid and the
     value is set to `all` in that case.
 
-    The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants)
+    The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano)
     , for example `2014-09-16T06:17:46.000000000Z`, to each
     log entry. To ensure that the timestamps are aligned the
     nano-second part of the timestamp will be padded with zero when necessary.

data/engine-cli/docker_node_inspect.yaml

@@ -4,7 +4,7 @@ long: |-
     Returns information about a node. By default, this command renders all results
     in a JSON array. You can specify an alternate format to execute a
     given template for each result. Go's
-    [text/template](https://golang.org/pkg/text/template/) package describes all the
+    [text/template](https://pkg.go.dev/text/template) package describes all the
     details of the format.
 
     > **Note**

data/engine-cli/docker_ps.yaml

@@ -262,9 +262,19 @@ examples: |-
 
     #### status
 
-    The `status` filter matches containers by status. You can filter using
-    `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example,
-    to filter for `running` containers:
+    The `status` filter matches containers by status. The possible values for the container status are:
+
+    | Status       | Description                                                                                                                                                                                     |
+    | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `created`    | A container that has never been started.                                                                                                                                                        |
+    | `running`    | A running container, started by either `docker start` or `docker run`.                                                                                                                          |
+    | `paused`     | A paused container. See `docker pause`.                                                                                                                                                         |
+    | `restarting` | A container which is starting due to the designated restart policy for that container.                                                                                                          |
+    | `exited`     | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command.                                   |
+    | `removing`   | A container which is in the process of being removed. See `docker rm`.                                                                                                                          |
+    | `dead`       | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. |
+
+    For example, to filter for `running` containers:
 
     ```console
     $ docker ps --filter status=running

data/engine-cli/docker_pull.yaml

@@ -104,18 +104,18 @@ examples: |-
     Docker images can consist of multiple layers. In the example above, the image
     consists of a single layer; `e756f3fdd6a3`.
 
-    Layers can be reused by images. For example, the `debian:bullseye` image shares
-    its layer with the `debian:latest`. Pulling the `debian:bullseye` image therefore
+    Layers can be reused by images. For example, the `debian:bookworm` image shares
+    its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore
     only pulls its metadata, but not its layers, because the layer is already present
     locally:
 
     ```console
-    $ docker image pull debian:bullseye
+    $ docker image pull debian:bookworm
 
-    bullseye: Pulling from library/debian
+    bookworm: Pulling from library/debian
     Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
-    Status: Downloaded newer image for debian:bullseye
-    docker.io/library/debian:bullseye
+    Status: Downloaded newer image for debian:bookworm
+    docker.io/library/debian:bookworm
     ```
 
     To see which images are present locally, use the [`docker images`](images.md)
@@ -125,13 +125,13 @@ examples: |-
     $ docker images
 
     REPOSITORY   TAG        IMAGE ID       CREATED        SIZE
-    debian       bullseye   4eacea30377a   8 days ago     124MB
+    debian       bookworm   4eacea30377a   8 days ago     124MB
     debian       latest     4eacea30377a   8 days ago     124MB
     ```
 
     Docker uses a content-addressable image store, and the image ID is a SHA256
     digest covering the image's configuration and layers. In the example above,
-    `debian:bullseye` and `debian:latest` have the same image ID because they are
+    `debian:bookworm` and `debian:latest` have the same image ID because they are
     the *same* image tagged with different names. Because they are the same image,
     their layers are stored only once and do not consume extra disk space.
 

data/engine-cli/docker_run.yaml

@@ -1360,6 +1360,8 @@ examples: |-
     You can also load the environment variables from a file. This file should use
     the syntax `<variable>=value` (which sets the variable to the given value) or
     `<variable>` (which takes the value from the local environment), and `#` for comments.
+    Additionally, it's important to note that lines beginning with `#` are treated as line comments
+    and are ignored, whereas a `#` appearing anywhere else in a line is treated as part of the variable value.
 
     ```console
     $ cat env.list
@@ -1622,7 +1624,7 @@ examples: |-
     following rule:
 
     ```console
-    $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
+    $ docker run -d --device-cgroup-rule='c 42:* rmw' --name my-container my-image
     ```
 
     Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`