introduce publish (alpha) command

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

.github/dependabot.yml

@@ -5,14 +5,20 @@ updates:
     schedule:
       interval: daily
     ignore:
-      # docker/buildx + docker/cli + docker/docker require coordination to
-      # ensure compatibility between them
+      # docker + moby deps require coordination
       - dependency-name: "github.com/docker/buildx"
         # buildx is still 0.x
         update-types: ["version-update:semver-minor"]
+      - dependency-name: "github.com/moby/buildkit"
+        # buildkit is still 0.x
+        update-types: [ "version-update:semver-minor" ]
       - dependency-name: "github.com/docker/cli"
-        # docker/cli uses CalVer rather than SemVer
-        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+        update-types: ["version-update:semver-major"]
       - dependency-name: "github.com/docker/docker"
-        # docker/docker uses CalVer rather than SemVer
-        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "github.com/containerd/containerd"
+        # containerd major/minor must be kept in sync with moby
+        update-types: [ "version-update:semver-major", "version-update:semver-minor" ]
+      - dependency-name: "go.opentelemetry.io/otel/*"
+        # OTEL is v1.x but has some parts that are not API stable yet
+        update-types: [ "version-update:semver-major", "version-update:semver-minor"]

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ concurrency:
 on:
   push:
     branches:
-      - 'v2'
+      - 'main'
     tags:
       - 'v*'
   pull_request:
@@ -19,7 +19,6 @@ on:
         default: "false"
 
 env:
-  DESTDIR: "./bin"
   DOCKER_CLI_VERSION: "20.10.17"
 
 permissions:
@@ -103,7 +102,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: compose
-          path: ${{ env.DESTDIR }}/*
+          path: ./bin/release/*
           if-no-files-found: error
 
   test:
@@ -124,13 +123,15 @@ jobs:
             *.cache-from=type=gha,scope=test
             *.cache-to=type=gha,scope=test
       -
-        name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
+        name: Gather coverage data
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-data-unit
+          path: bin/coverage/unit/
+          if-no-files-found: error
 
   e2e:
     runs-on: ubuntu-latest
-    env:
-      DESTDIR: "./bin/build"
     strategy:
       fail-fast: false
       matrix:
@@ -179,11 +180,17 @@ jobs:
         name: Test plugin mode
         if: ${{ matrix.mode == 'plugin' }}
         run: |
-          rm -rf ./covdatafiles
-          mkdir ./covdatafiles
-          make e2e-compose GOCOVERDIR=covdatafiles
-          go tool covdata textfmt -i=covdatafiles -o=coverage.out
-
+          rm -rf ./bin/coverage/e2e
+          mkdir -p ./bin/coverage/e2e
+          make e2e-compose GOCOVERDIR=bin/coverage/e2e TEST_FLAGS="-v"
+      -
+        name: Gather coverage data
+        if: ${{ matrix.mode == 'plugin' }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-data-e2e
+          path: bin/coverage/e2e/
+          if-no-files-found: error
       -
         name: Test standalone mode
         if: ${{ matrix.mode == 'standalone' }}
@@ -196,9 +203,44 @@ jobs:
         if: ${{ matrix.mode == 'cucumber'}}
         run: |
           make test-cucumber
-      -
-        name: Upload coverage to Codecov
+
+  coverage:
+    runs-on: ubuntu-22.04
+    needs:
+      - test
+      - e2e
+    steps:
+      # codecov won't process the report without the source code available
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version-file: 'go.mod'
+          check-latest: true
+      - name: Download unit test coverage
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-data-unit
+          path: coverage/unit
+      - name: Download E2E test coverage
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-data-e2e
+          path: coverage/e2e
+      - name: Merge coverage reports
+        run: |
+          go tool covdata textfmt -i=./coverage/unit,./coverage/e2e -o ./coverage.txt
+      - name: Store coverage report in GitHub Actions
+        uses: actions/upload-artifact@v3
+        with:
+          name: go-covdata-txt
+          path: ./coverage.txt
+          if-no-files-found: error
+      - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.txt
 
   release:
     permissions:
@@ -216,10 +258,10 @@ jobs:
         uses: actions/download-artifact@v3
         with:
           name: compose
-          path: ${{ env.DESTDIR }}
+          path: bin/release
       -
         name: Create checksums
-        working-directory: ${{ env.DESTDIR }}
+        working-directory: bin/release
         run: |
           find . -type f -print0 | sort -z | xargs -r0 shasum -a 256 -b | sed 's# \*\./# *#' > $RUNNER_TEMP/checksums.txt
           shasum -a 256 -U -c $RUNNER_TEMP/checksums.txt
@@ -227,21 +269,21 @@ jobs:
           cat checksums.txt | while read sum file; do echo "$sum $file" > ${file#\*}.sha256; done
       -
         name: License
-        run: cp packaging/* ${{ env.DESTDIR }}/
+        run: cp packaging/* bin/release/
       -
         name: List artifacts
         run: |
-          tree -nh ${{ env.DESTDIR }}
+          tree -nh bin/release
       -
         name: Check artifacts
         run: |
-          find ${{ env.DESTDIR }} -type f -exec file -e ascii -- {} +
+          find bin/release -type f -exec file -e ascii -- {} +
       -
         name: GitHub Release
         if: startsWith(github.ref, 'refs/tags/v')
         uses: ncipollo/release-action@58ae73b360456532aafd58ee170c045abbeaee37 # v1.10.0
         with:
-          artifacts: ${{ env.DESTDIR }}/*
+          artifacts: bin/release/*
           generateReleaseNotes: true
           draft: true
           token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/merge.yml

@@ -7,7 +7,7 @@ concurrency:
 on:
   push:
     branches:
-      - 'v2'
+      - 'main'
     tags:
       - 'v*'
 
@@ -76,6 +76,8 @@ jobs:
 
   bin-image:
     runs-on: ubuntu-22.04
+    outputs:
+      digest: ${{ fromJSON(steps.bake.outputs.metadata).image-cross['containerimage.digest'] }}
     steps:
       -
         name: Checkout
@@ -107,6 +109,7 @@ jobs:
       -
         name: Build and push image
         uses: docker/bake-action@v2
+        id: bake
         with:
           files: |
             ./docker-bake.hcl
@@ -118,3 +121,31 @@ jobs:
             *.cache-to=type=gha,scope=bin-image,mode=max
             *.attest=type=sbom
             *.attest=type=provenance,mode=max,builder-id=https://github.com/${{ env.GITHUB_REPOSITORY }}/actions/runs/${{ env.GITHUB_RUN_ID }}
+
+  desktop-edge-test:
+    runs-on: ubuntu-latest
+    needs: bin-image
+    steps:
+      -
+        name: Generate Token
+        id: generate_token
+        uses: tibdex/github-app-token@v1
+        with:
+          app_id: ${{ vars.DOCKERDESKTOP_APP_ID }}
+          private_key: ${{ secrets.DOCKERDESKTOP_APP_PRIVATEKEY }}
+          repository: docker/${{ secrets.DOCKERDESKTOP_REPO }}
+      -
+        name: Trigger Docker Desktop e2e with edge version
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ steps.generate_token.outputs.token }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: 'docker',
+              repo: '${{ secrets.DOCKERDESKTOP_REPO }}',
+              workflow_id: 'compose-edge-integration.yml',
+              ref: 'main',
+              inputs: {
+                "image-tag": "${{ needs.bin-image.outputs.digest }}"
+              }
+            })

.github/workflows/scorecards.yml

@@ -5,7 +5,7 @@ on:
   schedule:
     - cron: '44 9 * * 4'
   push:
-    branches: [ "v2" ]
+    branches: [ "main" ]
 
 # Declare default permissions as read only.
 permissions: read-all

.golangci.yml

@@ -31,12 +31,11 @@ linters-settings:
       - name: package-comments
         disabled: true
   depguard:
-    list-type: denylist
-    include-go-root: true
-    packages:
-      # The io/ioutil package has been deprecated.
-      # https://go.dev/doc/go1.16#ioutil
-      - io/ioutil
+    rules:
+      all:
+        deny:
+          - pkg: io/ioutil
+            desc: 'io/ioutil package has been deprecated'
   gomodguard:
     blocked:
       versions:

Dockerfile

@@ -15,9 +15,9 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-ARG GO_VERSION=1.20.2
-ARG XX_VERSION=1.1.2
-ARG GOLANGCI_LINT_VERSION=v1.52.0
+ARG GO_VERSION=1.21.0
+ARG XX_VERSION=1.2.1
+ARG GOLANGCI_LINT_VERSION=v1.53.2
 ARG ADDLICENSE_VERSION=v1.0.0
 
 ARG BUILD_TAGS="e2e"
@@ -84,13 +84,14 @@ RUN --mount=type=bind,target=. \
     --mount=type=bind,from=osxcross,src=/osxsdk,target=/xx-sdk \
     xx-go --wrap && \
     if [ "$(xx-info os)" == "darwin" ]; then export CGO_ENABLED=1; fi && \
-    make build GO_BUILDTAGS="$BUILD_TAGS" DESTDIR=/usr/bin && \
-    xx-verify --static /usr/bin/docker-compose
+    make build GO_BUILDTAGS="$BUILD_TAGS" DESTDIR=/out && \
+    xx-verify --static /out/docker-compose
 
 FROM build-base AS lint
 ARG BUILD_TAGS
 RUN --mount=type=bind,target=. \
     --mount=type=cache,target=/root/.cache \
+    --mount=type=cache,target=/go/pkg/mod \
     --mount=from=golangci-lint,source=/usr/bin/golangci-lint,target=/usr/bin/golangci-lint \
     golangci-lint run --build-tags "$BUILD_TAGS" ./...
 
@@ -100,11 +101,13 @@ ARG BUILD_TAGS
 RUN --mount=type=bind,target=. \
     --mount=type=cache,target=/root/.cache \
     --mount=type=cache,target=/go/pkg/mod \
-    go test -tags "$BUILD_TAGS" -v -coverprofile=/tmp/coverage.txt -covermode=atomic $(go list  $(TAGS) ./... | grep -vE 'e2e') && \
-    go tool cover -func=/tmp/coverage.txt
+    rm -rf /tmp/coverage && \
+    mkdir -p /tmp/coverage && \
+    go test -tags "$BUILD_TAGS" -v -cover -covermode=atomic $(go list  $(TAGS) ./... | grep -vE 'e2e') -args -test.gocoverdir="/tmp/coverage" && \
+    go tool covdata percent -i=/tmp/coverage
 
 FROM scratch AS test-coverage
-COPY --from=test /tmp/coverage.txt /coverage.txt
+COPY --from=test --link /tmp/coverage /
 
 FROM base AS license-set
 ARG LICENSE_FILES
@@ -127,6 +130,7 @@ FROM base AS docsgen
 WORKDIR /src
 RUN --mount=target=. \
     --mount=target=/root/.cache,type=cache \
+    --mount=type=cache,target=/go/pkg/mod \
     go build -o /out/docsgen ./docs/yaml/main/generate.go
 
 FROM --platform=${BUILDPLATFORM} alpine AS docs-build
@@ -162,11 +166,11 @@ RUN --mount=target=/context \
 EOT
 
 FROM scratch AS binary-unix
-COPY --link --from=build /usr/bin/docker-compose /
+COPY --link --from=build /out/docker-compose /
 FROM binary-unix AS binary-darwin
 FROM binary-unix AS binary-linux
 FROM scratch AS binary-windows
-COPY --link --from=build /usr/bin/docker-compose /docker-compose.exe
+COPY --link --from=build /out/docker-compose /docker-compose.exe
 FROM binary-$TARGETOS AS binary
 # enable scanning for this stage
 ARG BUILDKIT_SBOM_SCAN_STAGE=true

Makefile

@@ -17,29 +17,18 @@ VERSION ?= $(shell git describe --match 'v[0-9]*' --dirty='.m' --always --tags)
 
 GO_LDFLAGS ?= -w -X ${PKG}/internal.Version=${VERSION}
 GO_BUILDTAGS ?= e2e
-
+DRIVE_PREFIX?=
 ifeq ($(OS),Windows_NT)
     DETECTED_OS = Windows
+    DRIVE_PREFIX=C:
 else
     DETECTED_OS = $(shell uname -s)
 endif
 
-ifeq ($(DETECTED_OS),Linux)
-	MOBY_DOCKER=/usr/bin/docker
-endif
-ifeq ($(DETECTED_OS),Darwin)
-	MOBY_DOCKER=/Applications/Docker.app/Contents/Resources/bin/docker
-endif
 ifeq ($(DETECTED_OS),Windows)
 	BINARY_EXT=.exe
 endif
 
-TEST_COVERAGE_FLAGS = -coverprofile=coverage.out -covermode=atomic
-ifneq ($(DETECTED_OS),Windows)
-	# go race detector requires gcc on Windows so not used by default
-	# https://github.com/golang/go/issues/27089
-	TEST_COVERAGE_FLAGS += -race
-endif
 BUILD_FLAGS?=
 TEST_FLAGS?=
 E2E_TEST?=
@@ -49,13 +38,23 @@ else
 endif
 
 BUILDX_CMD ?= docker buildx
-DESTDIR ?= ./bin/build
+
+# DESTDIR overrides the output path for binaries and other artifacts
+# this is used by docker/docker-ce-packaging for the apt/rpm builds,
+# so it's important that the resulting binary ends up EXACTLY at the
+# path $DESTDIR/docker-compose when specified.
+#
+# See https://github.com/docker/docker-ce-packaging/blob/e43fbd37e48fde49d907b9195f23b13537521b94/rpm/SPECS/docker-compose-plugin.spec#L47
+#
+# By default, all artifacts go to subdirectories under ./bin/ in the
+# repo root, e.g. ./bin/build, ./bin/coverage, ./bin/release.
+DESTDIR ?=
 
 all: build
 
 .PHONY: build ## Build the compose cli-plugin
 build:
-	GO111MODULE=on go build $(BUILD_FLAGS) -trimpath -tags "$(GO_BUILDTAGS)" -ldflags "$(GO_LDFLAGS)" -o "$(DESTDIR)/docker-compose$(BINARY_EXT)" ./cmd
+	GO111MODULE=on go build $(BUILD_FLAGS) -trimpath -tags "$(GO_BUILDTAGS)" -ldflags "$(GO_LDFLAGS)" -o "$(or $(DESTDIR),./bin/build)/docker-compose$(BINARY_EXT)" ./cmd
 
 .PHONY: binary
 binary:
@@ -68,7 +67,7 @@ binary-with-coverage:
 .PHONY: install
 install: binary
 	mkdir -p ~/.docker/cli-plugins
-	install bin/build/docker-compose ~/.docker/cli-plugins/docker-compose
+	install $(or $(DESTDIR),./bin/build)/docker-compose ~/.docker/cli-plugins/docker-compose
 
 .PHONY: e2e-compose
 e2e-compose: ## Run end to end local tests in plugin mode. Set E2E_TEST=TestName to run a single test
@@ -122,8 +121,8 @@ docs: ## generate documentation
 	$(eval $@_TMP_OUT := $(shell mktemp -d -t compose-output.XXXXXXXXXX))
 	$(BUILDX_CMD) bake --set "*.output=type=local,dest=$($@_TMP_OUT)" docs-update
 	rm -rf ./docs/internal
-	cp -R "$($@_TMP_OUT)"/out/* ./docs/
-	rm -rf "$($@_TMP_OUT)"/*
+	cp -R "$(DRIVE_PREFIX)$($@_TMP_OUT)"/out/* ./docs/
+	rm -rf "$(DRIVE_PREFIX)$($@_TMP_OUT)"/*
 
 .PHONY: validate-docs
 validate-docs: ## validate the doc does not change

README.md

@@ -6,13 +6,14 @@
     + [Linux](#linux)
 - [Quick Start](#quick-start)
 - [Contributing](#contributing)
+- [Legacy](#legacy)
 # Docker Compose v2
 
 [![GitHub release](https://img.shields.io/github/release/docker/compose.svg?style=flat-square)](https://github.com/docker/compose/releases/latest)
 [![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?style=flat-square&logo=go&logoColor=white)](https://pkg.go.dev/github.com/docker/compose/v2)
-[![Build Status](https://img.shields.io/github/workflow/status/docker/compose/ci?label=ci&logo=github&style=flat-square)](https://github.com/docker/compose/actions?query=workflow%3Aci)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/docker/compose/ci.yml?label=ci&logo=github&style=flat-square)](https://github.com/docker/compose/actions?query=workflow%3Aci)
 [![Go Report Card](https://goreportcard.com/badge/github.com/docker/compose/v2?style=flat-square)](https://goreportcard.com/report/github.com/docker/compose/v2)
-[![Codecov](https://codecov.io/gh/docker/compose/branch/master/graph/badge.svg?token=HP3K4Y4ctu)](https://codecov.io/gh/docker/compose)
+[![Codecov](https://codecov.io/gh/docker/compose/branch/main/graph/badge.svg?token=HP3K4Y4ctu)](https://codecov.io/gh/docker/compose)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/docker/compose/badge)](https://api.securityscorecards.dev/projects/github.com/docker/compose)
 ![Docker Compose](logo.png?raw=true "Docker Compose Logo")
 
@@ -23,12 +24,6 @@ your application are configured.
 Once you have a Compose file, you can create and start your application with a
 single command: `docker compose up`.
 
-# About update and backward compatibility
-
-Docker Compose V2 is a major version bump release of Docker Compose. It has been completely rewritten from scratch in Golang (V1 was in Python). The installation instructions for Compose V2 differ from V1. V2 is not a standalone binary anymore, and installation scripts will have to be adjusted. Some commands are different.
-
-For a smooth transition from legacy docker-compose 1.xx, please consider installing [compose-switch](https://github.com/docker/compose-switch) to translate `docker-compose ...` commands into Compose V2's `docker compose .... `. Also check V2's `--compatibility` flag.
-
 # Where to get Docker Compose
 
 ### Windows and macOS
@@ -85,3 +80,8 @@ Want to help develop Docker Compose? Check out our
 
 If you find an issue, please report it on the
 [issue tracker](https://github.com/docker/compose/issues/new/choose).
+
+Legacy
+-------------
+
+The Python version of Compose is available under the `v1` [branch](https://github.com/docker/compose/tree/v1)

cmd/cmdtrace/cmd_span.go

@@ -0,0 +1,131 @@
+/*
+   Copyright 2023 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package cmdtrace
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	dockercli "github.com/docker/cli/cli"
+	"github.com/docker/cli/cli/command"
+	commands "github.com/docker/compose/v2/cmd/compose"
+	"github.com/docker/compose/v2/internal/tracing"
+	"github.com/spf13/cobra"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// Setup should be called as part of the command's PersistentPreRunE
+// as soon as possible after initializing the dockerCli.
+//
+// It initializes the tracer for the CLI using both auto-detection
+// from the Docker context metadata as well as standard OTEL_ env
+// vars, creates a root span for the command, and wraps the actual
+// command invocation to ensure the span is properly finalized and
+// exported before exit.
+func Setup(cmd *cobra.Command, dockerCli command.Cli) error {
+	tracingShutdown, err := tracing.InitTracing(dockerCli)
+	if err != nil {
+		return fmt.Errorf("initializing tracing: %w", err)
+	}
+
+	ctx := cmd.Context()
+	ctx, cmdSpan := tracing.Tracer.Start(
+		ctx,
+		"cli/"+strings.Join(commandName(cmd), "-"),
+	)
+	cmd.SetContext(ctx)
+	wrapRunE(cmd, cmdSpan, tracingShutdown)
+	return nil
+}
+
+// wrapRunE injects a wrapper function around the command's actual RunE (or Run)
+// method. This is necessary to capture the command result for reporting as well
+// as flushing any spans before exit.
+//
+// Unfortunately, PersistentPostRun(E) can't be used for this purpose because it
+// only runs if RunE does _not_ return an error, but this should run unconditionally.
+func wrapRunE(c *cobra.Command, cmdSpan trace.Span, tracingShutdown tracing.ShutdownFunc) {
+	origRunE := c.RunE
+	if origRunE == nil {
+		origRun := c.Run
+		//nolint:unparam // wrapper function for RunE, always returns nil by design
+		origRunE = func(cmd *cobra.Command, args []string) error {
+			origRun(cmd, args)
+			return nil
+		}
+		c.Run = nil
+	}
+
+	c.RunE = func(cmd *cobra.Command, args []string) error {
+		cmdErr := origRunE(cmd, args)
+		if cmdSpan != nil {
+			if cmdErr != nil && !errors.Is(cmdErr, context.Canceled) {
+				// default exit code is 1 if a more descriptive error
+				// wasn't returned
+				exitCode := 1
+				var statusErr dockercli.StatusError
+				if errors.As(cmdErr, &statusErr) {
+					exitCode = statusErr.StatusCode
+				}
+				cmdSpan.SetStatus(codes.Error, "CLI command returned error")
+				cmdSpan.RecordError(cmdErr, trace.WithAttributes(
+					attribute.Int("exit_code", exitCode),
+				))
+
+			} else {
+				cmdSpan.SetStatus(codes.Ok, "")
+			}
+			cmdSpan.End()
+		}
+		if tracingShutdown != nil {
+			// use background for root context because the cmd's context might have
+			// been canceled already
+			ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+			defer cancel()
+			// TODO(milas): add an env var to enable logging from the
+			// OTel components for debugging purposes
+			_ = tracingShutdown(ctx)
+		}
+		return cmdErr
+	}
+}
+
+// commandName returns the path components for a given command.
+//
+// The root Compose command and anything before (i.e. "docker")
+// are not included.
+//
+// For example:
+//   - docker compose alpha watch -> [alpha, watch]
+//   - docker-compose up -> [up]
+func commandName(cmd *cobra.Command) []string {
+	var name []string
+	for c := cmd; c != nil; c = c.Parent() {
+		if c.Name() == commands.PluginName {
+			break
+		}
+		name = append(name, c.Name())
+	}
+	sort.Sort(sort.Reverse(sort.StringSlice(name)))
+	return name
+}

cmd/compatibility/convert.go

@@ -62,10 +62,6 @@ func Convert(args []string) []string {
 			continue
 		}
 		if len(arg) > 0 && arg[0] != '-' {
-			// not a top-level flag anymore, keep the rest of the command unmodified
-			if arg == compose.PluginName {
-				i++
-			}
 			command = append(command, args[i:]...)
 			break
 		}

cmd/compatibility/convert_test.go

@@ -83,6 +83,11 @@ func Test_convert(t *testing.T) {
 			args: []string{"--project-directory", "", "ps"},
 			want: []string{"compose", "--project-directory", "", "ps"},
 		},
+		{
+			name: "compose as project name",
+			args: []string{"--project-name", "compose", "down", "--remove-orphans"},
+			want: []string{"compose", "--project-name", "compose", "down", "--remove-orphans"},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

cmd/compose/alpha.go

@@ -15,8 +15,6 @@
 package compose
 
 import (
-	"context"
-
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/spf13/cobra"
 )
@@ -33,25 +31,8 @@ func alphaCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	}
 	cmd.AddCommand(
 		watchCommand(p, backend),
-		dryRunRedirectCommand(p),
+		vizCommand(p, backend),
+		publishCommand(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
-}

cmd/compose/build.go

@@ -26,8 +26,8 @@ import (
 	"github.com/compose-spec/compose-go/loader"
 	"github.com/compose-spec/compose-go/types"
 	buildx "github.com/docker/buildx/util/progress"
-	"github.com/docker/compose/v2/pkg/progress"
-	"github.com/docker/compose/v2/pkg/utils"
+	cliopts "github.com/docker/cli/opts"
+	ui "github.com/docker/compose/v2/pkg/progress"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -36,14 +36,14 @@ import (
 type buildOptions struct {
 	*ProjectOptions
 	composeOptions
-	quiet    bool
-	pull     bool
-	push     bool
-	progress string
-	args     []string
-	noCache  bool
-	memory   string
-	ssh      string
+	quiet   bool
+	pull    bool
+	push    bool
+	args    []string
+	noCache bool
+	memory  cliopts.MemBytes
+	ssh     string
+	builder string
 }
 
 func (opts buildOptions) toAPIBuildOptions(services []string) (api.BuildOptions, error) {
@@ -55,27 +55,25 @@ func (opts buildOptions) toAPIBuildOptions(services []string) (api.BuildOptions,
 			return api.BuildOptions{}, err
 		}
 	}
+	builderName := opts.builder
+	if builderName == "" {
+		builderName = os.Getenv("BUILDX_BUILDER")
+	}
 
 	return api.BuildOptions{
 		Pull:     opts.pull,
 		Push:     opts.push,
-		Progress: opts.progress,
+		Progress: ui.Mode,
 		Args:     types.NewMappingWithEquals(opts.args),
 		NoCache:  opts.noCache,
 		Quiet:    opts.quiet,
 		Services: services,
 		SSHs:     SSHKeys,
+		Builder:  builderName,
 	}, nil
 }
 
-var printerModes = []string{
-	buildx.PrinterModeAuto,
-	buildx.PrinterModeTty,
-	buildx.PrinterModePlain,
-	buildx.PrinterModeQuiet,
-}
-
-func buildCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func buildCommand(p *ProjectOptions, progress *string, backend api.Service) *cobra.Command {
 	opts := buildOptions{
 		ProjectOptions: p,
 	}
@@ -83,28 +81,22 @@ func buildCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *
 		Use:   "build [OPTIONS] [SERVICE...]",
 		Short: "Build or rebuild services",
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {
-			if opts.memory != "" {
-				fmt.Fprintln(streams.Err(), "WARNING --memory is ignored as not supported in buildkit.")
-			}
 			if opts.quiet {
-				opts.progress = buildx.PrinterModeQuiet
+				ui.Mode = ui.ModeQuiet
 				devnull, err := os.Open(os.DevNull)
 				if err != nil {
 					return err
 				}
 				os.Stdout = devnull
 			}
-			if !utils.StringContains(printerModes, opts.progress) {
-				return fmt.Errorf("unsupported --progress value %q", opts.progress)
-			}
 			return nil
 		}),
 		RunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
 			if cmd.Flags().Changed("ssh") && opts.ssh == "" {
 				opts.ssh = "default"
 			}
-			if progress.Mode == progress.ModePlain && !cmd.Flags().Changed("progress") {
-				opts.progress = buildx.PrinterModePlain
+			if cmd.Flags().Changed("progress") && opts.ssh == "" {
+				fmt.Fprint(os.Stderr, "--progress is a global compose flag, better use `docker compose --progress xx build ...")
 			}
 			return runBuild(ctx, backend, opts, args)
 		}),
@@ -113,9 +105,9 @@ func buildCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *
 	cmd.Flags().BoolVar(&opts.push, "push", false, "Push service images.")
 	cmd.Flags().BoolVarP(&opts.quiet, "quiet", "q", false, "Don't print anything to STDOUT")
 	cmd.Flags().BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the image.")
-	cmd.Flags().StringVar(&opts.progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of progress output (%s)`, strings.Join(printerModes, ", ")))
 	cmd.Flags().StringArrayVar(&opts.args, "build-arg", []string{}, "Set build-time variables for services.")
 	cmd.Flags().StringVar(&opts.ssh, "ssh", "", "Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent)")
+	cmd.Flags().StringVar(&opts.builder, "builder", "", "Set builder to use.")
 	cmd.Flags().Bool("parallel", true, "Build images in parallel. DEPRECATED")
 	cmd.Flags().MarkHidden("parallel") //nolint:errcheck
 	cmd.Flags().Bool("compress", true, "Compress the build context using gzip. DEPRECATED")
@@ -125,8 +117,9 @@ func buildCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *
 	cmd.Flags().BoolVar(&opts.noCache, "no-cache", false, "Do not use cache when building the image")
 	cmd.Flags().Bool("no-rm", false, "Do not remove intermediate containers after a successful build. DEPRECATED")
 	cmd.Flags().MarkHidden("no-rm") //nolint:errcheck
-	cmd.Flags().StringVarP(&opts.memory, "memory", "m", "", "Set memory limit for the build container. Not supported on buildkit yet.")
-	cmd.Flags().MarkHidden("memory") //nolint:errcheck
+	cmd.Flags().VarP(&opts.memory, "memory", "m", "Set memory limit for the build container. Not supported by BuildKit.")
+	cmd.Flags().StringVar(progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of ui output (%s)`, strings.Join(printerModes, ", ")))
+	cmd.Flags().MarkHidden("progress") //nolint:errcheck
 
 	return cmd
 }
@@ -141,5 +134,7 @@ func runBuild(ctx context.Context, backend api.Service, opts buildOptions, servi
 	if err != nil {
 		return err
 	}
+
+	apiBuildOptions.Memory = int64(opts.memory)
 	return backend.Build(ctx, project, apiBuildOptions)
 }

cmd/compose/completion.go

@@ -17,6 +17,7 @@
 package compose
 
 import (
+	"sort"
 	"strings"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -65,3 +66,23 @@ func completeProjectNames(backend api.Service) func(cmd *cobra.Command, args []s
 		return values, cobra.ShellCompDirectiveNoFileComp
 	}
 }
+
+func completeProfileNames(p *ProjectOptions) validArgsFn {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		project, err := p.ToProject(nil)
+		if err != nil {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+
+		allProfileNames := project.AllServices().GetProfiles()
+		sort.Strings(allProfileNames)
+
+		var values []string
+		for _, profileName := range allProfileNames {
+			if strings.HasPrefix(profileName, toComplete) {
+				values = append(values, profileName)
+			}
+		}
+		return values, cobra.ShellCompDirectiveNoFileComp
+	}
+}

cmd/compose/compose.go

@@ -26,6 +26,8 @@ import (
 	"strings"
 	"syscall"
 
+	"github.com/compose-spec/compose-go/dotenv"
+	buildx "github.com/docker/buildx/util/progress"
 	"github.com/docker/cli/cli/command"
 
 	"github.com/compose-spec/compose-go/cli"
@@ -43,10 +45,23 @@ import (
 	"github.com/docker/compose/v2/cmd/formatter"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/docker/compose/v2/pkg/compose"
-	"github.com/docker/compose/v2/pkg/progress"
+	ui "github.com/docker/compose/v2/pkg/progress"
 	"github.com/docker/compose/v2/pkg/utils"
 )
 
+const (
+	// ComposeParallelLimit set the limit running concurrent operation on docker engine
+	ComposeParallelLimit = "COMPOSE_PARALLEL_LIMIT"
+	// ComposeProjectName define the project name to be used, instead of guessing from parent directory
+	ComposeProjectName = "COMPOSE_PROJECT_NAME"
+	// ComposeCompatibility try to mimic compose v1 as much as possible
+	ComposeCompatibility = "COMPOSE_COMPATIBILITY"
+	// ComposeRemoveOrphans remove “orphaned" containers, i.e. containers tagged for current project but not declared as service
+	ComposeRemoveOrphans = "COMPOSE_REMOVE_ORPHANS"
+	// ComposeIgnoreOrphans ignore "orphaned" containers
+	ComposeIgnoreOrphans = "COMPOSE_IGNORE_ORPHANS"
+)
+
 // Command defines a compose CLI command as a func with args
 type Command func(context.Context, []string) error
 
@@ -119,7 +134,7 @@ func (o *ProjectOptions) WithProject(fn ProjectFunc) func(cmd *cobra.Command, ar
 // WithServices creates a cobra run command from a ProjectFunc based on configured project options and selected services
 func (o *ProjectOptions) WithServices(fn ProjectServicesFunc) func(cmd *cobra.Command, args []string) error {
 	return Adapt(func(ctx context.Context, args []string) error {
-		project, err := o.ToProject(args, cli.WithResolvedPaths(true))
+		project, err := o.ToProject(args, cli.WithResolvedPaths(true), cli.WithDiscardEnvFile)
 		if err != nil {
 			return err
 		}
@@ -143,9 +158,9 @@ func (o *ProjectOptions) projectOrName(services ...string) (*types.Project, stri
 	name := o.ProjectName
 	var project *types.Project
 	if len(o.ConfigPaths) > 0 || o.ProjectName == "" {
-		p, err := o.ToProject(services)
+		p, err := o.ToProject(services, cli.WithDiscardEnvFile)
 		if err != nil {
-			envProjectName := os.Getenv("COMPOSE_PROJECT_NAME")
+			envProjectName := os.Getenv(ComposeProjectName)
 			if envProjectName != "" {
 				return nil, envProjectName, nil
 			}
@@ -162,7 +177,7 @@ func (o *ProjectOptions) toProjectName() (string, error) {
 		return o.ProjectName, nil
 	}
 
-	envProjectName := os.Getenv("COMPOSE_PROJECT_NAME")
+	envProjectName := os.Getenv(ComposeProjectName)
 	if envProjectName != "" {
 		return envProjectName, nil
 	}
@@ -180,7 +195,7 @@ func (o *ProjectOptions) ToProject(services []string, po ...cli.ProjectOptionsFn
 		return nil, compose.WrapComposeError(err)
 	}
 
-	if o.Compatibility || utils.StringToBool(options.Environment["COMPOSE_COMPATIBILITY"]) {
+	if o.Compatibility || utils.StringToBool(options.Environment[ComposeCompatibility]) {
 		api.Separator = "_"
 	}
 
@@ -260,9 +275,11 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 		version  bool
 		parallel int
 		dryRun   bool
+		progress string
 	)
 	c := &cobra.Command{
 		Short:            "Docker Compose",
+		Long:             "Define and run multi-container applications with Docker.",
 		Use:              PluginName,
 		TraverseChildren: true,
 		// By default (no Run/RunE in parent c) for typos in subcommands, cobra displays the help of parent c but exit(0) !
@@ -305,17 +322,43 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 				logrus.SetLevel(logrus.TraceLevel)
 			}
 
-			if noColor, ok := os.LookupEnv("NO_COLOR"); ok && noColor != "" && !cmd.Flags().Changed("ansi") {
-				ansi = "never"
+			if v, ok := os.LookupEnv("COMPOSE_ANSI"); ok && !cmd.Flags().Changed("ansi") {
+				ansi = v
 			}
 
 			formatter.SetANSIMode(streams, ansi)
+
+			if noColor, ok := os.LookupEnv("NO_COLOR"); ok && noColor != "" {
+				ui.NoColor()
+				formatter.SetANSIMode(streams, formatter.Never)
+			}
+
 			switch ansi {
 			case "never":
-				progress.Mode = progress.ModePlain
-			case "tty":
-				progress.Mode = progress.ModeTTY
+				ui.Mode = ui.ModePlain
+			case "always":
+				ui.Mode = ui.ModeTTY
 			}
+
+			switch progress {
+			case ui.ModeAuto:
+				ui.Mode = ui.ModeAuto
+			case ui.ModeTTY:
+				if ansi == "never" {
+					return fmt.Errorf("can't use --progress tty while ANSI support is disabled")
+				}
+				ui.Mode = ui.ModeTTY
+			case ui.ModePlain:
+				if ansi == "always" {
+					return fmt.Errorf("can't use --progress plain while ANSI support is forced")
+				}
+				ui.Mode = ui.ModePlain
+			case ui.ModeQuiet, "none":
+				ui.Mode = ui.ModeQuiet
+			default:
+				return fmt.Errorf("unsupported --progress value %q", progress)
+			}
+
 			if opts.WorkDir != "" {
 				if opts.ProjectDir != "" {
 					return errors.New(`cannot specify DEPRECATED "--workdir" and "--project-directory". Please use only "--project-directory" instead`)
@@ -332,10 +375,22 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 					opts.EnvFiles[i] = file
 				}
 			}
-			if v, ok := os.LookupEnv("COMPOSE_PARALLEL_LIMIT"); ok && !cmd.Flags().Changed("parallel") {
+
+			composeCmd := cmd
+			for {
+				if composeCmd.Name() == PluginName {
+					break
+				}
+				if !composeCmd.HasParent() {
+					return fmt.Errorf("error parsing command line, expected %q", PluginName)
+				}
+				composeCmd = composeCmd.Parent()
+			}
+
+			if v, ok := os.LookupEnv(ComposeParallelLimit); ok && !composeCmd.Flags().Changed("parallel") {
 				i, err := strconv.Atoi(v)
 				if err != nil {
-					return fmt.Errorf("COMPOSE_PARALLEL_LIMIT must be an integer (found: %q)", v)
+					return fmt.Errorf("%s must be an integer (found: %q)", ComposeParallelLimit, v)
 				}
 				parallel = i
 			}
@@ -360,7 +415,7 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 		psCommand(&opts, streams, backend),
 		listCommand(streams, backend),
 		logsCommand(&opts, streams, backend),
-		convertCommand(&opts, streams, backend),
+		configCommand(&opts, streams, backend),
 		killCommand(&opts, backend),
 		runCommand(&opts, streams, backend),
 		removeCommand(&opts, backend),
@@ -372,11 +427,12 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 		portCommand(&opts, streams, backend),
 		imagesCommand(&opts, streams, backend),
 		versionCommand(streams),
-		buildCommand(&opts, streams, backend),
+		buildCommand(&opts, &progress, backend),
 		pushCommand(&opts, backend),
 		pullCommand(&opts, backend),
 		createCommand(&opts, backend),
 		copyCommand(&opts, backend),
+		waitCommand(&opts, backend),
 		alphaCommand(&opts, backend),
 	)
 
@@ -386,23 +442,34 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 		"project-name",
 		completeProjectNames(backend),
 	)
+	c.RegisterFlagCompletionFunc( //nolint:errcheck
+		"project-directory",
+		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+			return []string{}, cobra.ShellCompDirectiveFilterDirs
+		},
+	)
 	c.RegisterFlagCompletionFunc( //nolint:errcheck
 		"file",
 		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			return []string{"yaml", "yml"}, cobra.ShellCompDirectiveFilterFileExt
 		},
 	)
+	c.RegisterFlagCompletionFunc( //nolint:errcheck
+		"profile",
+		completeProfileNames(&opts),
+	)
+
+	c.Flags().StringVar(&progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of progress output (%s)`, strings.Join(printerModes, ", ")))
 
 	c.Flags().StringVar(&ansi, "ansi", "auto", `Control when to print ANSI control characters ("never"|"always"|"auto")`)
 	c.Flags().IntVar(&parallel, "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
 }
 
@@ -416,7 +483,7 @@ func setEnvWithDotEnv(prjOpts *ProjectOptions) error {
 		return err
 	}
 
-	envFromFile, err := cli.GetEnvFromFile(composegoutils.GetAsEqualsMap(os.Environ()), workingDir, options.EnvFiles)
+	envFromFile, err := dotenv.GetEnvFromFile(composegoutils.GetAsEqualsMap(os.Environ()), workingDir, options.EnvFiles)
 	if err != nil {
 		return err
 	}
@@ -429,3 +496,10 @@ func setEnvWithDotEnv(prjOpts *ProjectOptions) error {
 	}
 	return nil
 }
+
+var printerModes = []string{
+	ui.ModeAuto,
+	ui.ModeTTY,
+	ui.ModePlain,
+	ui.ModeQuiet,
+}

cmd/compose/config.go

@@ -40,6 +40,7 @@ type configOptions struct {
 	resolveImageDigests bool
 	noInterpolate       bool
 	noNormalize         bool
+	noResolvePath       bool
 	services            bool
 	volumes             bool
 	profiles            bool
@@ -51,14 +52,14 @@ type configOptions struct {
 func (o *configOptions) ToProject(services []string) (*types.Project, error) {
 	return o.ProjectOptions.ToProject(services,
 		cli.WithInterpolation(!o.noInterpolate),
-		cli.WithResolvedPaths(true),
+		cli.WithResolvedPaths(!o.noResolvePath),
 		cli.WithNormalization(!o.noNormalize),
 		cli.WithConsistency(!o.noConsistency),
 		cli.WithProfiles(o.Profiles),
 		cli.WithDiscardEnvFile)
 }
 
-func convertCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func configCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
 	opts := configOptions{
 		ProjectOptions: p,
 	}
@@ -106,6 +107,7 @@ func convertCommand(p *ProjectOptions, streams api.Streams, backend api.Service)
 	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Only validate the configuration, don't print anything.")
 	flags.BoolVar(&opts.noInterpolate, "no-interpolate", false, "Don't interpolate environment variables.")
 	flags.BoolVar(&opts.noNormalize, "no-normalize", false, "Don't normalize compose model.")
+	flags.BoolVar(&opts.noResolvePath, "no-path-resolution", false, "Don't resolve file paths.")
 	flags.BoolVar(&opts.noConsistency, "no-consistency", false, "Don't check model consistency - warning: may produce invalid Compose output")
 
 	flags.BoolVar(&opts.services, "services", false, "Print the service names, one per line.")
@@ -231,11 +233,7 @@ func runConfigImages(streams api.Streams, opts configOptions, services []string)
 		return err
 	}
 	for _, s := range project.Services {
-		if s.Image != "" {
-			fmt.Fprintln(streams.Out(), s.Image)
-		} else {
-			fmt.Fprintf(streams.Out(), "%s%s%s\n", project.Name, api.Separator, s.Name)
-		}
+		fmt.Fprintln(streams.Out(), api.GetImageNameOrDefault(s, project.Name))
 	}
 	return nil
 }

cmd/compose/cp.go

@@ -64,10 +64,10 @@ func copyCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	}
 
 	flags := copyCmd.Flags()
-	flags.IntVar(&opts.index, "index", 0, "Index of the container if there are multiple instances of a service .")
-	flags.BoolVar(&opts.all, "all", false, "Copy to all the containers of the service.")
+	flags.IntVar(&opts.index, "index", 0, "index of the container if service has multiple replicas")
+	flags.BoolVar(&opts.all, "all", false, "copy to all the containers of the service.")
 	flags.MarkHidden("all")                                                                                                      //nolint:errcheck
-	flags.MarkDeprecated("all", "By default all the containers of the service will get the source file/directory to be copied.") //nolint:errcheck
+	flags.MarkDeprecated("all", "by default all the containers of the service will get the source file/directory to be copied.") //nolint:errcheck
 	flags.BoolVarP(&opts.followLink, "follow-link", "L", false, "Always follow symbol link in SRC_PATH")
 	flags.BoolVarP(&opts.copyUIDGID, "archive", "a", false, "Archive mode (copy all uid/gid information)")
 

cmd/compose/down.go

@@ -44,7 +44,7 @@ func downCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		ProjectOptions: p,
 	}
 	downCmd := &cobra.Command{
-		Use:   "down [OPTIONS]",
+		Use:   "down [OPTIONS] [SERVICES]",
 		Short: "Stop and remove containers, networks",
 		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
 			opts.timeChanged = cmd.Flags().Changed("timeout")
@@ -56,16 +56,15 @@ func downCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 			return nil
 		}),
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runDown(ctx, backend, opts)
+			return runDown(ctx, backend, opts, args)
 		}),
-		Args:              cobra.NoArgs,
 		ValidArgsFunction: noCompletion(),
 	}
 	flags := downCmd.Flags()
-	removeOrphans := utils.StringToBool(os.Getenv("COMPOSE_REMOVE_ORPHANS"))
+	removeOrphans := utils.StringToBool(os.Getenv(ComposeRemoveOrphans))
 	flags.BoolVar(&opts.removeOrphans, "remove-orphans", removeOrphans, "Remove containers for services not defined in the Compose file.")
-	flags.IntVarP(&opts.timeout, "timeout", "t", 10, "Specify a shutdown timeout in seconds")
-	flags.BoolVarP(&opts.volumes, "volumes", "v", false, "Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers.")
+	flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Specify a shutdown timeout in seconds")
+	flags.BoolVarP(&opts.volumes, "volumes", "v", false, `Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers.`)
 	flags.StringVar(&opts.images, "rmi", "", `Remove images used by services. "local" remove only images that don't have a custom tag ("local"|"all")`)
 	flags.SetNormalizeFunc(func(f *pflag.FlagSet, name string) pflag.NormalizedName {
 		if name == "volume" {
@@ -77,7 +76,7 @@ func downCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	return downCmd
 }
 
-func runDown(ctx context.Context, backend api.Service, opts downOptions) error {
+func runDown(ctx context.Context, backend api.Service, opts downOptions, services []string) error {
 	project, name, err := opts.projectOrName()
 	if err != nil {
 		return err
@@ -94,5 +93,6 @@ func runDown(ctx context.Context, backend api.Service, opts downOptions) error {
 		Timeout:       timeout,
 		Images:        opts.images,
 		Volumes:       opts.volumes,
+		Services:      services,
 	})
 }

cmd/compose/exec.go

@@ -65,7 +65,7 @@ func execCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 
 	runCmd.Flags().BoolVarP(&opts.detach, "detach", "d", false, "Detached mode: Run command in the background.")
 	runCmd.Flags().StringArrayVarP(&opts.environment, "env", "e", []string{}, "Set environment variables")
-	runCmd.Flags().IntVar(&opts.index, "index", 1, "index of the container if there are multiple instances of a service [default: 1].")
+	runCmd.Flags().IntVar(&opts.index, "index", 0, "index of the container if service has multiple replicas")
 	runCmd.Flags().BoolVarP(&opts.privileged, "privileged", "", false, "Give extended privileges to the process.")
 	runCmd.Flags().StringVarP(&opts.user, "user", "u", "", "Run the command as this user.")
 	runCmd.Flags().BoolVarP(&opts.noTty, "no-TTY", "T", !streams.Out().IsTerminal(), "Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.")

cmd/compose/kill.go

@@ -46,7 +46,7 @@ func killCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	}
 
 	flags := cmd.Flags()
-	removeOrphans := utils.StringToBool(os.Getenv("COMPOSE_REMOVE_ORPHANS"))
+	removeOrphans := utils.StringToBool(os.Getenv(ComposeRemoveOrphans))
 	flags.BoolVar(&opts.removeOrphans, "remove-orphans", removeOrphans, "Remove containers for services not defined in the Compose file.")
 	flags.StringVarP(&opts.signal, "signal", "s", "SIGKILL", "SIGNAL to send to the container.")
 

cmd/compose/port.go

@@ -57,7 +57,7 @@ func portCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 		ValidArgsFunction: completeServiceNames(p),
 	}
 	cmd.Flags().StringVar(&opts.protocol, "protocol", "tcp", "tcp or udp")
-	cmd.Flags().IntVar(&opts.index, "index", 1, "index of the container if service has multiple replicas")
+	cmd.Flags().IntVar(&opts.index, "index", 0, "index of the container if service has multiple replicas")
 	return cmd
 }
 

cmd/compose/publish.go

@@ -0,0 +1,49 @@
+/*
+   Copyright 2020 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"context"
+
+	"github.com/spf13/cobra"
+
+	"github.com/docker/compose/v2/pkg/api"
+)
+
+func publishCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+	opts := pushOptions{
+		ProjectOptions: p,
+	}
+	publishCmd := &cobra.Command{
+		Use:   "publish [OPTIONS] [REPOSITORY]",
+		Short: "Publish compose application",
+		RunE: Adapt(func(ctx context.Context, args []string) error {
+			return runPublish(ctx, backend, opts, args[0])
+		}),
+		Args: cobra.ExactArgs(1),
+	}
+	return publishCmd
+}
+
+func runPublish(ctx context.Context, backend api.Service, opts pushOptions, repository string) error {
+	project, err := opts.ToProject(nil)
+	if err != nil {
+		return err
+	}
+
+	return backend.Publish(ctx, project, repository)
+}

cmd/compose/remove.go

@@ -64,16 +64,6 @@ func runRemove(ctx context.Context, backend api.Service, opts removeOptions, ser
 		return err
 	}
 
-	if opts.stop {
-		err := backend.Stop(ctx, name, api.StopOptions{
-			Services: services,
-			Project:  project,
-		})
-		if err != nil {
-			return err
-		}
-	}
-
 	return backend.Remove(ctx, name, api.RemoveOptions{
 		Services: services,
 		Force:    opts.force,

cmd/compose/restart.go

@@ -28,8 +28,9 @@ import (
 
 type restartOptions struct {
 	*ProjectOptions
-	timeout int
-	noDeps  bool
+	timeChanged bool
+	timeout     int
+	noDeps      bool
 }
 
 func restartCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
@@ -39,13 +40,16 @@ func restartCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	restartCmd := &cobra.Command{
 		Use:   "restart [OPTIONS] [SERVICE...]",
 		Short: "Restart service containers",
+		PreRun: func(cmd *cobra.Command, args []string) {
+			opts.timeChanged = cmd.Flags().Changed("timeout")
+		},
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			return runRestart(ctx, backend, opts, args)
 		}),
 		ValidArgsFunction: completeServiceNames(p),
 	}
 	flags := restartCmd.Flags()
-	flags.IntVarP(&opts.timeout, "timeout", "t", 10, "Specify a shutdown timeout in seconds")
+	flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Specify a shutdown timeout in seconds")
 	flags.BoolVar(&opts.noDeps, "no-deps", false, "Don't restart dependent services.")
 
 	return restartCmd
@@ -57,6 +61,12 @@ func runRestart(ctx context.Context, backend api.Service, opts restartOptions, s
 		return err
 	}
 
+	var timeout *time.Duration
+	if opts.timeChanged {
+		timeoutValue := time.Duration(opts.timeout) * time.Second
+		timeout = &timeoutValue
+	}
+
 	if opts.noDeps {
 		err := project.ForServices(services, types.IgnoreDependencies)
 		if err != nil {
@@ -64,9 +74,8 @@ func runRestart(ctx context.Context, backend api.Service, opts restartOptions, s
 		}
 	}
 
-	timeout := time.Duration(opts.timeout) * time.Second
 	return backend.Restart(ctx, name, api.RestartOptions{
-		Timeout:  &timeout,
+		Timeout:  timeout,
 		Services: services,
 		Project:  project,
 	})

cmd/compose/run.go

@@ -24,6 +24,7 @@ import (
 	cgo "github.com/compose-spec/compose-go/cli"
 	"github.com/compose-spec/compose-go/loader"
 	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/cli/opts"
 	"github.com/mattn/go-shellwords"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -48,6 +49,8 @@ type runOptions struct {
 	workdir       string
 	entrypoint    string
 	entrypointCmd []string
+	capAdd        opts.ListOpts
+	capDrop       opts.ListOpts
 	labels        []string
 	volumes       []string
 	publish       []string
@@ -59,20 +62,27 @@ type runOptions struct {
 	quietPull     bool
 }
 
-func (opts runOptions) apply(project *types.Project) error {
-	target, err := project.GetService(opts.Service)
+func (options runOptions) apply(project *types.Project) error {
+	if options.noDeps {
+		err := project.ForServices([]string{options.Service}, types.IgnoreDependencies)
+		if err != nil {
+			return err
+		}
+	}
+
+	target, err := project.GetService(options.Service)
 	if err != nil {
 		return err
 	}
 
-	target.Tty = !opts.noTty
-	target.StdinOpen = opts.interactive
-	if !opts.servicePorts {
+	target.Tty = !options.noTty
+	target.StdinOpen = options.interactive
+	if !options.servicePorts {
 		target.Ports = []types.ServicePortConfig{}
 	}
-	if len(opts.publish) > 0 {
+	if len(options.publish) > 0 {
 		target.Ports = []types.ServicePortConfig{}
-		for _, p := range opts.publish {
+		for _, p := range options.publish {
 			config, err := types.ParsePortConfig(p)
 			if err != nil {
 				return err
@@ -80,8 +90,8 @@ func (opts runOptions) apply(project *types.Project) error {
 			target.Ports = append(target.Ports, config...)
 		}
 	}
-	if len(opts.volumes) > 0 {
-		for _, v := range opts.volumes {
+	if len(options.volumes) > 0 {
+		for _, v := range options.volumes {
 			volume, err := loader.ParseVolume(v)
 			if err != nil {
 				return err
@@ -90,15 +100,8 @@ func (opts runOptions) apply(project *types.Project) error {
 		}
 	}
 
-	if opts.noDeps {
-		err := project.ForServices([]string{opts.Service}, types.IgnoreDependencies)
-		if err != nil {
-			return err
-		}
-	}
-
 	for i, s := range project.Services {
-		if s.Name == opts.Service {
+		if s.Name == options.Service {
 			project.Services[i] = target
 			break
 		}
@@ -107,10 +110,12 @@ func (opts runOptions) apply(project *types.Project) error {
 }
 
 func runCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
-	opts := runOptions{
+	options := runOptions{
 		composeOptions: &composeOptions{
 			ProjectOptions: p,
 		},
+		capAdd:  opts.NewListOpts(nil),
+		capDrop: opts.NewListOpts(nil),
 	}
 	createOpts := createOptions{}
 	cmd := &cobra.Command{
@@ -118,60 +123,63 @@ func runCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *co
 		Short: "Run a one-off command on a service.",
 		Args:  cobra.MinimumNArgs(1),
 		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
-			opts.Service = args[0]
+			options.Service = args[0]
 			if len(args) > 1 {
-				opts.Command = args[1:]
+				options.Command = args[1:]
 			}
-			if len(opts.publish) > 0 && opts.servicePorts {
+			if len(options.publish) > 0 && options.servicePorts {
 				return fmt.Errorf("--service-ports and --publish are incompatible")
 			}
 			if cmd.Flags().Changed("entrypoint") {
-				command, err := shellwords.Parse(opts.entrypoint)
+				command, err := shellwords.Parse(options.entrypoint)
 				if err != nil {
 					return err
 				}
-				opts.entrypointCmd = command
+				options.entrypointCmd = command
 			}
 			if cmd.Flags().Changed("tty") {
 				if cmd.Flags().Changed("no-TTY") {
 					return fmt.Errorf("--tty and --no-TTY can't be used together")
 				} else {
-					opts.noTty = !opts.tty
+					options.noTty = !options.tty
 				}
 			}
 			return nil
 		}),
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			project, err := p.ToProject([]string{opts.Service}, cgo.WithResolvedPaths(true))
+			project, err := p.ToProject([]string{options.Service}, cgo.WithResolvedPaths(true), cgo.WithDiscardEnvFile)
 			if err != nil {
 				return err
 			}
-			opts.ignoreOrphans = utils.StringToBool(project.Environment["COMPOSE_IGNORE_ORPHANS"])
-			return runRun(ctx, backend, project, opts, createOpts, streams)
+
+			options.ignoreOrphans = utils.StringToBool(project.Environment[ComposeIgnoreOrphans])
+			return runRun(ctx, backend, project, options, createOpts, streams)
 		}),
 		ValidArgsFunction: completeServiceNames(p),
 	}
 	flags := cmd.Flags()
-	flags.BoolVarP(&opts.Detach, "detach", "d", false, "Run container in background and print container ID")
-	flags.StringArrayVarP(&opts.environment, "env", "e", []string{}, "Set environment variables")
-	flags.StringArrayVarP(&opts.labels, "label", "l", []string{}, "Add or override a label")
-	flags.BoolVar(&opts.Remove, "rm", false, "Automatically remove the container when it exits")
-	flags.BoolVarP(&opts.noTty, "no-TTY", "T", !streams.Out().IsTerminal(), "Disable pseudo-TTY allocation (default: auto-detected).")
-	flags.StringVar(&opts.name, "name", "", "Assign a name to the container")
-	flags.StringVarP(&opts.user, "user", "u", "", "Run as specified username or uid")
-	flags.StringVarP(&opts.workdir, "workdir", "w", "", "Working directory inside the container")
-	flags.StringVar(&opts.entrypoint, "entrypoint", "", "Override the entrypoint of the image")
-	flags.BoolVar(&opts.noDeps, "no-deps", false, "Don't start linked services.")
-	flags.StringArrayVarP(&opts.volumes, "volume", "v", []string{}, "Bind mount a volume.")
-	flags.StringArrayVarP(&opts.publish, "publish", "p", []string{}, "Publish a container's port(s) to the host.")
-	flags.BoolVar(&opts.useAliases, "use-aliases", false, "Use the service's network useAliases in the network(s) the container connects to.")
-	flags.BoolVar(&opts.servicePorts, "service-ports", false, "Run command with the service's ports enabled and mapped to the host.")
-	flags.BoolVar(&opts.quietPull, "quiet-pull", false, "Pull without printing progress information.")
+	flags.BoolVarP(&options.Detach, "detach", "d", false, "Run container in background and print container ID")
+	flags.StringArrayVarP(&options.environment, "env", "e", []string{}, "Set environment variables")
+	flags.StringArrayVarP(&options.labels, "label", "l", []string{}, "Add or override a label")
+	flags.BoolVar(&options.Remove, "rm", false, "Automatically remove the container when it exits")
+	flags.BoolVarP(&options.noTty, "no-TTY", "T", !streams.Out().IsTerminal(), "Disable pseudo-TTY allocation (default: auto-detected).")
+	flags.StringVar(&options.name, "name", "", "Assign a name to the container")
+	flags.StringVarP(&options.user, "user", "u", "", "Run as specified username or uid")
+	flags.StringVarP(&options.workdir, "workdir", "w", "", "Working directory inside the container")
+	flags.StringVar(&options.entrypoint, "entrypoint", "", "Override the entrypoint of the image")
+	flags.Var(&options.capAdd, "cap-add", "Add Linux capabilities")
+	flags.Var(&options.capDrop, "cap-drop", "Drop Linux capabilities")
+	flags.BoolVar(&options.noDeps, "no-deps", false, "Don't start linked services.")
+	flags.StringArrayVarP(&options.volumes, "volume", "v", []string{}, "Bind mount a volume.")
+	flags.StringArrayVarP(&options.publish, "publish", "p", []string{}, "Publish a container's port(s) to the host.")
+	flags.BoolVar(&options.useAliases, "use-aliases", false, "Use the service's network useAliases in the network(s) the container connects to.")
+	flags.BoolVar(&options.servicePorts, "service-ports", false, "Run command with the service's ports enabled and mapped to the host.")
+	flags.BoolVar(&options.quietPull, "quiet-pull", false, "Pull without printing progress information.")
 	flags.BoolVar(&createOpts.Build, "build", false, "Build image before starting container.")
 	flags.BoolVar(&createOpts.removeOrphans, "remove-orphans", false, "Remove containers for services not defined in the Compose file.")
 
-	cmd.Flags().BoolVarP(&opts.interactive, "interactive", "i", true, "Keep STDIN open even if not attached.")
-	cmd.Flags().BoolVarP(&opts.tty, "tty", "t", true, "Allocate a pseudo-TTY.")
+	cmd.Flags().BoolVarP(&options.interactive, "interactive", "i", true, "Keep STDIN open even if not attached.")
+	cmd.Flags().BoolVarP(&options.tty, "tty", "t", true, "Allocate a pseudo-TTY.")
 	cmd.Flags().MarkHidden("tty") //nolint:errcheck
 
 	flags.SetNormalizeFunc(normalizeRunFlags)
@@ -189,8 +197,8 @@ func normalizeRunFlags(f *pflag.FlagSet, name string) pflag.NormalizedName {
 	return pflag.NormalizedName(name)
 }
 
-func runRun(ctx context.Context, backend api.Service, project *types.Project, opts runOptions, createOpts createOptions, streams api.Streams) error {
-	err := opts.apply(project)
+func runRun(ctx context.Context, backend api.Service, project *types.Project, options runOptions, createOpts createOptions, streams api.Streams) error {
+	err := options.apply(project)
 	if err != nil {
 		return err
 	}
@@ -201,14 +209,14 @@ func runRun(ctx context.Context, backend api.Service, project *types.Project, op
 	}
 
 	err = progress.Run(ctx, func(ctx context.Context) error {
-		return startDependencies(ctx, backend, *project, opts.Service, opts.ignoreOrphans)
+		return startDependencies(ctx, backend, *project, options.Service, options.ignoreOrphans)
 	}, streams.Err())
 	if err != nil {
 		return err
 	}
 
 	labels := types.Labels{}
-	for _, s := range opts.labels {
+	for _, s := range options.labels {
 		parts := strings.SplitN(s, "=", 2)
 		if len(parts) != 2 {
 			return fmt.Errorf("label must be set as KEY=VALUE")
@@ -218,27 +226,29 @@ func runRun(ctx context.Context, backend api.Service, project *types.Project, op
 
 	// start container and attach to container streams
 	runOpts := api.RunOptions{
-		Name:              opts.name,
-		Service:           opts.Service,
-		Command:           opts.Command,
-		Detach:            opts.Detach,
-		AutoRemove:        opts.Remove,
-		Tty:               !opts.noTty,
-		Interactive:       opts.interactive,
-		WorkingDir:        opts.workdir,
-		User:              opts.user,
-		Environment:       opts.environment,
-		Entrypoint:        opts.entrypointCmd,
+		Name:              options.name,
+		Service:           options.Service,
+		Command:           options.Command,
+		Detach:            options.Detach,
+		AutoRemove:        options.Remove,
+		Tty:               !options.noTty,
+		Interactive:       options.interactive,
+		WorkingDir:        options.workdir,
+		User:              options.user,
+		CapAdd:            options.capAdd.GetAll(),
+		CapDrop:           options.capDrop.GetAll(),
+		Environment:       options.environment,
+		Entrypoint:        options.entrypointCmd,
 		Labels:            labels,
-		UseNetworkAliases: opts.useAliases,
-		NoDeps:            opts.noDeps,
+		UseNetworkAliases: options.useAliases,
+		NoDeps:            options.noDeps,
 		Index:             0,
-		QuietPull:         opts.quietPull,
+		QuietPull:         options.quietPull,
 	}
 
 	for i, service := range project.Services {
-		if service.Name == opts.Service {
-			service.StdinOpen = opts.interactive
+		if service.Name == options.Service {
+			service.StdinOpen = options.interactive
 			project.Services[i] = service
 		}
 	}

cmd/compose/stop.go

@@ -47,7 +47,7 @@ func stopCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		ValidArgsFunction: completeServiceNames(p),
 	}
 	flags := cmd.Flags()
-	flags.IntVarP(&opts.timeout, "timeout", "t", 10, "Specify a shutdown timeout in seconds")
+	flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Specify a shutdown timeout in seconds")
 
 	return cmd
 }

cmd/compose/up.go

@@ -21,9 +21,8 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/docker/compose/v2/cmd/formatter"
-
 	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/compose/v2/cmd/formatter"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -78,13 +77,13 @@ func upCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cob
 		Short: "Create and start containers",
 		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
 			create.pullChanged = cmd.Flags().Changed("pull")
-			create.timeChanged = cmd.Flags().Changed("waitTimeout")
+			create.timeChanged = cmd.Flags().Changed("timeout")
 			return validateFlags(&up, &create)
 		}),
 		RunE: p.WithServices(func(ctx context.Context, project *types.Project, services []string) error {
-			create.ignoreOrphans = utils.StringToBool(project.Environment["COMPOSE_IGNORE_ORPHANS"])
+			create.ignoreOrphans = utils.StringToBool(project.Environment[ComposeIgnoreOrphans])
 			if create.ignoreOrphans && create.removeOrphans {
-				return fmt.Errorf("COMPOSE_IGNORE_ORPHANS and --remove-orphans cannot be combined")
+				return fmt.Errorf("%s and --remove-orphans cannot be combined", ComposeIgnoreOrphans)
 			}
 			return runUp(ctx, streams, backend, create, up, project, services)
 		}),
@@ -104,7 +103,7 @@ func upCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cob
 	flags.BoolVar(&up.noStart, "no-start", false, "Don't start the services after creating them.")
 	flags.BoolVar(&up.cascadeStop, "abort-on-container-exit", false, "Stops all containers if any container was stopped. Incompatible with -d")
 	flags.StringVar(&up.exitCodeFrom, "exit-code-from", "", "Return the exit code of the selected service container. Implies --abort-on-container-exit")
-	flags.IntVarP(&create.timeout, "waitTimeout", "t", 10, "Use this waitTimeout in seconds for container shutdown when attached or when containers are already running.")
+	flags.IntVarP(&create.timeout, "timeout", "t", 0, "Use this timeout in seconds for container shutdown when attached or when containers are already running.")
 	flags.BoolVar(&up.timestamp, "timestamps", false, "Show timestamps.")
 	flags.BoolVar(&up.noDeps, "no-deps", false, "Don't start linked services.")
 	flags.BoolVar(&create.recreateDeps, "always-recreate-deps", false, "Recreate dependent containers. Incompatible with --no-recreate.")
@@ -164,17 +163,31 @@ func runUp(ctx context.Context, streams api.Streams, backend api.Service, create
 		consumer = formatter.NewLogConsumer(ctx, streams.Out(), streams.Err(), !upOptions.noColor, !upOptions.noPrefix, upOptions.timestamp)
 	}
 
-	attachTo := services
+	attachTo := utils.Set[string]{}
 	if len(upOptions.attach) > 0 {
-		attachTo = upOptions.attach
+		attachTo.AddAll(upOptions.attach...)
 	}
 	if upOptions.attachDependencies {
-		attachTo = project.ServiceNames()
+		if err := project.WithServices(attachTo.Elements(), func(s types.ServiceConfig) error {
+			if s.Attach == nil || *s.Attach {
+				attachTo.Add(s.Name)
+			}
+			return nil
+		}); err != nil {
+			return err
+		}
 	}
 	if len(attachTo) == 0 {
-		attachTo = project.ServiceNames()
+		if err := project.WithServices(services, func(s types.ServiceConfig) error {
+			if s.Attach == nil || *s.Attach {
+				attachTo.Add(s.Name)
+			}
+			return nil
+		}); err != nil {
+			return err
+		}
 	}
-	attachTo = utils.Remove(attachTo, upOptions.noAttach...)
+	attachTo.RemoveAll(upOptions.noAttach...)
 
 	create := api.CreateOptions{
 		Services:             services,
@@ -198,7 +211,7 @@ func runUp(ctx context.Context, streams api.Streams, backend api.Service, create
 		Start: api.StartOptions{
 			Project:      project,
 			Attach:       consumer,
-			AttachTo:     attachTo,
+			AttachTo:     attachTo.Elements(),
 			ExitCodeFrom: upOptions.exitCodeFrom,
 			CascadeStop:  upOptions.cascadeStop,
 			Wait:         upOptions.wait,

cmd/compose/viz.go

@@ -0,0 +1,96 @@
+/*
+   Copyright 2023 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/docker/compose/v2/pkg/api"
+	"github.com/spf13/cobra"
+)
+
+type vizOptions struct {
+	*ProjectOptions
+	includeNetworks  bool
+	includePorts     bool
+	includeImageName bool
+	indentationStr   string
+}
+
+func vizCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+	opts := vizOptions{
+		ProjectOptions: p,
+	}
+	var indentationSize int
+	var useSpaces bool
+
+	cmd := &cobra.Command{
+		Use:   "viz [OPTIONS]",
+		Short: "EXPERIMENTAL - Generate a graphviz graph from your compose file",
+		PreRunE: Adapt(func(ctx context.Context, args []string) error {
+			var err error
+			opts.indentationStr, err = preferredIndentationStr(indentationSize, useSpaces)
+			return err
+		}),
+		RunE: Adapt(func(ctx context.Context, args []string) error {
+			return runViz(ctx, backend, &opts)
+		}),
+	}
+
+	cmd.Flags().BoolVar(&opts.includePorts, "ports", false, "Include service's exposed ports in output graph")
+	cmd.Flags().BoolVar(&opts.includeNetworks, "networks", false, "Include service's attached networks in output graph")
+	cmd.Flags().BoolVar(&opts.includeImageName, "image", false, "Include service's image name in output graph")
+	cmd.Flags().IntVar(&indentationSize, "indentation-size", 1, "Number of tabs or spaces to use for indentation")
+	cmd.Flags().BoolVar(&useSpaces, "spaces", false, "If given, space character ' ' will be used to indent,\notherwise tab character '\\t' will be used")
+	return cmd
+}
+
+func runViz(ctx context.Context, backend api.Service, opts *vizOptions) error {
+	_, _ = fmt.Fprintln(os.Stderr, "viz command is EXPERIMENTAL")
+	project, err := opts.ToProject(nil)
+	if err != nil {
+		return err
+	}
+
+	// build graph
+	graphStr, _ := backend.Viz(ctx, project, api.VizOptions{
+		IncludeNetworks:  opts.includeNetworks,
+		IncludePorts:     opts.includePorts,
+		IncludeImageName: opts.includeImageName,
+		Indentation:      opts.indentationStr,
+	})
+
+	fmt.Println(graphStr)
+
+	return nil
+}
+
+// preferredIndentationStr returns a single string given the indentation preference
+func preferredIndentationStr(size int, useSpace bool) (string, error) {
+	if size < 0 {
+		return "", fmt.Errorf("invalid indentation size: %d", size)
+	}
+
+	indentationStr := "\t"
+	if useSpace {
+		indentationStr = " "
+	}
+	return strings.Repeat(indentationStr, size), nil
+}

cmd/compose/viz_test.go

@@ -0,0 +1,92 @@
+/*
+   Copyright 2020 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPreferredIndentationStr(t *testing.T) {
+	type args struct {
+		size     int
+		useSpace bool
+	}
+	tests := []struct {
+		name    string
+		args    args
+		want    string
+		wantErr bool
+	}{
+		{
+			name: "should return '\\t\\t'",
+			args: args{
+				size:     2,
+				useSpace: false,
+			},
+			want:    "\t\t",
+			wantErr: false,
+		},
+		{
+			name: "should return '    '",
+			args: args{
+				size:     4,
+				useSpace: true,
+			},
+			want:    "    ",
+			wantErr: false,
+		},
+		{
+			name: "should return ''",
+			args: args{
+				size:     0,
+				useSpace: false,
+			},
+			want:    "",
+			wantErr: false,
+		},
+		{
+			name: "should return ''",
+			args: args{
+				size:     0,
+				useSpace: true,
+			},
+			want:    "",
+			wantErr: false,
+		},
+		{
+			name: "should throw error because indentation size < 0",
+			args: args{
+				size:     -1,
+				useSpace: false,
+			},
+			want:    "",
+			wantErr: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := preferredIndentationStr(tt.args.size, tt.args.useSpace)
+			if tt.wantErr && assert.NotNilf(t, err, fmt.Sprintf("preferredIndentationStr(%v, %v)", tt.args.size, tt.args.useSpace)) {
+				return
+			}
+			assert.Equalf(t, tt.want, got, "preferredIndentationStr(%v, %v)", tt.args.size, tt.args.useSpace)
+		})
+	}
+}

cmd/compose/wait.go

@@ -0,0 +1,72 @@
+/*
+   Copyright 2023 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"context"
+	"os"
+
+	"github.com/docker/cli/cli"
+	"github.com/docker/compose/v2/pkg/api"
+	"github.com/spf13/cobra"
+)
+
+type waitOptions struct {
+	*ProjectOptions
+
+	services []string
+
+	downProject bool
+}
+
+func waitCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+	opts := waitOptions{
+		ProjectOptions: p,
+	}
+
+	var statusCode int64
+	var err error
+	cmd := &cobra.Command{
+		Use:   "wait SERVICE [SERVICE...] [OPTIONS]",
+		Short: "Block until the first service container stops",
+		Args:  cli.RequiresMinArgs(1),
+		RunE: Adapt(func(ctx context.Context, services []string) error {
+			opts.services = services
+			statusCode, err = runWait(ctx, backend, &opts)
+			return err
+		}),
+		PostRun: func(cmd *cobra.Command, args []string) {
+			os.Exit(int(statusCode))
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.downProject, "down-project", false, "Drops project when the first container stops")
+
+	return cmd
+}
+
+func runWait(ctx context.Context, backend api.Service, opts *waitOptions) (int64, error) {
+	_, name, err := opts.projectOrName()
+	if err != nil {
+		return 0, err
+	}
+
+	return backend.Wait(ctx, name, api.WaitOptions{
+		Services:                   opts.services,
+		DownProjectOnContainerExit: opts.downProject,
+	})
+}

cmd/main.go

@@ -23,6 +23,7 @@ import (
 	"github.com/docker/cli/cli-plugins/manager"
 	"github.com/docker/cli/cli-plugins/plugin"
 	"github.com/docker/cli/cli/command"
+	"github.com/docker/compose/v2/cmd/cmdtrace"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/cmd/compatibility"
@@ -38,14 +39,20 @@ func pluginMain() {
 		cmd := commands.RootCommand(dockerCli, serviceProxy)
 		originalPreRun := cmd.PersistentPreRunE
 		cmd.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
+			// initialize the dockerCli instance
 			if err := plugin.PersistentPreRunE(cmd, args); err != nil {
 				return err
 			}
+			// TODO(milas): add an env var to enable logging from the
+			// OTel components for debugging purposes
+			_ = cmdtrace.Setup(cmd, dockerCli)
+
 			if originalPreRun != nil {
 				return originalPreRun(cmd, args)
 			}
 			return nil
 		}
+
 		cmd.SetFlagErrorFunc(func(c *cobra.Command, err error) error {
 			return dockercli.StatusError{
 				StatusCode: compose.CommandSyntaxFailure.ExitCode,

codecov.yml

@@ -0,0 +1,21 @@
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+        target: auto
+        threshold: 2%
+    patch:
+      default:
+        informational: true
+
+comment:
+  require_changes: true
+
+ignore:
+  - "packaging"
+  - "docs"
+  - "bin"
+  - "e2e"
+  - "pkg/e2e"
+  - "**/*_test.go"

docker-bake.hcl

@@ -25,13 +25,16 @@ variable "DOCS_FORMATS" {
   default = "md,yaml"
 }
 
-# Defines the output folder
+# Defines the output folder to override the default behavior.
+# See Makefile for details, this is generally only useful for
+# the packaging scripts and care should be taken to not break
+# them.
 variable "DESTDIR" {
   default = ""
 }
-function "bindir" {
+function "outdir" {
   params = [defaultdir]
-  result = DESTDIR != "" ? DESTDIR : "./bin/${defaultdir}"
+  result = DESTDIR != "" ? DESTDIR : "${defaultdir}"
 }
 
 # Special target: https://github.com/docker/metadata-action#bake-definition
@@ -84,23 +87,23 @@ target "vendor-update" {
 target "test" {
   inherits = ["_common"]
   target = "test-coverage"
-  output = [bindir("coverage")]
+  output = [outdir("./bin/coverage/unit")]
 }
 
 target "binary-with-coverage" {
   inherits = ["_common"]
   target = "binary"
   args = {
-    BUILD_FLAGS = "-cover"
+    BUILD_FLAGS = "-cover -covermode=atomic"
   }
-  output = [bindir("build")]
+  output = [outdir("./bin/build")]
   platforms = ["local"]
 }
 
 target "binary" {
   inherits = ["_common"]
   target = "binary"
-  output = [bindir("build")]
+  output = [outdir("./bin/build")]
   platforms = ["local"]
 }
 
@@ -124,7 +127,7 @@ target "binary-cross" {
 target "release" {
   inherits = ["binary-cross"]
   target = "release"
-  output = [bindir("release")]
+  output = [outdir("./bin/release")]
 }
 
 target "docs-validate" {

docs/reference/compose.md

@@ -1,13 +1,12 @@
 # docker compose
 
 <!---MARKER_GEN_START-->
-Docker Compose
+Define and run multi-container applications with Docker.
 
 ### Subcommands
 
 | Name                            | Description                                                             |
 |:--------------------------------|:------------------------------------------------------------------------|
-| [`alpha`](compose_alpha.md)     | Experimental commands                                                   |
 | [`build`](compose_build.md)     | Build or rebuild services                                               |
 | [`config`](compose_config.md)   | Parse, resolve and render compose file in canonical format              |
 | [`cp`](compose_cp.md)           | Copy files/folders between a service container and the local filesystem |
@@ -33,6 +32,7 @@ Docker Compose
 | [`unpause`](compose_unpause.md) | Unpause services                                                        |
 | [`up`](compose_up.md)           | Create and start containers                                             |
 | [`version`](compose_version.md) | Show the Docker Compose version information                             |
+| [`wait`](compose_wait.md)       | Block until the first service container stops                           |
 
 
 ### Options
@@ -41,10 +41,12 @@ Docker Compose
 |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
 | `--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                                                           |
 | `--profile`            | `stringArray` |         | Specify a profile to enable                                                                         |
+| `--progress`           | `string`      | `auto`  | Set type of progress output (auto, tty, plain, quiet)                                               |
 | `--project-directory`  | `string`      |         | Specify an alternate working directory<br>(default: the path of the, first specified, Compose file) |
 | `-p`, `--project-name` | `string`      |         | Project name                                                                                        |
 
@@ -169,3 +171,28 @@ 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 shows you all the steps Compose applies when executing a 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
+```
+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.
+
+Dry Run mode works with almost all commands. 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.  

docs/reference/compose_alpha.md

@@ -5,12 +5,18 @@ 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                  |
-| [`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 |
 
 
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
 
 <!---MARKER_GEN_END-->
 

docs/reference/compose_alpha_publish.md

@@ -0,0 +1,14 @@
+# docker compose alpha publish
+
+<!---MARKER_GEN_START-->
+Publish compose application
+
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/compose_alpha_viz.md

@@ -0,0 +1,19 @@
+# docker compose alpha viz
+
+<!---MARKER_GEN_START-->
+EXPERIMENTAL - Generate a graphviz graph from your compose file
+
+### Options
+
+| 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                                                |
+| `--ports`            |       |         | Include service's exposed ports in output graph                                                    |
+| `--spaces`           |       |         | If given, space character ' ' will be used to indent,<br>otherwise tab character '\t' will be used |
+
+
+<!---MARKER_GEN_END-->
+

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

@@ -5,15 +5,17 @@ Build or rebuild services
 
 ### Options
 
-| Name            | Type          | Default | Description                                                                                                 |
-|:----------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------|
-| `--build-arg`   | `stringArray` |         | Set build-time variables for services.                                                                      |
-| `--no-cache`    |               |         | Do not use cache when building the image                                                                    |
-| `--progress`    | `string`      | `auto`  | Set type of progress output (auto, tty, plain, quiet)                                                       |
-| `--pull`        |               |         | Always attempt to pull a newer version of the image.                                                        |
-| `--push`        |               |         | Push service images.                                                                                        |
-| `-q`, `--quiet` |               |         | Don't print anything to STDOUT                                                                              |
-| `--ssh`         | `string`      |         | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) |
+| Name             | Type          | Default | Description                                                                                                 |
+|:-----------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------|
+| `--build-arg`    | `stringArray` |         | Set build-time variables for services.                                                                      |
+| `--builder`      | `string`      |         | Set builder to use.                                                                                         |
+| `--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                                                                    |
+| `--pull`         |               |         | Always attempt to pull a newer version of the image.                                                        |
+| `--push`         |               |         | Push service images.                                                                                        |
+| `-q`, `--quiet`  |               |         | Don't print anything to STDOUT                                                                              |
+| `--ssh`          | `string`      |         | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent) |
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_config.md

@@ -11,12 +11,14 @@ 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.                                        |
 | `--no-consistency`        |          |         | Don't check model consistency - warning: may produce invalid Compose output |
 | `--no-interpolate`        |          |         | Don't interpolate environment variables.                                    |
 | `--no-normalize`          |          |         | Don't normalize compose model.                                              |
+| `--no-path-resolution`    |          |         | Don't resolve file paths.                                                   |
 | `-o`, `--output`          | `string` |         | Save to file (default to stdout)                                            |
 | `--profiles`              |          |         | Print the profile names, one per line.                                      |
 | `-q`, `--quiet`           |          |         | Only validate the configuration, don't print anything.                      |

docs/reference/compose_cp.md

@@ -5,11 +5,12 @@ Copy files/folders between a service container and the local filesystem
 
 ### Options
 
-| Name                  | Type  | Default | Description                                                           |
-|:----------------------|:------|:--------|:----------------------------------------------------------------------|
-| `-a`, `--archive`     |       |         | Archive mode (copy all uid/gid information)                           |
-| `-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 . |
+| 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 service has multiple replicas |
 
 
 <!---MARKER_GEN_END-->

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,10 +7,11 @@ 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                                                                                    |
-| `-v`, `--volumes`  |          |         | Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers. |
+| `-t`, `--timeout`  | `int`    | `0`     | Specify a shutdown timeout in seconds                                                                                    |
+| `-v`, `--volumes`  |          |         | Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers. |
 
 
 <!---MARKER_GEN_END-->

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-->

docs/reference/compose_exec.md

@@ -5,15 +5,16 @@ Execute a command in a running container.
 
 ### Options
 
-| Name              | Type          | Default | Description                                                                       |
-|:------------------|:--------------|:--------|:----------------------------------------------------------------------------------|
-| `-d`, `--detach`  |               |         | Detached mode: Run command in the background.                                     |
-| `-e`, `--env`     | `stringArray` |         | Set environment variables                                                         |
-| `--index`         | `int`         | `1`     | index of the container if there are multiple instances of a service [default: 1]. |
-| `-T`, `--no-TTY`  |               |         | Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.  |
-| `--privileged`    |               |         | Give extended privileges to the process.                                          |
-| `-u`, `--user`    | `string`      |         | Run the command as this user.                                                     |
-| `-w`, `--workdir` | `string`      |         | Path to workdir directory for this command.                                       |
+| Name              | Type          | Default | Description                                                                      |
+|:------------------|:--------------|:--------|:---------------------------------------------------------------------------------|
+| `-d`, `--detach`  |               |         | Detached mode: Run command in the background.                                    |
+| `--dry-run`       |               |         | Execute command in dry run mode                                                  |
+| `-e`, `--env`     | `stringArray` |         | Set environment variables                                                        |
+| `--index`         | `int`         | `0`     | index of the container if service has multiple replicas                          |
+| `-T`, `--no-TTY`  |               |         | Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY. |
+| `--privileged`    |               |         | Give extended privileges to the process.                                         |
+| `-u`, `--user`    | `string`      |         | Run the command as this user.                                                    |
+| `-w`, `--workdir` | `string`      |         | Path to workdir directory for this command.                                      |
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_images.md

@@ -7,6 +7,7 @@ List images used by the created containers
 
 | Name            | Type     | Default | Description                                 |
 |:----------------|:---------|:--------|:--------------------------------------------|
+| `--dry-run`     |          |         | Execute command in dry run mode             |
 | `--format`      | `string` | `table` | Format the output. Values: [table \| json]. |
 | `-q`, `--quiet` |          |         | Only display IDs                            |
 

docs/reference/compose_kill.md

@@ -7,6 +7,7 @@ Force stop service containers.
 
 | Name               | Type     | Default   | Description                                                     |
 |:-------------------|:---------|:----------|:----------------------------------------------------------------|
+| `--dry-run`        |          |           | Execute command in dry run mode                                 |
 | `--remove-orphans` |          |           | Remove containers for services not defined in the Compose file. |
 | `-s`, `--signal`   | `string` | `SIGKILL` | SIGNAL to send to the container.                                |
 

docs/reference/compose_logs.md

@@ -7,6 +7,7 @@ View output from containers
 
 | Name                 | Type     | Default | Description                                                                                    |
 |:---------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
+| `--dry-run`          |          |         | Execute command in dry run mode                                                                |
 | `-f`, `--follow`     |          |         | Follow log output.                                                                             |
 | `--no-color`         |          |         | Produce monochrome output.                                                                     |
 | `--no-log-prefix`    |          |         | Don't print prefix in logs.                                                                    |

docs/reference/compose_ls.md

@@ -8,6 +8,7 @@ List running compose projects
 | Name            | Type     | Default | Description                                 |
 |:----------------|:---------|:--------|:--------------------------------------------|
 | `-a`, `--all`   |          |         | Show all stopped Compose projects           |
+| `--dry-run`     |          |         | Execute command in dry run mode             |
 | `--filter`      | `filter` |         | Filter output based on conditions provided. |
 | `--format`      | `string` | `table` | Format the output. Values: [table \| json]. |
 | `-q`, `--quiet` |          |         | Only display IDs.                           |

docs/reference/compose_pause.md

@@ -3,6 +3,12 @@
 <!---MARKER_GEN_START-->
 Pause services
 
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
 
 <!---MARKER_GEN_END-->
 

docs/reference/compose_port.md

@@ -7,7 +7,8 @@ Print the public port for a port binding.
 
 | Name         | Type     | Default | Description                                             |
 |:-------------|:---------|:--------|:--------------------------------------------------------|
-| `--index`    | `int`    | `1`     | index of the container if service has multiple replicas |
+| `--dry-run`  |          |         | Execute command in dry run mode                         |
+| `--index`    | `int`    | `0`     | index of the container if service has multiple replicas |
 | `--protocol` | `string` | `tcp`   | tcp or udp                                              |
 
 

docs/reference/compose_ps.md

@@ -8,6 +8,7 @@ List containers
 | Name                  | Type          | Default | Description                                                                                                   |
 |:----------------------|:--------------|:--------|:--------------------------------------------------------------------------------------------------------------|
 | `-a`, `--all`         |               |         | Show all stopped containers (including those created by the run command)                                      |
+| `--dry-run`           |               |         | Execute command in dry run mode                                                                               |
 | [`--filter`](#filter) | `string`      |         | Filter services by a property (supported filters: status).                                                    |
 | [`--format`](#format) | `string`      | `table` | Format the output. Values: [table \| json]                                                                    |
 | `-q`, `--quiet`       |               |         | Only display IDs                                                                                              |

docs/reference/compose_pull.md

@@ -7,6 +7,7 @@ Pull service images
 
 | Name                     | Type | Default | Description                                             |
 |:-------------------------|:-----|:--------|:--------------------------------------------------------|
+| `--dry-run`              |      |         | Execute command in dry run mode                         |
 | `--ignore-buildable`     |      |         | Ignore images that can be built.                        |
 | `--ignore-pull-failures` |      |         | Pull what it can and ignores images with pull failures. |
 | `--include-deps`         |      |         | Also pull services declared as dependencies.            |

docs/reference/compose_push.md

@@ -7,6 +7,7 @@ Push service images
 
 | Name                     | Type | Default | Description                                            |
 |:-------------------------|:-----|:--------|:-------------------------------------------------------|
+| `--dry-run`              |      |         | Execute command in dry run mode                        |
 | `--ignore-push-failures` |      |         | Push what it can and ignores images with push failures |
 | `--include-deps`         |      |         | Also push images of services declared as dependencies  |
 | `-q`, `--quiet`          |      |         | Push without printing progress information             |

docs/reference/compose_restart.md

@@ -7,8 +7,9 @@ Restart service containers
 
 | Name              | Type  | Default | Description                           |
 |:------------------|:------|:--------|:--------------------------------------|
+| `--dry-run`       |       |         | Execute command in dry run mode       |
 | `--no-deps`       |       |         | Don't restart dependent services.     |
-| `-t`, `--timeout` | `int` | `10`    | Specify a shutdown timeout in seconds |
+| `-t`, `--timeout` | `int` | `0`     | Specify a shutdown timeout in seconds |
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_rm.md

@@ -12,6 +12,7 @@ Any data which is not in a volume will be lost.
 
 | Name              | Type | Default | Description                                         |
 |:------------------|:-----|:--------|:----------------------------------------------------|
+| `--dry-run`       |      |         | Execute command in dry run mode                     |
 | `-f`, `--force`   |      |         | Don't ask to confirm removal                        |
 | `-s`, `--stop`    |      |         | Stop the containers, if required, before removing   |
 | `-v`, `--volumes` |      |         | Remove any anonymous volumes attached to containers |

docs/reference/compose_run.md

@@ -8,7 +8,10 @@ Run a one-off command on a service.
 | Name                  | Type          | Default | Description                                                                       |
 |:----------------------|:--------------|:--------|:----------------------------------------------------------------------------------|
 | `--build`             |               |         | Build image before starting container.                                            |
+| `--cap-add`           | `list`        |         | Add Linux capabilities                                                            |
+| `--cap-drop`          | `list`        |         | Drop Linux capabilities                                                           |
 | `-d`, `--detach`      |               |         | Run container in background and print container ID                                |
+| `--dry-run`           |               |         | Execute command in dry run mode                                                   |
 | `--entrypoint`        | `string`      |         | Override the entrypoint of the image                                              |
 | `-e`, `--env`         | `stringArray` |         | Set environment variables                                                         |
 | `-i`, `--interactive` |               |         | Keep STDIN open even if not attached.                                             |
@@ -33,7 +36,7 @@ Run a one-off command on a service.
 
 Runs a one-time command against a service.
 
-the following command starts the `web` service and runs `bash` as its command:
+The following command starts the `web` service and runs `bash` as its command:
 
 ```console
 $ docker compose run web bash

docs/reference/compose_start.md

@@ -3,6 +3,12 @@
 <!---MARKER_GEN_START-->
 Start services
 
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
 
 <!---MARKER_GEN_END-->
 

docs/reference/compose_stop.md

@@ -7,7 +7,8 @@ Stop services
 
 | Name              | Type  | Default | Description                           |
 |:------------------|:------|:--------|:--------------------------------------|
-| `-t`, `--timeout` | `int` | `10`    | Specify a shutdown timeout in seconds |
+| `--dry-run`       |       |         | Execute command in dry run mode       |
+| `-t`, `--timeout` | `int` | `0`     | Specify a shutdown timeout in seconds |
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_top.md

@@ -3,6 +3,12 @@
 <!---MARKER_GEN_START-->
 Display the running processes
 
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
 
 <!---MARKER_GEN_END-->
 

docs/reference/compose_unpause.md

@@ -3,6 +3,12 @@
 <!---MARKER_GEN_START-->
 Unpause services
 
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+
 
 <!---MARKER_GEN_END-->
 

docs/reference/compose_up.md

@@ -5,32 +5,33 @@ Create and start containers
 
 ### Options
 
-| Name                         | Type          | Default   | Description                                                                                                  |
-|:-----------------------------|:--------------|:----------|:-------------------------------------------------------------------------------------------------------------|
-| `--abort-on-container-exit`  |               |           | Stops all containers if any container was stopped. Incompatible with -d                                      |
-| `--always-recreate-deps`     |               |           | Recreate dependent containers. Incompatible with --no-recreate.                                              |
-| `--attach`                   | `stringArray` |           | Attach to service output.                                                                                    |
-| `--attach-dependencies`      |               |           | Attach to dependent containers.                                                                              |
-| `--build`                    |               |           | Build images before starting containers.                                                                     |
-| `-d`, `--detach`             |               |           | Detached mode: Run containers in the background                                                              |
-| `--exit-code-from`           | `string`      |           | Return the exit code of the selected service container. Implies --abort-on-container-exit                    |
-| `--force-recreate`           |               |           | Recreate containers even if their configuration and image haven't changed.                                   |
-| `--no-attach`                | `stringArray` |           | Don't attach to specified service.                                                                           |
-| `--no-build`                 |               |           | Don't build an image, even if it's missing.                                                                  |
-| `--no-color`                 |               |           | Produce monochrome output.                                                                                   |
-| `--no-deps`                  |               |           | Don't start linked services.                                                                                 |
-| `--no-log-prefix`            |               |           | Don't print prefix in logs.                                                                                  |
-| `--no-recreate`              |               |           | If containers already exist, don't recreate them. Incompatible with --force-recreate.                        |
-| `--no-start`                 |               |           | Don't start the services after creating them.                                                                |
-| `--pull`                     | `string`      | `missing` | Pull image before running ("always"\|"missing"\|"never")                                                     |
-| `--quiet-pull`               |               |           | Pull without printing progress information.                                                                  |
-| `--remove-orphans`           |               |           | Remove containers for services not defined in the Compose file.                                              |
-| `-V`, `--renew-anon-volumes` |               |           | Recreate anonymous volumes instead of retrieving data from the previous containers.                          |
-| `--scale`                    | `stringArray` |           | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.                |
-| `--timestamps`               |               |           | Show timestamps.                                                                                             |
-| `--wait`                     |               |           | Wait for services to be running\|healthy. Implies detached mode.                                             |
-| `--wait-timeout`             | `int`         | `0`       | timeout waiting for application to be running\|healthy.                                                      |
-| `-t`, `--waitTimeout`        | `int`         | `10`      | Use this waitTimeout in seconds for container shutdown when attached or when containers are already running. |
+| Name                         | Type          | Default   | Description                                                                                              |
+|:-----------------------------|:--------------|:----------|:---------------------------------------------------------------------------------------------------------|
+| `--abort-on-container-exit`  |               |           | Stops all containers if any container was stopped. Incompatible with -d                                  |
+| `--always-recreate-deps`     |               |           | Recreate dependent containers. Incompatible with --no-recreate.                                          |
+| `--attach`                   | `stringArray` |           | Attach to service output.                                                                                |
+| `--attach-dependencies`      |               |           | Attach to dependent containers.                                                                          |
+| `--build`                    |               |           | Build images before starting containers.                                                                 |
+| `-d`, `--detach`             |               |           | Detached mode: Run containers in the background                                                          |
+| `--dry-run`                  |               |           | Execute command in dry run mode                                                                          |
+| `--exit-code-from`           | `string`      |           | Return the exit code of the selected service container. Implies --abort-on-container-exit                |
+| `--force-recreate`           |               |           | Recreate containers even if their configuration and image haven't changed.                               |
+| `--no-attach`                | `stringArray` |           | Don't attach to specified service.                                                                       |
+| `--no-build`                 |               |           | Don't build an image, even if it's missing.                                                              |
+| `--no-color`                 |               |           | Produce monochrome output.                                                                               |
+| `--no-deps`                  |               |           | Don't start linked services.                                                                             |
+| `--no-log-prefix`            |               |           | Don't print prefix in logs.                                                                              |
+| `--no-recreate`              |               |           | If containers already exist, don't recreate them. Incompatible with --force-recreate.                    |
+| `--no-start`                 |               |           | Don't start the services after creating them.                                                            |
+| `--pull`                     | `string`      | `missing` | Pull image before running ("always"\|"missing"\|"never")                                                 |
+| `--quiet-pull`               |               |           | Pull without printing progress information.                                                              |
+| `--remove-orphans`           |               |           | Remove containers for services not defined in the Compose file.                                          |
+| `-V`, `--renew-anon-volumes` |               |           | Recreate anonymous volumes instead of retrieving data from the previous containers.                      |
+| `--scale`                    | `stringArray` |           | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.            |
+| `-t`, `--timeout`            | `int`         | `0`       | Use this timeout in seconds for container shutdown when attached or when containers are already running. |
+| `--timestamps`               |               |           | Show timestamps.                                                                                         |
+| `--wait`                     |               |           | Wait for services to be running\|healthy. Implies detached mode.                                         |
+| `--wait-timeout`             | `int`         | `0`       | timeout waiting for application to be running\|healthy.                                                  |
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_version.md

@@ -7,6 +7,7 @@ Show the Docker Compose version information
 
 | Name             | Type     | Default | Description                                                    |
 |:-----------------|:---------|:--------|:---------------------------------------------------------------|
+| `--dry-run`      |          |         | Execute command in dry run mode                                |
 | `-f`, `--format` | `string` |         | Format the output. Values: [pretty \| json]. (Default: pretty) |
 | `--short`        |          |         | Shows only Compose's version number.                           |
 

docs/reference/compose_wait.md

@@ -0,0 +1,15 @@
+# docker compose wait
+
+<!---MARKER_GEN_START-->
+Block until the first service container stops
+
+### Options
+
+| Name             | Type | Default | Description                                  |
+|:-----------------|:-----|:--------|:---------------------------------------------|
+| `--down-project` |      |         | Drops project when the first container stops |
+| `--dry-run`      |      |         | Execute command in dry run mode              |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/docker_compose.yaml

@@ -117,6 +117,31 @@ 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 shows you all the steps Compose applies when executing a 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
+    ```
+    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.
+
+    Dry Run mode works with almost all commands. 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.
 usage: docker compose
 pname: docker
 plink: docker.yaml
@@ -146,6 +171,7 @@ cname:
     - docker compose unpause
     - docker compose up
     - docker compose version
+    - docker compose wait
 clink:
     - docker_compose_build.yaml
     - docker_compose_config.yaml
@@ -172,6 +198,7 @@ clink:
     - docker_compose_unpause.yaml
     - docker_compose_up.yaml
     - docker_compose_version.yaml
+    - docker_compose_wait.yaml
 options:
     - option: ansi
       value_type: string
@@ -199,7 +226,7 @@ options:
       default_value: "false"
       description: Execute command in dry run mode
       deprecated: false
-      hidden: true
+      hidden: false
       experimental: false
       experimentalcli: false
       kubernetes: false
@@ -255,6 +282,16 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: progress
+      value_type: string
+      default_value: auto
+      description: Set type of progress output (auto, tty, plain, quiet)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: project-directory
       value_type: string
       description: |-
@@ -310,6 +347,7 @@ options:
       kubernetes: false
       swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_alpha.yaml

@@ -4,12 +4,26 @@ long: Experimental commands
 pname: docker compose
 plink: docker_compose.yaml
 cname:
-    - docker compose alpha dry-run
+    - docker compose alpha publish
+    - docker compose alpha viz
     - docker compose alpha watch
 clink:
-    - docker_compose_alpha_dry-run.yaml
+    - docker_compose_alpha_publish.yaml
+    - docker_compose_alpha_viz.yaml
     - docker_compose_alpha_watch.yaml
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: true
 experimental: false
 experimentalcli: true
 kubernetes: false

docs/reference/docker_compose_alpha_publish.yaml

@@ -0,0 +1,24 @@
+command: docker compose alpha publish
+short: Publish compose application
+long: Publish compose application
+usage: docker compose alpha publish [OPTIONS] [REPOSITORY]
+pname: docker compose alpha
+plink: docker_compose_alpha.yaml
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+deprecated: false
+hidden: false
+experimental: false
+experimentalcli: true
+kubernetes: false
+swarm: false
+

docs/reference/docker_compose_alpha_viz.yaml

@@ -0,0 +1,77 @@
+command: docker compose alpha viz
+short: EXPERIMENTAL - Generate a graphviz graph from your compose file
+long: EXPERIMENTAL - Generate a graphviz graph from your compose file
+usage: docker compose alpha viz [OPTIONS]
+pname: docker compose alpha
+plink: docker_compose_alpha.yaml
+options:
+    - option: image
+      value_type: bool
+      default_value: "false"
+      description: Include service's image name in output graph
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: indentation-size
+      value_type: int
+      default_value: "1"
+      description: Number of tabs or spaces to use for indentation
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: networks
+      value_type: bool
+      default_value: "false"
+      description: Include service's attached networks in output graph
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: ports
+      value_type: bool
+      default_value: "false"
+      description: Include service's exposed ports in output graph
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: spaces
+      value_type: bool
+      default_value: "false"
+      description: |-
+        If given, space character ' ' will be used to indent,
+        otherwise tab character '\t' will be used
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+deprecated: false
+hidden: false
+experimental: false
+experimentalcli: true
+kubernetes: false
+swarm: false
+

docs/reference/docker_compose_alpha_watch.yaml

@@ -17,7 +17,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: true
 kubernetes: false

docs/reference/docker_compose_build.yaml

@@ -24,6 +24,15 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: builder
+      value_type: string
+      description: Set builder to use.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: compress
       value_type: bool
       default_value: "true"
@@ -46,11 +55,12 @@ options:
       swarm: false
     - option: memory
       shorthand: m
-      value_type: string
+      value_type: bytes
+      default_value: "0"
       description: |
-        Set memory limit for the build container. Not supported on buildkit yet.
+        Set memory limit for the build container. Not supported by BuildKit.
       deprecated: false
-      hidden: true
+      hidden: false
       experimental: false
       experimentalcli: false
       kubernetes: false
@@ -89,9 +99,9 @@ options:
     - option: progress
       value_type: string
       default_value: auto
-      description: Set type of progress output (auto, tty, plain, quiet)
+      description: Set type of ui output (auto, tty, plain, quiet)
       deprecated: false
-      hidden: false
+      hidden: true
       experimental: false
       experimentalcli: false
       kubernetes: false
@@ -137,7 +147,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_config.yaml

@@ -69,6 +69,16 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: no-path-resolution
+      value_type: bool
+      default_value: "false"
+      description: Don't resolve file paths.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: output
       shorthand: o
       value_type: string
@@ -130,7 +140,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_cp.yaml

@@ -10,7 +10,7 @@ options:
     - option: all
       value_type: bool
       default_value: "false"
-      description: Copy to all the containers of the service.
+      description: copy to all the containers of the service.
       deprecated: true
       hidden: true
       experimental: false
@@ -42,8 +42,18 @@ options:
     - option: index
       value_type: int
       default_value: "0"
-      description: |
-        Index of the container if there are multiple instances of a service .
+      description: index of the container if service has multiple replicas
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
       deprecated: false
       hidden: false
       experimental: false
@@ -51,6 +61,7 @@ options:
       kubernetes: false
       swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_create.yaml

@@ -78,7 +78,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_down.yaml

@@ -14,7 +14,7 @@ long: |-
     Anonymous volumes are not removed by default. However, as they don’t have a stable name, they will not be automatically
     mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
     named volumes.
-usage: docker compose down [OPTIONS]
+usage: docker compose down [OPTIONS] [SERVICES]
 pname: docker compose
 plink: docker_compose.yaml
 options:
@@ -41,7 +41,7 @@ options:
     - option: timeout
       shorthand: t
       value_type: int
-      default_value: "10"
+      default_value: "0"
       description: Specify a shutdown timeout in seconds
       deprecated: false
       hidden: false
@@ -54,7 +54,18 @@ options:
       value_type: bool
       default_value: "false"
       description: |
-        Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers.
+        Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
       deprecated: false
       hidden: false
       experimental: false
@@ -62,6 +73,7 @@ options:
       kubernetes: false
       swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_events.yaml

@@ -34,7 +34,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_exec.yaml

@@ -33,9 +33,8 @@ options:
       swarm: false
     - option: index
       value_type: int
-      default_value: "1"
-      description: |
-        index of the container if there are multiple instances of a service [default: 1].
+      default_value: "0"
+      description: index of the container if service has multiple replicas
       deprecated: false
       hidden: false
       experimental: false
@@ -106,7 +105,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_images.yaml

@@ -26,7 +26,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_kill.yaml

@@ -31,7 +31,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_logs.yaml

@@ -79,7 +79,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_ls.yaml

@@ -46,7 +46,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_pause.yaml

@@ -5,7 +5,19 @@ long: |
 usage: docker compose pause [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_port.yaml

@@ -7,7 +7,7 @@ plink: docker_compose.yaml
 options:
     - option: index
       value_type: int
-      default_value: "1"
+      default_value: "0"
       description: index of the container if service has multiple replicas
       deprecated: false
       hidden: false
@@ -25,7 +25,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_ps.yaml

@@ -87,6 +87,17 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 examples: |-
     ### Format the output (--format) {#format}
 
@@ -169,6 +180,7 @@ examples: |-
     The `docker compose ps` command currently only supports the `--filter status=<status>`
     option, but additional filter options may be added in the future.
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_pull.yaml

@@ -68,6 +68,17 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 examples: |-
     suppose you have this `compose.yaml`:
 
@@ -113,6 +124,7 @@ examples: |-
     `docker compose pull` will try to pull image for services with a build section. If pull fails, it will let
     user know this service image MUST be built. You can skip this by setting `--ignore-buildable` flag
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_push.yaml

@@ -54,7 +54,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_restart.yaml

@@ -28,7 +28,7 @@ options:
     - option: timeout
       shorthand: t
       value_type: int
-      default_value: "10"
+      default_value: "0"
       description: Specify a shutdown timeout in seconds
       deprecated: false
       hidden: false
@@ -36,7 +36,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_rm.yaml

@@ -64,7 +64,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_run.yaml

@@ -3,7 +3,7 @@ short: Run a one-off command on a service.
 long: |-
     Runs a one-time command against a service.
 
-    the following command starts the `web` service and runs `bash` as its command:
+    The following command starts the `web` service and runs `bash` as its command:
 
     ```console
     $ docker compose run web bash
@@ -68,6 +68,24 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: cap-add
+      value_type: list
+      description: Add Linux capabilities
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: cap-drop
+      value_type: list
+      description: Drop Linux capabilities
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: detach
       shorthand: d
       value_type: bool
@@ -256,7 +274,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_start.yaml

@@ -4,7 +4,19 @@ long: Starts existing containers for a service.
 usage: docker compose start [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_stop.yaml

@@ -9,7 +9,7 @@ options:
     - option: timeout
       shorthand: t
       value_type: int
-      default_value: "10"
+      default_value: "0"
       description: Specify a shutdown timeout in seconds
       deprecated: false
       hidden: false
@@ -17,7 +17,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_top.yaml

@@ -4,6 +4,17 @@ long: Displays the running processes.
 usage: docker compose top [SERVICES...]
 pname: docker compose
 plink: docker_compose.yaml
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 examples: |-
     ```console
     $ docker compose top
@@ -12,6 +23,7 @@ examples: |-
     root   142353   142331   2    15:33   ?     00:00:00   ping localhost -c 5
     ```
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_unpause.yaml

@@ -4,7 +4,19 @@ long: Unpauses paused containers of a service.
 usage: docker compose unpause [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_up.yaml

@@ -231,6 +231,18 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: timeout
+      shorthand: t
+      value_type: int
+      default_value: "0"
+      description: |
+        Use this timeout in seconds for container shutdown when attached or when containers are already running.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: timestamps
       value_type: bool
       default_value: "false"
@@ -261,12 +273,11 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-    - option: waitTimeout
-      shorthand: t
-      value_type: int
-      default_value: "10"
-      description: |
-        Use this waitTimeout in seconds for container shutdown when attached or when containers are already running.
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
       deprecated: false
       hidden: false
       experimental: false
@@ -274,6 +285,7 @@ options:
       kubernetes: false
       swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_version.yaml

@@ -25,7 +25,19 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
+hidden: false
 experimental: false
 experimentalcli: false
 kubernetes: false

docs/reference/docker_compose_wait.yaml

@@ -0,0 +1,35 @@
+command: docker compose wait
+short: Block until the first service container stops
+long: Block until the first service container stops
+usage: docker compose wait SERVICE [SERVICE...] [OPTIONS]
+pname: docker compose
+plink: docker_compose.yaml
+options:
+    - option: down-project
+      value_type: bool
+      default_value: "false"
+      description: Drops project when the first container stops
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+inherited_options:
+    - option: dry-run
+      value_type: bool
+      default_value: "false"
+      description: Execute command in dry run mode
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+deprecated: false
+hidden: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+

e2e/cucumber-features/build-contexts.feature

@@ -7,15 +7,13 @@ Background:
           a:
             build:
                 context: .
+                dockerfile_inline: |
+                    # syntax=docker/dockerfile:1
+                    FROM alpine:latest
+                    COPY --from=dep /etc/hostname /
                 additional_contexts:
                   - dep=docker-image://ubuntu:latest
         """
-    And a dockerfile
-        """
-        # syntax=docker/dockerfile:1
-        FROM alpine:latest
-        COPY --from=dep /etc/hostname /
-        """
 
 Scenario: Build w/ build context
     When I run "compose build"

e2e/cucumber-features/port-conflict.feature

@@ -0,0 +1,28 @@
+Feature: Report port conflicts
+
+Background:
+    Given a compose file
+        """
+        services:
+          web:
+            image: nginx
+            ports:
+            - 31415:80
+        """
+    And I run "docker rm -f nginx-pi-31415"
+
+Scenario: Reports a port allocation conflict with another container
+    Given I run "docker run -d -p 31415:80 --name nginx-pi-31415 nginx"
+    When I run "compose up -d"
+    Then the output contains "port is already allocated"
+    And the exit code is 1
+
+Scenario: Reports a port conflict with some other process
+    Given a process listening on port 31415
+    When I run "compose up -d"
+    Then the output contains "address already in use"
+    And the exit code is 1
+
+Scenario: Cleanup
+    Given I run "docker rm -f nginx-pi-31415"
+

e2e/cucumber-features/ps.feature

@@ -16,6 +16,7 @@ Background:
         """
         FROM golang:1.19-alpine
         """
+    And I run "docker rm -f external-test"
 
 Scenario: external container from compose image exists
     When I run "compose build"
@@ -24,4 +25,5 @@ Scenario: external container from compose image exists
     Then the exit code is 0
     And I run "compose ps -a"
     Then the output does not contain "external-test"
+    And I run "docker rm -f external-test"
 

e2e/cucumber-features/stop.feature

@@ -6,7 +6,7 @@ Background:
         services:
           should_fail:
             image: alpine
-            command: ls /does_not_exist
+            command: ['sh', '-c', 'exit 123']
           sleep: # will be killed
             image: alpine
             command: ping localhost
@@ -15,15 +15,22 @@ Background:
 
 Scenario: Cascade stop
     When I run "compose up --abort-on-container-exit"
-    Then the output contains "should_fail-1 exited with code 1"
+    Then the output contains "should_fail-1 exited with code 123"
     And the output contains "Aborting on container exit..."
-    And the exit code is 1
+    And the exit code is 123
 
 Scenario: Exit code from
-    When I run "compose up --exit-code-from sleep"
-    Then the output contains "should_fail-1 exited with code 1"
+    When I run "compose up --exit-code-from should_fail"
+    Then the output contains "should_fail-1 exited with code 123"
     And the output contains "Aborting on container exit..."
-    And the exit code is 143
+    And the exit code is 123
+
+# TODO: this is currently not working propagating the exit code properly
+#Scenario: Exit code from (cascade stop)
+#    When I run "compose up --exit-code-from sleep"
+#    Then the output contains "should_fail-1 exited with code 123"
+#    And the output contains "Aborting on container exit..."
+#    And the exit code is 143
 
 Scenario: Exit code from unknown service
     When I run "compose up --exit-code-from unknown"

e2e/cucumber_test.go

@@ -19,6 +19,7 @@ package cucumber
 import (
 	"context"
 	"fmt"
+	"net"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -87,6 +88,7 @@ func setup(s *godog.ScenarioContext) {
 	s.Step(`output contains "(.*)"$`, th.outputContains(true))
 	s.Step(`output does not contain "(.*)"$`, th.outputContains(false))
 	s.Step(`exit code is (\d+)$`, th.exitCodeIs)
+	s.Step(`a process listening on port (\d+)$`, th.listenerOnPort)
 }
 
 type testHelper struct {
@@ -174,3 +176,16 @@ func (th *testHelper) setDockerfile(dockerfileString string) error {
 	}
 	return nil
 }
+
+func (th *testHelper) listenerOnPort(port int) error {
+	l, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
+	if err != nil {
+		return err
+	}
+
+	th.T.Cleanup(func() {
+		_ = l.Close()
+	})
+
+	return nil
+}