Update dry-run documentation

Co-authored-by: Allie Sadler <[email protected]>
Signed-off-by: Guillaume Lours <[email protected]>

Author: 2 people

docs/reference/compose.md

@@ -175,7 +175,7 @@ containers for the project.
 ### Use Dry Run mode to test your command
 
 Use `--dry-run` flag to test a command without changing your application stack state.
-Dry Run mode will show you all the steps Compose will apply by executing the command, for example:
+Dry Run mode shows you all the steps Compose applies when executing a command, for example:
 ```console
 $ docker compose --dry-run up --build -d
 [+] Pulling 1/1
@@ -192,10 +192,10 @@ $ docker compose --dry-run up --build -d
  ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Started                                                                                                                                           0.0s
  ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Started                                     Started
 ```
-You could see that the first step will be to pull the image defined by `db` service, then build the `backend` service.  
-After that, containers will be created, the `db` service started and the `backend` and `proxy` will wait until `db` service is healthy to start.
+From the example above, you can see that the first step is to pull the image defined by `db` service, then build the `backend` service.  
+Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting.
 
-The Dry Run mode is not supported by all commands, especially by the command which doesn't change the state of a Compose stack
+Dry Run mode does not currently work with all commands. In particular, you cannot use Dry Run mode with a command that doesn't change the state of a Compose stack
 such as `ps`, `ls`, `logs` for example.  
 
 Here the list of commands supporting `--dry-run` flag:

docs/reference/compose_alpha.md

@@ -11,6 +11,12 @@ Experimental commands
 | [`watch`](compose_alpha_watch.md) | EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated |
 
 
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
 
 <!---MARKER_GEN_END-->
 

docs/reference/compose_alpha_viz.md

@@ -7,6 +7,7 @@ EXPERIMENTAL - Generate a graphviz graph from your compose file
 
 | Name                 | Type  | Default | Description                                                                                        |
 |:---------------------|:------|:--------|:---------------------------------------------------------------------------------------------------|
+| `--dry-run`          |       |         | Execute command in dry run mode                                                                    |
 | `--image`            |       |         | Include service's image name in output graph                                                       |
 | `--indentation-size` | `int` | `1`     | Number of tabs or spaces to use for indentation                                                    |
 | `--networks`         |       |         | Include service's attached networks in output graph                                                |

docs/reference/compose_alpha_watch.md

@@ -5,9 +5,10 @@ EXPERIMENTAL - Watch build context for service and rebuild/refresh containers wh
 
 ### Options
 
-| Name      | Type | Default | Description       |
-|:----------|:-----|:--------|:------------------|
-| `--quiet` |      |         | hide build output |
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+| `--quiet`   |      |         | hide build output               |
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_build.md

@@ -8,6 +8,7 @@ Build or rebuild services
 | Name             | Type          | Default | Description                                                                                                 |
 |:-----------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------|
 | `--build-arg`    | `stringArray` |         | Set build-time variables for services.                                                                      |
+| `--dry-run`      |               |         | Execute command in dry run mode                                                                             |
 | `-m`, `--memory` | `bytes`       | `0`     | Set memory limit for the build container. Not supported by BuildKit.                                        |
 | `--no-cache`     |               |         | Do not use cache when building the image                                                                    |
 | `--progress`     | `string`      | `auto`  | Set type of progress output (auto, tty, plain, quiet)                                                       |

docs/reference/compose_config.md

@@ -11,6 +11,7 @@ Parse, resolve and render compose file in canonical format
 
 | Name                      | Type     | Default | Description                                                                 |
 |:--------------------------|:---------|:--------|:----------------------------------------------------------------------------|
+| `--dry-run`               |          |         | Execute command in dry run mode                                             |
 | `--format`                | `string` | `yaml`  | Format the output. Values: [yaml \| json]                                   |
 | `--hash`                  | `string` |         | Print the service config hash, one per line.                                |
 | `--images`                |          |         | Print the image names, one per line.                                        |

docs/reference/compose_cp.md

@@ -8,6 +8,7 @@ Copy files/folders between a service container and the local filesystem
 | Name                  | Type  | Default | Description                                                           |
 |:----------------------|:------|:--------|:----------------------------------------------------------------------|
 | `-a`, `--archive`     |       |         | Archive mode (copy all uid/gid information)                           |
+| `--dry-run`           |       |         | Execute command in dry run mode                                       |
 | `-L`, `--follow-link` |       |         | Always follow symbol link in SRC_PATH                                 |
 | `--index`             | `int` | `0`     | Index of the container if there are multiple instances of a service . |
 

docs/reference/compose_create.md

@@ -8,6 +8,7 @@ Creates containers for a service.
 | Name               | Type          | Default   | Description                                                                                   |
 |:-------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------|
 | `--build`          |               |           | Build images before starting containers.                                                      |
+| `--dry-run`        |               |           | Execute command in dry run mode                                                               |
 | `--force-recreate` |               |           | Recreate containers even if their configuration and image haven't changed.                    |
 | `--no-build`       |               |           | Don't build an image, even if it's missing.                                                   |
 | `--no-recreate`    |               |           | If containers already exist, don't recreate them. Incompatible with --force-recreate.         |

docs/reference/compose_down.md

@@ -7,6 +7,7 @@ Stop and remove containers, networks
 
 | Name               | Type     | Default | Description                                                                                                              |
 |:-------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------|
+| `--dry-run`        |          |         | Execute command in dry run mode                                                                                          |
 | `--remove-orphans` |          |         | Remove containers for services not defined in the Compose file.                                                          |
 | `--rmi`            | `string` |         | Remove images used by services. "local" remove only images that don't have a custom tag ("local"\|"all")                 |
 | `-t`, `--timeout`  | `int`    | `10`    | Specify a shutdown timeout in seconds                                                                                    |

docs/reference/compose_events.md

@@ -5,9 +5,10 @@ Receive real time events from containers.
 
 ### Options
 
-| Name     | Type | Default | Description                               |
-|:---------|:-----|:--------|:------------------------------------------|
-| `--json` |      |         | Output events as a stream of json objects |
+| Name        | Type | Default | Description                               |
+|:------------|:-----|:--------|:------------------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode           |
+| `--json`    |      |         | Output events as a stream of json objects |
 
 
 <!---MARKER_GEN_END-->