From e8caad1903124c55f714825e5f11bf339910f8cf Mon Sep 17 00:00:00 2001 From: Guillaume Lours <705411+glours@users.noreply.github.com> Date: Fri, 5 May 2023 10:40:18 +0200 Subject: [PATCH] move dry-run support from alpha to main command Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com> --- cmd/compose/alpha.go | 21 ----------- cmd/compose/compose.go | 3 +- docs/reference/compose.md | 47 ++++++++++++++++++++++++ docs/reference/compose_alpha.md | 9 ++--- docs/reference/docker_compose.yaml | 47 +++++++++++++++++++++++- docs/reference/docker_compose_alpha.yaml | 2 - 6 files changed, 98 insertions(+), 31 deletions(-) diff --git a/cmd/compose/alpha.go b/cmd/compose/alpha.go index a05210d51..5eaeaa9e2 100644 --- a/cmd/compose/alpha.go +++ b/cmd/compose/alpha.go @@ -15,8 +15,6 @@ package compose import ( - "context" - "github.com/docker/compose/v2/pkg/api" "github.com/spf13/cobra" ) @@ -33,26 +31,7 @@ func alphaCommand(p *ProjectOptions, backend api.Service) *cobra.Command { } cmd.AddCommand( watchCommand(p, backend), - dryRunRedirectCommand(p), vizCommand(p, backend), ) return cmd } - -// Temporary alpha command as the dry-run will be implemented with a flag -func dryRunRedirectCommand(p *ProjectOptions) *cobra.Command { - cmd := &cobra.Command{ - Use: "dry-run -- [COMMAND...]", - Short: "EXPERIMENTAL - Dry run command allow you to test a command without applying changes", - PreRunE: Adapt(func(ctx context.Context, args []string) error { - return nil - }), - RunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error { - rootCmd := cmd.Root() - rootCmd.SetArgs(append([]string{"compose", "--dry-run"}, args...)) - return rootCmd.Execute() - }), - ValidArgsFunction: completeServiceNames(p), - } - return cmd -} diff --git a/cmd/compose/compose.go b/cmd/compose/compose.go index 4ad90b418..d711b23d1 100644 --- a/cmd/compose/compose.go +++ b/cmd/compose/compose.go @@ -399,13 +399,12 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no c.Flags().StringVar(&ansi, "ansi", "auto", `Control when to print ANSI control characters ("never"|"always"|"auto")`) c.Flags().IntVar(¶llel, "parallel", -1, `Control max parallelism, -1 for unlimited`) c.Flags().BoolVarP(&version, "version", "v", false, "Show the Docker Compose version information") + c.PersistentFlags().BoolVar(&dryRun, "dry-run", false, "Execute command in dry run mode") c.Flags().MarkHidden("version") //nolint:errcheck c.Flags().BoolVar(&noAnsi, "no-ansi", false, `Do not print ANSI control characters (DEPRECATED)`) c.Flags().MarkHidden("no-ansi") //nolint:errcheck c.Flags().BoolVar(&verbose, "verbose", false, "Show more output") c.Flags().MarkHidden("verbose") //nolint:errcheck - c.Flags().BoolVar(&dryRun, "dry-run", false, "Execute command in dry run mode") - c.Flags().MarkHidden("dry-run") //nolint:errcheck return c } diff --git a/docs/reference/compose.md b/docs/reference/compose.md index 6f48a6df9..01ce96d5e 100644 --- a/docs/reference/compose.md +++ b/docs/reference/compose.md @@ -41,6 +41,7 @@ Define and run multi-container applications with Docker. |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------| | `--ansi` | `string` | `auto` | Control when to print ANSI control characters ("never"\|"always"\|"auto") | | `--compatibility` | | | Run compose in backward compatibility mode | +| `--dry-run` | | | Execute command in dry run mode | | `--env-file` | `stringArray` | | Specify an alternate environment file. | | `-f`, `--file` | `stringArray` | | Compose configuration files | | `--parallel` | `int` | `-1` | Control max parallelism, -1 for unlimited | @@ -169,3 +170,49 @@ If flags are explicitly set on the command line, the associated environment vari Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned 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: +```console +$ docker compose --dry-run up --build -d +[+] Pulling 1/1 + ✔ DRY-RUN MODE - db Pulled 0.9s +[+] Running 10/8 + ✔ DRY-RUN MODE - build service backend 0.0s + ✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s + ✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s + ✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s + ✔ 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. + +The Dry Run mode is not supported by all commands, especially by the command which 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: +* build +* cp +* create +* down +* exec +* kill +* pause +* pull +* push +* remove +* restart +* run +* start +* stop +* unpause +* up + diff --git a/docs/reference/compose_alpha.md b/docs/reference/compose_alpha.md index 0aef6400f..af9fd171f 100644 --- a/docs/reference/compose_alpha.md +++ b/docs/reference/compose_alpha.md @@ -5,11 +5,10 @@ Experimental commands ### Subcommands -| Name | Description | -|:--------------------------------------|:-----------------------------------------------------------------------------------------------------| -| [`dry-run`](compose_alpha_dry-run.md) | EXPERIMENTAL - Dry run command allow you to test a command without applying changes | -| [`viz`](compose_alpha_viz.md) | EXPERIMENTAL - Generate a graphviz graph from your compose file | -| [`watch`](compose_alpha_watch.md) | EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated | +| Name | Description | +|:----------------------------------|:-----------------------------------------------------------------------------------------------------| +| [`viz`](compose_alpha_viz.md) | EXPERIMENTAL - Generate a graphviz graph from your compose file | +| [`watch`](compose_alpha_watch.md) | EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated | diff --git a/docs/reference/docker_compose.yaml b/docs/reference/docker_compose.yaml index 16b3d3fd9..bce174ba3 100644 --- a/docs/reference/docker_compose.yaml +++ b/docs/reference/docker_compose.yaml @@ -117,6 +117,51 @@ long: |- Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned 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: + ```console + $ docker compose --dry-run up --build -d + [+] Pulling 1/1 + ✔ DRY-RUN MODE - db Pulled 0.9s + [+] Running 10/8 + ✔ DRY-RUN MODE - build service backend 0.0s + ✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s + ✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s + ✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s + ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s + ✔ 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. + + The Dry Run mode is not supported by all commands, especially by the command which 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: + * build + * cp + * create + * down + * exec + * kill + * pause + * pull + * push + * remove + * restart + * run + * start + * stop + * unpause + * up usage: docker compose pname: docker plink: docker.yaml @@ -199,7 +244,7 @@ options: default_value: "false" description: Execute command in dry run mode deprecated: false - hidden: true + hidden: false experimental: false experimentalcli: false kubernetes: false diff --git a/docs/reference/docker_compose_alpha.yaml b/docs/reference/docker_compose_alpha.yaml index 612430f84..4cfcd9c9f 100644 --- a/docs/reference/docker_compose_alpha.yaml +++ b/docs/reference/docker_compose_alpha.yaml @@ -4,11 +4,9 @@ long: Experimental commands pname: docker compose plink: docker_compose.yaml cname: - - docker compose alpha dry-run - docker compose alpha viz - docker compose alpha watch clink: - - docker_compose_alpha_dry-run.yaml - docker_compose_alpha_viz.yaml - docker_compose_alpha_watch.yaml deprecated: false