Update Compose reference API to v2.16.0 (#16702)

Signed-off-by: GitHub <noreply@github.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Co-authored-by: glours <glours@users.noreply.github.com>

_config.yml

@@ -45,7 +45,7 @@ exclude:
 latest_engine_api_version: "1.42"
 docker_ce_version: "23.0.0"
 compose_v1_version: "1.29.2"
-compose_version: "v2.15.1"
+compose_version: "v2.16.0"
 compose_file_v3: "3.9"
 compose_file_v2: "2.4"
 machine_version: "0.16.0"

_data/compose-cli/docker_compose.yaml

@@ -89,13 +89,22 @@ long: |-
 
     Profiles can also be set by `COMPOSE_PROFILES` environment variable.
 
+    ### Configuring parallelism
+
+    Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
+    Calling `docker compose --parallel 1 pull` will pull the pullable images defined in the Compose file
+    one at a time. This can also be used to control build concurrency.
+
+    Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
+
     ### Set up environment variables
 
     You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.
 
     Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,
     `COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag,
-    and `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag.
+    `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag
+    and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag.
 
     If flags are explicitly set on the command line, the associated environment variable is ignored.
 
@@ -106,7 +115,7 @@ pname: docker
 plink: docker.yaml
 cname:
     - docker compose build
-    - docker compose convert
+    - docker compose config
     - docker compose cp
     - docker compose create
     - docker compose down
@@ -132,7 +141,7 @@ cname:
     - docker compose version
 clink:
     - docker_compose_build.yaml
-    - docker_compose_convert.yaml
+    - docker_compose_config.yaml
     - docker_compose_cp.yaml
     - docker_compose_create.yaml
     - docker_compose_down.yaml
@@ -178,6 +187,16 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: env-file
       value_type: string
       description: Specify an alternate environment file.

_data/compose-cli/docker_compose_alpha.yaml

@@ -0,0 +1,17 @@
+command: docker compose alpha
+short: Experimental commands
+long: Experimental commands
+pname: docker compose
+plink: docker_compose.yaml
+cname:
+    - docker compose alpha dry-run
+    - docker compose alpha watch
+clink:
+    - docker_compose_alpha_dry-run.yaml
+    - docker_compose_alpha_watch.yaml
+deprecated: false
+experimental: false
+experimentalcli: true
+kubernetes: false
+swarm: false
+

_data/compose-cli/docker_compose_alpha_dry-run.yaml

@@ -0,0 +1,14 @@
+command: docker compose alpha dry-run
+short: |
+    EXPERIMENTAL - Dry run command allow you to test a command without applying changes
+long: |
+    EXPERIMENTAL - Dry run command allow you to test a command without applying changes
+usage: docker compose alpha dry-run -- [COMMAND...]
+pname: docker compose alpha
+plink: docker_compose_alpha.yaml
+deprecated: false
+experimental: false
+experimentalcli: true
+kubernetes: false
+swarm: false
+

_data/compose-cli/docker_compose_alpha_watch.yaml

@@ -0,0 +1,25 @@
+command: docker compose alpha watch
+short: |
+    EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated
+long: |
+    EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated
+usage: docker compose alpha watch [SERVICE...]
+pname: docker compose alpha
+plink: docker_compose_alpha.yaml
+options:
+    - option: quiet
+      value_type: bool
+      default_value: "false"
+      description: hide build output
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+deprecated: false
+experimental: false
+experimentalcli: true
+kubernetes: false
+swarm: false
+

_data/compose-cli/docker_compose_build.yaml

@@ -106,6 +106,16 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: push
+      value_type: bool
+      default_value: "false"
+      description: Push service images.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: quiet
       shorthand: q
       value_type: bool

_data/compose-cli/docker_compose_config.yaml

@@ -1,13 +1,11 @@
-command: docker compose convert
+command: docker compose config
-aliases: docker compose convert, docker compose config
+aliases: docker compose config, docker compose convert
-short: Converts the compose file to platform's canonical format
+short: Parse, resolve and render compose file in canonical format
 long: |-
-    `docker compose convert` renders the actual data model to be applied on the target platform. When used with the Docker engine,
+    `docker compose config` renders the actual data model to be applied on the Docker engine.
     it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
     the canonical format.
-
+usage: docker compose config [OPTIONS] [SERVICE...]
-    To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`
-usage: docker compose convert [OPTIONS] [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
 options:

_data/compose-cli/docker_compose_create.yaml

@@ -57,6 +57,27 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: remove-orphans
+      value_type: bool
+      default_value: "false"
+      description: Remove containers for services not defined in the Compose file.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: scale
+      value_type: stringArray
+      default_value: '[]'
+      description: |
+        Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 experimental: false
 experimentalcli: false

_data/compose-cli/docker_compose_logs.yaml

@@ -47,6 +47,7 @@ options:
       kubernetes: false
       swarm: false
     - option: tail
+      shorthand: "n"
       value_type: string
       default_value: all
       description: |

_data/compose-cli/docker_compose_ps.yaml

@@ -2,13 +2,20 @@ command: docker compose ps
 short: List containers
 long: |-
     Lists containers for a Compose project, with current status and exposed ports.
-    By default, both running and stopped containers are shown:
 
     ```console
     $ docker compose ps
-    NAME           COMMAND                  SERVICE   STATUS       PORTS
+    NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
-    example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
+    example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
-    example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp
+    ```
+
+    By default, only running containers are shown. `--all` flag can be used to include stopped containers
+
+    ```console
+    $ docker compose ps --all
+    NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
+    example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
+    example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)
     ```
 usage: docker compose ps [OPTIONS] [SERVICE...]
 pname: docker compose
@@ -139,12 +146,12 @@ examples: |-
 
     ```console
     $ docker compose ps --status=running
-    NAME           COMMAND                  SERVICE   STATUS       PORTS
+    NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
-    example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp
+    example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
 
     $ docker compose ps --status=exited
-    NAME           COMMAND                  SERVICE   STATUS       PORTS
+    NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
-    example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
+    example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)
     ```
 
     ### Filter containers by status (--filter) {#filter}
@@ -155,12 +162,8 @@ examples: |-
 
     ```console
     $ docker compose ps --filter status=running
-    NAME           COMMAND                  SERVICE   STATUS       PORTS
+    NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
-    example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->80/tcp
+    example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
-
-    $ docker compose ps --filter status=running
-    NAME           COMMAND                  SERVICE   STATUS       PORTS
-    example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
     ```
 
     The `docker compose ps` command currently only supports the `--filter status=<status>`

_data/compose-cli/docker_compose_run.yaml

@@ -172,6 +172,16 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: remove-orphans
+      value_type: bool
+      default_value: "false"
+      description: Remove containers for services not defined in the Compose file.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: rm
       value_type: bool
       default_value: "false"

_data/toc.yaml

@@ -313,6 +313,8 @@ reference:
           title: docker compose
         - path: /engine/reference/commandline/compose_build/
           title: docker compose build
+        - path: /engine/reference/commandline/compose_config/
+          title: docker compose config
         - path: /engine/reference/commandline/compose_convert/
           title: docker compose convert
         - path: /engine/reference/commandline/compose_cp/

_redirects.yml

@@ -128,7 +128,6 @@
 "/desktop/windows/wsl/":
   # Link used by Docker Desktop to refer users on how to activate WSL 2
   - /go/wsl2/
-
 # samples
 "https://hub.docker.com/_/adminer/":
   - /samples/adminer

compose/environment-variables/set-environment-variables.md

@@ -30,7 +30,7 @@ services:
 
 When you run `docker compose up`, the `web` service defined in the Compose file substitues in the
 image `webapp:v1.5` which was set in the `.env` file. You can verify this with the
-[convert command](../../engine/reference/commandline/compose_convert.md), which prints your resolved application config to the terminal:
+[convert command](../../engine/reference/commandline/compose_config.md), which prints your resolved application config to the terminal:
 
 ```console
 $ docker compose convert

engine/reference/commandline/compose_config.md

@@ -1,9 +1,10 @@
 ---
 datafolder: compose-cli
-datafile: docker_compose_convert
+datafile: docker_compose_config
-title: docker compose convert
+title: docker compose config
 redirect_from:
-- /compose/reference/config/
+  - /compose/reference/config/
+  - /engine/reference/commandline/compose_convert/
 ---
 <!--
 Sorry, but the contents of this page are automatically generated from