Strip project prefix from docker-compose up output

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:
@@ -123,18 +122,22 @@ jobs:
           set: |
             *.cache-from=type=gha,scope=test
             *.cache-to=type=gha,scope=test
+      -
+        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:
         mode:
           - plugin
           - standalone
-          - cucumber
     steps:
       -
         name: Checkout
@@ -158,7 +161,7 @@ jobs:
         name: Build
         uses: docker/bake-action@v2
         with:
-          targets: binary
+          targets: binary-with-coverage
           set: |
             *.cache-from=type=gha,scope=binary-linux-amd64
             *.cache-from=type=gha,scope=binary-e2e-${{ matrix.mode }}
@@ -176,10 +179,17 @@ jobs:
         name: Test plugin mode
         if: ${{ matrix.mode == 'plugin' }}
         run: |
-          make e2e-compose
+          rm -rf ./bin/coverage/e2e
+          mkdir -p ./bin/coverage/e2e
+          make e2e-compose GOCOVERDIR=bin/coverage/e2e TEST_FLAGS="-v"
       -
-        name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
+        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' }}
@@ -187,11 +197,44 @@ jobs:
           rm -f /usr/local/bin/docker-compose
           cp bin/build/docker-compose /usr/local/bin
           make e2e-compose-standalone
-      -
-        name: Run cucumber tests
-        if: ${{ matrix.mode == 'cucumber'}}
+
+  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: |
-          make test-cucumber
+          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:
@@ -209,10 +252,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
@@ -220,21 +263,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/codeql.yml

@@ -0,0 +1,58 @@
+name: codeql
+
+on:
+  push:
+    branches:
+       - 'main'
+    paths-ignore:
+      - '**/*.md'
+      - '**/*.txt'
+      - '**/*.yaml'
+      - '**/*_test.go'
+  pull_request:
+    branches:
+        - 'main'
+    paths-ignore:
+      - '**/*.md'
+      - '**/*.txt'
+      - '**/*.yaml'
+      - '**/*_test.go'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: 'ubuntu-latest'
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language:
+          - go
+        
+    steps:
+    -
+      name: Checkout
+      uses: actions/checkout@v4
+    -
+      name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version-file: go.mod
+        check-latest: true
+    -
+      name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+    -
+      name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+    -
+      name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/docs-upstream.yml

@@ -0,0 +1,42 @@
+# this workflow runs the remote validate bake target from docker/docs
+# to check if yaml reference docs used in this repo are valid
+name: docs-upstream
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - 'main'
+      - 'v[0-9]*'
+    paths:
+      - '.github/workflows/docs-upstream.yml'
+      - 'docs/**'
+  pull_request:
+    paths:
+      - '.github/workflows/docs-upstream.yml'
+      - 'docs/**'
+
+jobs:
+  docs-yaml:
+    runs-on: ubuntu-22.04
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Upload reference YAML docs
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs-yaml
+          path: docs/reference
+          retention-days: 1
+
+  validate:
+    uses: docker/docs/.github/workflows/validate-upstream.yml@main
+    needs:
+      - docs-yaml
+    with:
+      module-name: docker/compose

.github/workflows/docs.yml

@@ -1,56 +0,0 @@
-name: Docs
-
-on:
-  release:
-    types: [published]
-
-permissions: {}
-jobs:
-  open-pr:
-    permissions:
-      contents: write # to create branch (peter-evans/create-pull-request)
-      pull-requests: write # to create a PR (peter-evans/create-pull-request)
-
-    runs-on: ubuntu-latest
-    steps:
-      -
-        name: Checkout docs repo
-        uses: actions/checkout@v3
-        with:
-          token: ${{ secrets.GHPAT_DOCS_DISPATCH }}
-          repository: docker/docs
-          ref: main
-      -
-        name: Prepare
-        run: |
-          rm -rf ./_data/compose-cli/*
-      -
-        name: Build
-        uses: docker/build-push-action@v3
-        with:
-          context: ${{ github.server_url }}/${{ github.repository }}.git#${{ github.event.release.name }}
-          target: docs-reference
-          outputs: ./_data/compose-cli
-      -
-        name: Update compose_version in _config.yml
-        run: |
-          sed -i "s|^compose_version\:.*|compose_version\: \"${{ github.event.release.name }}\"|g" _config.yml
-          cat _config.yml | yq .compose_version
-      -
-        name: Commit changes
-        run: |
-          git add -A .
-      -
-        name: Create PR on docs repo
-        uses: peter-evans/create-pull-request@923ad837f191474af6b1721408744feb989a4c27 # v4.0.4
-        with:
-          token: ${{ secrets.GHPAT_DOCS_DISPATCH }}
-          push-to-fork: docker-tools-robot/docker.github.io
-          commit-message: Update Compose reference API to ${{ github.event.release.name }}
-          signoff: true
-          branch: dispatch/compose-api-reference-${{ github.event.release.name }}
-          delete-branch: true
-          title: Update Compose reference API to ${{ github.event.release.name }}
-          body: |
-            Update the Compose reference API documentation to keep in sync with the latest release `${{ github.event.release.name }}`
-          draft: false

.github/workflows/merge.yml

@@ -7,14 +7,16 @@ concurrency:
 on:
   push:
     branches:
-      - 'v2'
+      - 'main'
     tags:
       - 'v*'
-  workflow_dispatch:
 
 permissions:
   contents: read # to fetch code (actions/checkout)
 
+env:
+  REPO_SLUG: "docker/compose-bin"
+
 jobs:
   e2e:
     name: Build and test
@@ -72,3 +74,78 @@ jobs:
         run: |
           make e2e-compose-standalone
 
+  bin-image:
+    runs-on: ubuntu-22.04
+    outputs:
+      digest: ${{ fromJSON(steps.bake.outputs.metadata).image-cross['containerimage.digest'] }}
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v3
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v2
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      -
+        name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: |
+            ${{ env.REPO_SLUG }}
+          tags: |
+            type=ref,event=tag
+            type=edge
+          bake-target: meta-helper
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKERPUBLICBOT_USERNAME }}
+          password: ${{ secrets.DOCKERPUBLICBOT_WRITE_PAT }}
+      -
+        name: Build and push image
+        uses: docker/bake-action@v2
+        id: bake
+        with:
+          files: |
+            ./docker-bake.hcl
+            ${{ steps.meta.outputs.bake-file }}
+          targets: image-cross
+          push: ${{ github.event_name != 'pull_request' }}
+          set: |
+            *.cache-from=type=gha,scope=bin-image
+            *.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

.gitignore

@@ -1,3 +1,5 @@
 bin/
 /.vscode/
 coverage.out
+covdatafiles/
+.DS_Store

.golangci.yml

@@ -7,6 +7,7 @@ linters:
   enable:
     - depguard
     - errcheck
+    - errorlint
     - gocritic
     - gocyclo
     - gofmt
@@ -31,15 +32,23 @@ 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'
+          - pkg: gopkg.in/yaml.v2
+            desc: 'compose-go uses yaml.v3'
   gomodguard:
     blocked:
+      modules:
+        - github.com/pkg/errors:
+            recommendations:
+              - errors
+              - fmt
       versions:
+        - github.com/distribution/distribution:
+            reason: "use distribution/reference"
         - gotest.tools:
             version: "< 3.0.0"
             reason: "deprecated, pre-modules version"
@@ -62,5 +71,3 @@ issues:
   # golangci hides some golint warnings (the warning about exported things
   # withtout documentation for example), this will make it show them anyway.
   exclude-use-default: false
-  exclude:
-    - should not use dot imports

Dockerfile

@@ -15,9 +15,9 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-ARG GO_VERSION=1.20.0
-ARG XX_VERSION=1.1.2
-ARG GOLANGCI_LINT_VERSION=v1.51.0
+ARG GO_VERSION=1.21.4
+ARG XX_VERSION=1.2.1
+ARG GOLANGCI_LINT_VERSION=v1.54.2
 ARG ADDLICENSE_VERSION=v1.0.0
 
 ARG BUILD_TAGS="e2e"
@@ -27,12 +27,16 @@ ARG LICENSE_FILES=".*\(Dockerfile\|Makefile\|\.go\|\.hcl\|\.sh\)"
 # xx is a helper for cross-compilation
 FROM --platform=${BUILDPLATFORM} tonistiigi/xx:${XX_VERSION} AS xx
 
+# osxcross contains the MacOSX cross toolchain for xx
+FROM crazymax/osxcross:11.3-alpine AS osxcross
+
 FROM golangci/golangci-lint:${GOLANGCI_LINT_VERSION}-alpine AS golangci-lint
 FROM ghcr.io/google/addlicense:${ADDLICENSE_VERSION} AS addlicense
 
 FROM --platform=${BUILDPLATFORM} golang:${GO_VERSION}-alpine AS base
 COPY --from=xx / /
 RUN apk add --no-cache \
+      clang \
       docker \
       file \
       findutils \
@@ -72,19 +76,26 @@ EOT
 
 FROM build-base AS build
 ARG BUILD_TAGS
+ARG BUILD_FLAGS
 ARG TARGETPLATFORM
-RUN xx-go --wrap
 RUN --mount=type=bind,target=. \
     --mount=type=cache,target=/root/.cache \
     --mount=type=cache,target=/go/pkg/mod \
-    make build GO_BUILDTAGS="$BUILD_TAGS" DESTDIR=/usr/bin && \
-    xx-verify --static /usr/bin/docker-compose
+    --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=/out && \
+    xx-verify --static /out/docker-compose
 
 FROM build-base AS lint
 ARG BUILD_TAGS
+ENV GOLANGCI_LINT_CACHE=/cache/golangci-lint
 RUN --mount=type=bind,target=. \
     --mount=type=cache,target=/root/.cache \
+    --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/cache/golangci-lint \
     --mount=from=golangci-lint,source=/usr/bin/golangci-lint,target=/usr/bin/golangci-lint \
+    golangci-lint cache status && \
     golangci-lint run --build-tags "$BUILD_TAGS" ./...
 
 FROM build-base AS test
@@ -93,11 +104,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
@@ -120,6 +133,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
@@ -155,12 +169,14 @@ 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
 
 FROM --platform=$BUILDPLATFORM alpine AS releaser
 WORKDIR /work
@@ -176,9 +192,3 @@ RUN --mount=from=binary \
 
 FROM scratch AS release
 COPY --from=releaser /out/ /
-
-# docs-reference is a target used as remote context to update docs on release
-# with latest changes on docs.docker.com.
-# see open-pr job in .github/workflows/docs.yml for more details
-FROM scratch AS docs-reference
-COPY docs/reference/*.yaml .

Makefile

@@ -15,25 +15,21 @@
 PKG := github.com/docker/compose/v2
 VERSION ?= $(shell git describe --match 'v[0-9]*' --dirty='.m' --always --tags)
 
-GO_LDFLAGS ?= -s -w -X ${PKG}/internal.Version=${VERSION}
+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 = -race -coverprofile=coverage.out -covermode=atomic
+BUILD_FLAGS?=
 TEST_FLAGS?=
 E2E_TEST?=
 ifeq ($(E2E_TEST),)
@@ -42,35 +38,45 @@ 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:
-	CGO_ENABLED=0 GO111MODULE=on go build -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:
 	$(BUILDX_CMD) bake binary
 
+.PHONY: binary-with-coverage
+binary-with-coverage:
+	$(BUILDX_CMD) bake 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
-	go test $(TEST_FLAGS) $(TEST_COVERAGE_FLAGS) -count=1 ./pkg/e2e
+	go test -v $(TEST_FLAGS) -count=1 ./pkg/e2e
 
 .PHONY: e2e-compose-standalone
 e2e-compose-standalone: ## Run End to end local tests in standalone mode. Set E2E_TEST=TestName to run a single test
 	go test $(TEST_FLAGS) -v -count=1 -parallel=1 --tags=standalone ./pkg/e2e
 
-.PHONY: test-cucumber
-test-cucumber:
-	go test $(TEST_FLAGS) -v -count=1 -parallel=1 ./e2e
-
 .PHONY: build-and-e2e-compose
 build-and-e2e-compose: build e2e-compose ## Compile the compose cli-plugin and run end to end local tests in plugin mode. Set E2E_TEST=TestName to run a single test
 
@@ -111,8 +117,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

@@ -1,18 +1,18 @@
 # Table of Contents
 - [Docker Compose v2](#docker-compose-v2)
-- [About update and backward compatibility](#about-update-and-backward-compatibility)
 - [Where to get Docker Compose](#where-to-get-docker-compose)
     + [Windows and macOS](#windows-and-macos)
     + [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 +23,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 +79,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,143 @@
+/*
+   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"
+	flag "github.com/spf13/pflag"
+	"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, args []string) 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), "-"),
+	)
+	cmdSpan.SetAttributes(attribute.StringSlice("cli.args", args))
+	cmdSpan.SetAttributes(attribute.StringSlice("cli.flags", getFlags(cmd.Flags())))
+
+	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
+}
+
+func getFlags(fs *flag.FlagSet) []string {
+	var result []string
+	fs.Visit(func(flag *flag.Flag) {
+		result = append(result, flag.Name)
+	})
+	return result
+}

cmd/cmdtrace/cmd_span_test.go

@@ -0,0 +1,64 @@
+/*
+   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 cmdtrace
+
+import (
+	"reflect"
+	"testing"
+
+	flag "github.com/spf13/pflag"
+)
+
+func TestGetFlags(t *testing.T) {
+	// Initialize flagSet with flags
+	fs := flag.NewFlagSet("up", flag.ContinueOnError)
+	var (
+		detach  string
+		timeout string
+	)
+	fs.StringVar(&detach, "detach", "d", "")
+	fs.StringVar(&timeout, "timeout", "t", "")
+	_ = fs.Set("detach", "detach")
+	_ = fs.Set("timeout", "timeout")
+
+	tests := []struct {
+		name     string
+		input    *flag.FlagSet
+		expected []string
+	}{
+		{
+			name:     "NoFlags",
+			input:    flag.NewFlagSet("NoFlags", flag.ContinueOnError),
+			expected: nil,
+		},
+		{
+			name:     "Flags",
+			input:    fs,
+			expected: []string{"detach", "timeout"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			result := getFlags(test.input)
+			if !reflect.DeepEqual(result, test.expected) {
+				t.Errorf("Expected %v, but got %v", test.expected, result)
+			}
+		})
+	}
+
+}

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,14 +15,13 @@
 package compose
 
 import (
-	"context"
-
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/spf13/cobra"
 )
 
 // alphaCommand groups all experimental subcommands
-func alphaCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func alphaCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	cmd := &cobra.Command{
 		Short:  "Experimental commands",
 		Use:    "alpha [COMMAND]",
@@ -32,26 +31,9 @@ func alphaCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		},
 	}
 	cmd.AddCommand(
-		watchCommand(p, backend),
-		dryRunRedirectCommand(p),
+		watchCommand(p, dockerCli, backend),
+		vizCommand(p, dockerCli, backend),
+		publishCommand(p, dockerCli, 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,9 @@ 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"
+	"github.com/docker/cli/cli/command"
+	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"
@@ -35,15 +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, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := buildOptions{
 		ProjectOptions: p,
 	}
@@ -83,39 +81,33 @@ 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 ...\n")
 			}
-			return runBuild(ctx, backend, opts, args)
+			return runBuild(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	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,21 +117,28 @@ 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(&p.Progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of ui output (%s)`, strings.Join(printerModes, ", ")))
+	cmd.Flags().MarkHidden("progress") //nolint:errcheck
 
 	return cmd
 }
 
-func runBuild(ctx context.Context, backend api.Service, opts buildOptions, services []string) error {
-	project, err := opts.ToProject(services, cli.WithResolvedPaths(true))
+func runBuild(ctx context.Context, dockerCli command.Cli, backend api.Service, opts buildOptions, services []string) error {
+	project, err := opts.ToProject(dockerCli, services, cli.WithResolvedPaths(true))
 	if err != nil {
 		return err
 	}
 
+	if err := applyPlatforms(project, false); err != nil {
+		return err
+	}
+
 	apiBuildOptions, err := opts.toAPIBuildOptions(services)
 	if err != nil {
 		return err
 	}
+
+	apiBuildOptions.Memory = int64(opts.memory)
 	return backend.Build(ctx, project, apiBuildOptions)
 }

cmd/compose/completion.go

@@ -17,8 +17,10 @@
 package compose
 
 import (
+	"sort"
 	"strings"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/spf13/cobra"
 )
@@ -32,9 +34,10 @@ func noCompletion() validArgsFn {
 	}
 }
 
-func completeServiceNames(p *ProjectOptions) validArgsFn {
+func completeServiceNames(dockerCli command.Cli, p *ProjectOptions) validArgsFn {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-		project, err := p.ToProject(nil)
+		p.Offline = true
+		project, err := p.ToProject(dockerCli, nil)
 		if err != nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
@@ -65,3 +68,24 @@ func completeProjectNames(backend api.Service) func(cmd *cobra.Command, args []s
 		return values, cobra.ShellCompDirectiveNoFileComp
 	}
 }
+
+func completeProfileNames(dockerCli command.Cli, p *ProjectOptions) validArgsFn {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		p.Offline = true
+		project, err := p.ToProject(dockerCli, 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

@@ -18,6 +18,7 @@ package compose
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"os/signal"
@@ -26,16 +27,17 @@ import (
 	"strings"
 	"syscall"
 
-	"github.com/docker/cli/cli/command"
-
 	"github.com/compose-spec/compose-go/cli"
+	"github.com/compose-spec/compose-go/dotenv"
 	"github.com/compose-spec/compose-go/types"
 	composegoutils "github.com/compose-spec/compose-go/utils"
 	"github.com/docker/buildx/util/logutil"
+	buildx "github.com/docker/buildx/util/progress"
 	dockercli "github.com/docker/cli/cli"
 	"github.com/docker/cli/cli-plugins/manager"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/compose/v2/pkg/remote"
 	"github.com/morikuni/aec"
-	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -43,10 +45,25 @@ 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"
+	// ComposeEnvFiles defines the env files to use if --env-file isn't used
+	ComposeEnvFiles = "COMPOSE_ENV_FILES"
+)
+
 // Command defines a compose CLI command as a func with args
 type Command func(context.Context, []string) error
 
@@ -66,6 +83,8 @@ func AdaptCmd(fn CobraCommand) func(cmd *cobra.Command, args []string) error {
 			go func() {
 				<-s
 				cancel()
+				signal.Stop(s)
+				close(s)
 			}()
 		}
 		err := fn(ctx, cmd, args)
@@ -99,8 +118,10 @@ type ProjectOptions struct {
 	ConfigPaths   []string
 	WorkDir       string
 	ProjectDir    string
-	EnvFile       string
+	EnvFiles      []string
 	Compatibility bool
+	Progress      string
+	Offline       bool
 }
 
 // ProjectFunc does stuff within a types.Project
@@ -110,16 +131,22 @@ type ProjectFunc func(ctx context.Context, project *types.Project) error
 type ProjectServicesFunc func(ctx context.Context, project *types.Project, services []string) error
 
 // WithProject creates a cobra run command from a ProjectFunc based on configured project options and selected services
-func (o *ProjectOptions) WithProject(fn ProjectFunc) func(cmd *cobra.Command, args []string) error {
-	return o.WithServices(func(ctx context.Context, project *types.Project, services []string) error {
+func (o *ProjectOptions) WithProject(fn ProjectFunc, dockerCli command.Cli) func(cmd *cobra.Command, args []string) error {
+	return o.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
 		return fn(ctx, project)
 	})
 }
 
 // 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 {
+func (o *ProjectOptions) WithServices(dockerCli command.Cli, 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))
+		options := []cli.ProjectOptionsFn{
+			cli.WithResolvedPaths(true),
+			cli.WithDiscardEnvFile,
+			cli.WithContext(ctx),
+		}
+
+		project, err := o.ToProject(dockerCli, args, options...)
 		if err != nil {
 			return err
 		}
@@ -132,20 +159,21 @@ func (o *ProjectOptions) addProjectFlags(f *pflag.FlagSet) {
 	f.StringArrayVar(&o.Profiles, "profile", []string{}, "Specify a profile to enable")
 	f.StringVarP(&o.ProjectName, "project-name", "p", "", "Project name")
 	f.StringArrayVarP(&o.ConfigPaths, "file", "f", []string{}, "Compose configuration files")
-	f.StringVar(&o.EnvFile, "env-file", "", "Specify an alternate environment file.")
+	f.StringArrayVar(&o.EnvFiles, "env-file", nil, "Specify an alternate environment file.")
 	f.StringVar(&o.ProjectDir, "project-directory", "", "Specify an alternate working directory\n(default: the path of the, first specified, Compose file)")
 	f.StringVar(&o.WorkDir, "workdir", "", "DEPRECATED! USE --project-directory INSTEAD.\nSpecify an alternate working directory\n(default: the path of the, first specified, Compose file)")
 	f.BoolVar(&o.Compatibility, "compatibility", false, "Run compose in backward compatibility mode")
+	f.StringVar(&o.Progress, "progress", buildx.PrinterModeAuto, fmt.Sprintf(`Set type of progress output (%s)`, strings.Join(printerModes, ", ")))
 	_ = f.MarkHidden("workdir")
 }
 
-func (o *ProjectOptions) projectOrName(services ...string) (*types.Project, string, error) {
+func (o *ProjectOptions) projectOrName(dockerCli command.Cli, services ...string) (*types.Project, string, error) {
 	name := o.ProjectName
 	var project *types.Project
 	if len(o.ConfigPaths) > 0 || o.ProjectName == "" {
-		p, err := o.ToProject(services)
+		p, err := o.ToProject(dockerCli, services, cli.WithDiscardEnvFile)
 		if err != nil {
-			envProjectName := os.Getenv("COMPOSE_PROJECT_NAME")
+			envProjectName := os.Getenv(ComposeProjectName)
 			if envProjectName != "" {
 				return nil, envProjectName, nil
 			}
@@ -157,30 +185,34 @@ func (o *ProjectOptions) projectOrName(services ...string) (*types.Project, stri
 	return project, name, nil
 }
 
-func (o *ProjectOptions) toProjectName() (string, error) {
+func (o *ProjectOptions) toProjectName(dockerCli command.Cli) (string, error) {
 	if o.ProjectName != "" {
 		return o.ProjectName, nil
 	}
 
-	envProjectName := os.Getenv("COMPOSE_PROJECT_NAME")
+	envProjectName := os.Getenv(ComposeProjectName)
 	if envProjectName != "" {
 		return envProjectName, nil
 	}
 
-	project, err := o.ToProject(nil)
+	project, err := o.ToProject(dockerCli, nil)
 	if err != nil {
 		return "", err
 	}
 	return project.Name, nil
 }
 
-func (o *ProjectOptions) ToProject(services []string, po ...cli.ProjectOptionsFn) (*types.Project, error) {
+func (o *ProjectOptions) ToProject(dockerCli command.Cli, services []string, po ...cli.ProjectOptionsFn) (*types.Project, error) {
+	if !o.Offline {
+		po = o.configureRemoteLoaders(dockerCli, po)
+	}
+
 	options, err := o.toProjectOptions(po...)
 	if err != nil {
 		return nil, compose.WrapComposeError(err)
 	}
 
-	if o.Compatibility || utils.StringToBool(options.Environment["COMPOSE_COMPATIBILITY"]) {
+	if o.Compatibility || utils.StringToBool(options.Environment[ComposeCompatibility]) {
 		api.Separator = "_"
 	}
 
@@ -189,6 +221,15 @@ func (o *ProjectOptions) ToProject(services []string, po ...cli.ProjectOptionsFn
 		return nil, compose.WrapComposeError(err)
 	}
 
+	if project.Name == "" {
+		return nil, errors.New("project name can't be empty. Use `--project-name` to set a valid name")
+	}
+
+	err = project.EnableServices(services...)
+	if err != nil {
+		return nil, err
+	}
+
 	for i, s := range project.Services {
 		s.CustomLabels = map[string]string{
 			api.ProjectLabel:     project.Name,
@@ -198,41 +239,36 @@ func (o *ProjectOptions) ToProject(services []string, po ...cli.ProjectOptionsFn
 			api.ConfigFilesLabel: strings.Join(project.ComposeFiles, ","),
 			api.OneoffLabel:      "False", // default, will be overridden by `run` command
 		}
-		if o.EnvFile != "" {
-			s.CustomLabels[api.EnvironmentFileLabel] = o.EnvFile
+		if len(o.EnvFiles) != 0 {
+			s.CustomLabels[api.EnvironmentFileLabel] = strings.Join(o.EnvFiles, ",")
 		}
 		project.Services[i] = s
 	}
 
-	if profiles, ok := options.Environment["COMPOSE_PROFILES"]; ok && len(o.Profiles) == 0 {
-		o.Profiles = append(o.Profiles, strings.Split(profiles, ",")...)
-	}
-
-	if len(services) > 0 {
-		s, err := project.GetServices(services...)
-		if err != nil {
-			return nil, err
-		}
-		o.Profiles = append(o.Profiles, s.GetProfiles()...)
-	}
-
-	project.ApplyProfiles(o.Profiles)
-
 	project.WithoutUnnecessaryResources()
 
 	err = project.ForServices(services)
 	return project, err
 }
 
+func (o *ProjectOptions) configureRemoteLoaders(dockerCli command.Cli, po []cli.ProjectOptionsFn) []cli.ProjectOptionsFn {
+	git := remote.NewGitRemoteLoader(o.Offline)
+	oci := remote.NewOCIRemoteLoader(dockerCli, o.Offline)
+
+	po = append(po, cli.WithResourceLoader(git), cli.WithResourceLoader(oci))
+	return po
+}
+
 func (o *ProjectOptions) toProjectOptions(po ...cli.ProjectOptionsFn) (*cli.ProjectOptions, error) {
 	return cli.NewProjectOptions(o.ConfigPaths,
 		append(po,
 			cli.WithWorkingDirectory(o.ProjectDir),
 			cli.WithOsEnv,
-			cli.WithEnvFile(o.EnvFile),
+			cli.WithEnvFiles(o.EnvFiles...),
 			cli.WithDotEnv,
 			cli.WithConfigFileEnv,
 			cli.WithDefaultConfigPath,
+			cli.WithDefaultProfiles(o.Profiles...),
 			cli.WithName(o.ProjectName))...)
 }
 
@@ -245,7 +281,7 @@ func RunningAsStandalone() bool {
 }
 
 // RootCommand returns the compose command with its child commands
-func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //nolint:gocyclo
+func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //nolint:gocyclo
 	// filter out useless commandConn.CloseWrite warning message that can occur
 	// when using a remote context that is unreachable: "commandConn.CloseWrite: commandconn: failed to wait: signal: killed"
 	// https://github.com/docker/cli/blob/e1f24d3c93df6752d3c27c8d61d18260f141310c/cli/connhelper/commandconn/commandconn.go#L203-L215
@@ -267,6 +303,7 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 	)
 	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) !
@@ -275,7 +312,7 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 				return cmd.Help()
 			}
 			if version {
-				return versionCommand().Execute()
+				return versionCommand(dockerCli).Execute()
 			}
 			_ = cmd.Help()
 			return dockercli.StatusError{
@@ -308,13 +345,44 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 			if verbose {
 				logrus.SetLevel(logrus.TraceLevel)
 			}
-			formatter.SetANSIMode(streams, ansi)
+
+			if v, ok := os.LookupEnv("COMPOSE_ANSI"); ok && !cmd.Flags().Changed("ansi") {
+				ansi = v
+			}
+
+			formatter.SetANSIMode(dockerCli, ansi)
+
+			if noColor, ok := os.LookupEnv("NO_COLOR"); ok && noColor != "" {
+				ui.NoColor()
+				formatter.SetANSIMode(dockerCli, 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 opts.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", opts.Progress)
+			}
+
 			if opts.WorkDir != "" {
 				if opts.ProjectDir != "" {
 					return errors.New(`cannot specify DEPRECATED "--workdir" and "--project-directory". Please use only "--project-directory" instead`)
@@ -322,16 +390,31 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 				opts.ProjectDir = opts.WorkDir
 				fmt.Fprint(os.Stderr, aec.Apply("option '--workdir' is DEPRECATED at root level! Please use '--project-directory' instead.\n", aec.RedF))
 			}
-			if opts.EnvFile != "" && !filepath.IsAbs(opts.EnvFile) {
-				opts.EnvFile, err = filepath.Abs(opts.EnvFile)
-				if err != nil {
-					return err
+			for i, file := range opts.EnvFiles {
+				if !filepath.IsAbs(file) {
+					file, err = filepath.Abs(file)
+					if err != nil {
+						return err
+					}
+					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
 			}
@@ -348,32 +431,35 @@ func RootCommand(streams command.Cli, backend api.Service) *cobra.Command { //no
 	}
 
 	c.AddCommand(
-		upCommand(&opts, streams, backend),
-		downCommand(&opts, backend),
-		startCommand(&opts, backend),
-		restartCommand(&opts, backend),
-		stopCommand(&opts, backend),
-		psCommand(&opts, streams, backend),
-		listCommand(streams, backend),
-		logsCommand(&opts, streams, backend),
-		convertCommand(&opts, streams, backend),
-		killCommand(&opts, backend),
-		runCommand(&opts, streams, backend),
-		removeCommand(&opts, backend),
-		execCommand(&opts, streams, backend),
-		pauseCommand(&opts, backend),
-		unpauseCommand(&opts, backend),
-		topCommand(&opts, streams, backend),
-		eventsCommand(&opts, streams, backend),
-		portCommand(&opts, streams, backend),
-		imagesCommand(&opts, streams, backend),
-		versionCommand(),
-		buildCommand(&opts, streams, backend),
-		pushCommand(&opts, backend),
-		pullCommand(&opts, backend),
-		createCommand(&opts, backend),
-		copyCommand(&opts, backend),
-		alphaCommand(&opts, backend),
+		upCommand(&opts, dockerCli, backend),
+		downCommand(&opts, dockerCli, backend),
+		startCommand(&opts, dockerCli, backend),
+		restartCommand(&opts, dockerCli, backend),
+		stopCommand(&opts, dockerCli, backend),
+		psCommand(&opts, dockerCli, backend),
+		listCommand(dockerCli, backend),
+		logsCommand(&opts, dockerCli, backend),
+		configCommand(&opts, dockerCli, backend),
+		killCommand(&opts, dockerCli, backend),
+		runCommand(&opts, dockerCli, backend),
+		removeCommand(&opts, dockerCli, backend),
+		execCommand(&opts, dockerCli, backend),
+		pauseCommand(&opts, dockerCli, backend),
+		unpauseCommand(&opts, dockerCli, backend),
+		topCommand(&opts, dockerCli, backend),
+		eventsCommand(&opts, dockerCli, backend),
+		portCommand(&opts, dockerCli, backend),
+		imagesCommand(&opts, dockerCli, backend),
+		versionCommand(dockerCli),
+		buildCommand(&opts, dockerCli, backend),
+		pushCommand(&opts, dockerCli, backend),
+		pullCommand(&opts, dockerCli, backend),
+		createCommand(&opts, dockerCli, backend),
+		copyCommand(&opts, dockerCli, backend),
+		waitCommand(&opts, dockerCli, backend),
+		scaleCommand(&opts, dockerCli, backend),
+		watchCommand(&opts, dockerCli, backend),
+		alphaCommand(&opts, dockerCli, backend),
 	)
 
 	c.Flags().SetInterspersed(false)
@@ -382,27 +468,41 @@ 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(dockerCli, &opts),
+	)
 
 	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
 }
 
 func setEnvWithDotEnv(prjOpts *ProjectOptions) error {
+	if len(prjOpts.EnvFiles) == 0 {
+		if envFiles := os.Getenv(ComposeEnvFiles); envFiles != "" {
+			prjOpts.EnvFiles = strings.Split(envFiles, ",")
+		}
+	}
 	options, err := prjOpts.toProjectOptions()
 	if err != nil {
 		return compose.WrapComposeError(err)
@@ -412,7 +512,7 @@ func setEnvWithDotEnv(prjOpts *ProjectOptions) error {
 		return err
 	}
 
-	envFromFile, err := cli.GetEnvFromFile(composegoutils.GetAsEqualsMap(os.Environ()), workingDir, options.EnvFile)
+	envFromFile, err := dotenv.GetEnvFromFile(composegoutils.GetAsEqualsMap(os.Environ()), workingDir, options.EnvFiles)
 	if err != nil {
 		return err
 	}
@@ -425,3 +525,10 @@ func setEnvWithDotEnv(prjOpts *ProjectOptions) error {
 	}
 	return nil
 }
+
+var printerModes = []string{
+	ui.ModeAuto,
+	ui.ModeTTY,
+	ui.ModePlain,
+	ui.ModeQuiet,
+}

cmd/compose/compose_test.go

@@ -31,8 +31,10 @@ func TestFilterServices(t *testing.T) {
 				Links: []string{"bar"},
 			},
 			{
-				Name:        "bar",
-				NetworkMode: types.NetworkModeServicePrefix + "zot",
+				Name: "bar",
+				DependsOn: map[string]types.ServiceDependency{
+					"zot": {},
+				},
 			},
 			{
 				Name: "zot",

cmd/compose/config.go

@@ -26,13 +26,14 @@ import (
 
 	"github.com/compose-spec/compose-go/cli"
 	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/docker/compose/v2/pkg/compose"
 )
 
-type convertOptions struct {
+type configOptions struct {
 	*ProjectOptions
 	Format              string
 	Output              string
@@ -40,6 +41,7 @@ type convertOptions struct {
 	resolveImageDigests bool
 	noInterpolate       bool
 	noNormalize         bool
+	noResolvePath       bool
 	services            bool
 	volumes             bool
 	profiles            bool
@@ -48,8 +50,20 @@ type convertOptions struct {
 	noConsistency       bool
 }
 
-func convertCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
-	opts := convertOptions{
+func (o *configOptions) ToProject(ctx context.Context, dockerCli command.Cli, services []string, po ...cli.ProjectOptionsFn) (*types.Project, error) {
+	po = append(po,
+		cli.WithInterpolation(!o.noInterpolate),
+		cli.WithResolvedPaths(!o.noResolvePath),
+		cli.WithNormalization(!o.noNormalize),
+		cli.WithConsistency(!o.noConsistency),
+		cli.WithDefaultProfiles(o.Profiles...),
+		cli.WithDiscardEnvFile,
+		cli.WithContext(ctx))
+	return o.ProjectOptions.ToProject(dockerCli, services, po...)
+}
+
+func configCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
+	opts := configOptions{
 		ProjectOptions: p,
 	}
 	cmd := &cobra.Command{
@@ -71,24 +85,24 @@ func convertCommand(p *ProjectOptions, streams api.Streams, backend api.Service)
 		}),
 		RunE: Adapt(func(ctx context.Context, args []string) error {
 			if opts.services {
-				return runServices(streams, opts)
+				return runServices(ctx, dockerCli, opts)
 			}
 			if opts.volumes {
-				return runVolumes(streams, opts)
+				return runVolumes(ctx, dockerCli, opts)
 			}
 			if opts.hash != "" {
-				return runHash(streams, opts)
+				return runHash(ctx, dockerCli, opts)
 			}
 			if opts.profiles {
-				return runProfiles(streams, opts, args)
+				return runProfiles(ctx, dockerCli, opts, args)
 			}
 			if opts.images {
-				return runConfigImages(streams, opts, args)
+				return runConfigImages(ctx, dockerCli, opts, args)
 			}
 
-			return runConfig(ctx, streams, backend, opts, args)
+			return runConfig(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	flags := cmd.Flags()
 	flags.StringVar(&opts.Format, "format", "yaml", "Format the output. Values: [yaml | json]")
@@ -96,6 +110,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.")
@@ -108,14 +123,9 @@ func convertCommand(p *ProjectOptions, streams api.Streams, backend api.Service)
 	return cmd
 }
 
-func runConfig(ctx context.Context, streams api.Streams, backend api.Service, opts convertOptions, services []string) error {
+func runConfig(ctx context.Context, dockerCli command.Cli, backend api.Service, opts configOptions, services []string) error {
 	var content []byte
-	project, err := opts.ToProject(services,
-		cli.WithInterpolation(!opts.noInterpolate),
-		cli.WithResolvedPaths(true),
-		cli.WithNormalization(!opts.noNormalize),
-		cli.WithConsistency(!opts.noConsistency),
-		cli.WithDiscardEnvFile)
+	project, err := opts.ToProject(ctx, dockerCli, services)
 	if err != nil {
 		return err
 	}
@@ -140,54 +150,74 @@ func runConfig(ctx context.Context, streams api.Streams, backend api.Service, op
 	if opts.Output != "" && len(content) > 0 {
 		return os.WriteFile(opts.Output, content, 0o666)
 	}
-	_, err = fmt.Fprint(streams.Out(), string(content))
+	_, err = fmt.Fprint(dockerCli.Out(), string(content))
 	return err
 }
 
-func runServices(streams api.Streams, opts convertOptions) error {
-	project, err := opts.ToProject(nil)
+func runServices(ctx context.Context, dockerCli command.Cli, opts configOptions) error {
+	project, err := opts.ToProject(ctx, dockerCli, nil, cli.WithoutEnvironmentResolution)
 	if err != nil {
 		return err
 	}
 	return project.WithServices(project.ServiceNames(), func(s types.ServiceConfig) error {
-		fmt.Fprintln(streams.Out(), s.Name)
+		fmt.Fprintln(dockerCli.Out(), s.Name)
 		return nil
 	})
 }
 
-func runVolumes(streams api.Streams, opts convertOptions) error {
-	project, err := opts.ToProject(nil)
+func runVolumes(ctx context.Context, dockerCli command.Cli, opts configOptions) error {
+	project, err := opts.ToProject(ctx, dockerCli, nil, cli.WithoutEnvironmentResolution)
 	if err != nil {
 		return err
 	}
 	for n := range project.Volumes {
-		fmt.Fprintln(streams.Out(), n)
+		fmt.Fprintln(dockerCli.Out(), n)
 	}
 	return nil
 }
 
-func runHash(streams api.Streams, opts convertOptions) error {
+func runHash(ctx context.Context, dockerCli command.Cli, opts configOptions) error {
 	var services []string
 	if opts.hash != "*" {
 		services = append(services, strings.Split(opts.hash, ",")...)
 	}
-	project, err := opts.ToProject(services)
+	project, err := opts.ToProject(ctx, dockerCli, nil, cli.WithoutEnvironmentResolution)
 	if err != nil {
 		return err
 	}
-	for _, s := range project.Services {
-		hash, err := compose.ServiceHash(s)
+
+	if err := applyPlatforms(project, true); err != nil {
+		return err
+	}
+
+	if len(services) == 0 {
+		services = project.ServiceNames()
+	}
+
+	sorted := services
+	sort.Slice(sorted, func(i, j int) bool {
+		return sorted[i] < sorted[j]
+	})
+
+	for _, name := range sorted {
+		s, err := project.GetService(name)
 		if err != nil {
 			return err
 		}
-		fmt.Fprintf(streams.Out(), "%s %s\n", s.Name, hash)
+
+		hash, err := compose.ServiceHash(s)
+
+		if err != nil {
+			return err
+		}
+		fmt.Fprintf(dockerCli.Out(), "%s %s\n", s.Name, hash)
 	}
 	return nil
 }
 
-func runProfiles(streams api.Streams, opts convertOptions, services []string) error {
+func runProfiles(ctx context.Context, dockerCli command.Cli, opts configOptions, services []string) error {
 	set := map[string]struct{}{}
-	project, err := opts.ToProject(services)
+	project, err := opts.ToProject(ctx, dockerCli, services, cli.WithoutEnvironmentResolution)
 	if err != nil {
 		return err
 	}
@@ -202,22 +232,18 @@ func runProfiles(streams api.Streams, opts convertOptions, services []string) er
 	}
 	sort.Strings(profiles)
 	for _, p := range profiles {
-		fmt.Fprintln(streams.Out(), p)
+		fmt.Fprintln(dockerCli.Out(), p)
 	}
 	return nil
 }
 
-func runConfigImages(streams api.Streams, opts convertOptions, services []string) error {
-	project, err := opts.ToProject(services)
+func runConfigImages(ctx context.Context, dockerCli command.Cli, opts configOptions, services []string) error {
+	project, err := opts.ToProject(ctx, dockerCli, services, cli.WithoutEnvironmentResolution)
 	if err != nil {
 		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(dockerCli.Out(), api.GetImageNameOrDefault(s, project.Name))
 	}
 	return nil
 }

cmd/compose/cp.go

@@ -21,6 +21,7 @@ import (
 	"errors"
 
 	"github.com/docker/cli/cli"
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -37,7 +38,7 @@ type copyOptions struct {
 	copyUIDGID  bool
 }
 
-func copyCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func copyCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := copyOptions{
 		ProjectOptions: p,
 	}
@@ -58,24 +59,24 @@ func copyCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		RunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
 			opts.source = args[0]
 			opts.destination = args[1]
-			return runCopy(ctx, backend, opts)
+			return runCopy(ctx, dockerCli, backend, opts)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 
 	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)")
 
 	return copyCmd
 }
 
-func runCopy(ctx context.Context, backend api.Service, opts copyOptions) error {
-	name, err := opts.toProjectName()
+func runCopy(ctx context.Context, dockerCli command.Cli, backend api.Service, opts copyOptions) error {
+	name, err := opts.toProjectName(dockerCli)
 	if err != nil {
 		return err
 	}

cmd/compose/create.go

@@ -19,11 +19,13 @@ package compose
 import (
 	"context"
 	"fmt"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
 
 	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -46,8 +48,11 @@ type createOptions struct {
 	scale         []string
 }
 
-func createCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func createCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := createOptions{}
+	buildOpts := buildOptions{
+		ProjectOptions: p,
+	}
 	cmd := &cobra.Command{
 		Use:   "create [OPTIONS] [SERVICE...]",
 		Short: "Creates containers for a service.",
@@ -61,26 +66,15 @@ func createCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 			}
 			return nil
 		}),
-		RunE: p.WithProject(func(ctx context.Context, project *types.Project) error {
-			if err := opts.Apply(project); err != nil {
-				return err
-			}
-			return backend.Create(ctx, project, api.CreateOptions{
-				RemoveOrphans:        opts.removeOrphans,
-				IgnoreOrphans:        opts.ignoreOrphans,
-				Recreate:             opts.recreateStrategy(),
-				RecreateDependencies: opts.dependenciesRecreateStrategy(),
-				Inherit:              !opts.noInherit,
-				Timeout:              opts.GetTimeout(),
-				QuietPull:            false,
-			})
+		RunE: p.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
+			return runCreate(ctx, dockerCli, backend, opts, buildOpts, project, services)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	flags := cmd.Flags()
 	flags.BoolVar(&opts.Build, "build", false, "Build images before starting containers.")
-	flags.BoolVar(&opts.noBuild, "no-build", false, "Don't build an image, even if it's missing.")
-	flags.StringVar(&opts.Pull, "pull", "missing", `Pull image before running ("always"|"missing"|"never")`)
+	flags.BoolVar(&opts.noBuild, "no-build", false, "Don't build an image, even if it's policy.")
+	flags.StringVar(&opts.Pull, "pull", "policy", `Pull image before running ("always"|"missing"|"never"|"build")`)
 	flags.BoolVar(&opts.forceRecreate, "force-recreate", false, "Recreate containers even if their configuration and image haven't changed.")
 	flags.BoolVar(&opts.noRecreate, "no-recreate", false, "If containers already exist, don't recreate them. Incompatible with --force-recreate.")
 	flags.BoolVar(&opts.removeOrphans, "remove-orphans", false, "Remove containers for services not defined in the Compose file.")
@@ -88,6 +82,33 @@ func createCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	return cmd
 }
 
+func runCreate(ctx context.Context, _ command.Cli, backend api.Service, createOpts createOptions, buildOpts buildOptions, project *types.Project, services []string) error {
+	if err := createOpts.Apply(project); err != nil {
+		return err
+	}
+
+	var build *api.BuildOptions
+	if !createOpts.noBuild {
+		bo, err := buildOpts.toAPIBuildOptions(services)
+		if err != nil {
+			return err
+		}
+		build = &bo
+	}
+
+	return backend.Create(ctx, project, api.CreateOptions{
+		Build:                build,
+		Services:             services,
+		RemoveOrphans:        createOpts.removeOrphans,
+		IgnoreOrphans:        createOpts.ignoreOrphans,
+		Recreate:             createOpts.recreateStrategy(),
+		RecreateDependencies: createOpts.dependenciesRecreateStrategy(),
+		Inherit:              !createOpts.noInherit,
+		Timeout:              createOpts.GetTimeout(),
+		QuietPull:            false,
+	})
+}
+
 func (opts createOptions) recreateStrategy() string {
 	if opts.noRecreate {
 		return api.RecreateNever
@@ -118,11 +139,17 @@ func (opts createOptions) GetTimeout() *time.Duration {
 
 func (opts createOptions) Apply(project *types.Project) error {
 	if opts.pullChanged {
+		if !opts.isPullPolicyValid() {
+			return fmt.Errorf("invalid --pull option %q", opts.Pull)
+		}
 		for i, service := range project.Services {
 			service.PullPolicy = opts.Pull
 			project.Services[i] = service
 		}
 	}
+	// N.B. opts.Build means "force build all", but images can still be built
+	// when this is false
+	// e.g. if a service has pull_policy: build or its local image is policy
 	if opts.Build {
 		for i, service := range project.Services {
 			if service.Build == nil {
@@ -132,6 +159,7 @@ func (opts createOptions) Apply(project *types.Project) error {
 			project.Services[i] = service
 		}
 	}
+	// opts.noBuild, however, means do not perform ANY builds
 	if opts.noBuild {
 		for i, service := range project.Services {
 			service.Build = nil
@@ -141,6 +169,11 @@ func (opts createOptions) Apply(project *types.Project) error {
 			project.Services[i] = service
 		}
 	}
+
+	if err := applyPlatforms(project, true); err != nil {
+		return err
+	}
+
 	for _, scale := range opts.scale {
 		split := strings.Split(scale, "=")
 		if len(split) != 2 {
@@ -158,3 +191,9 @@ func (opts createOptions) Apply(project *types.Project) error {
 	}
 	return nil
 }
+
+func (opts createOptions) isPullPolicyValid() bool {
+	pullPolicies := []string{types.PullPolicyAlways, types.PullPolicyNever, types.PullPolicyBuild,
+		types.PullPolicyMissing, types.PullPolicyIfNotPresent}
+	return slices.Contains(pullPolicies, opts.Pull)
+}

cmd/compose/create_test.go

@@ -0,0 +1,170 @@
+/*
+   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"
+	"testing"
+
+	"github.com/compose-spec/compose-go/types"
+	"github.com/davecgh/go-spew/spew"
+	"github.com/docker/compose/v2/pkg/api"
+	"github.com/docker/compose/v2/pkg/mocks"
+	"github.com/golang/mock/gomock"
+	"github.com/google/go-cmp/cmp"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRunCreate(t *testing.T) {
+	ctrl, ctx := gomock.WithContext(context.Background(), t)
+	backend := mocks.NewMockService(ctrl)
+	backend.EXPECT().Create(
+		gomock.Eq(ctx),
+		pullPolicy(""),
+		deepEqual(defaultCreateOptions(true)),
+	)
+
+	createOpts := createOptions{}
+	buildOpts := buildOptions{}
+	project := sampleProject()
+	err := runCreate(ctx, nil, backend, createOpts, buildOpts, project, nil)
+	require.NoError(t, err)
+}
+
+func TestRunCreate_Build(t *testing.T) {
+	ctrl, ctx := gomock.WithContext(context.Background(), t)
+	backend := mocks.NewMockService(ctrl)
+	backend.EXPECT().Create(
+		gomock.Eq(ctx),
+		pullPolicy("build"),
+		deepEqual(defaultCreateOptions(true)),
+	)
+
+	createOpts := createOptions{
+		Build: true,
+	}
+	buildOpts := buildOptions{}
+	project := sampleProject()
+	err := runCreate(ctx, nil, backend, createOpts, buildOpts, project, nil)
+	require.NoError(t, err)
+}
+
+func TestRunCreate_NoBuild(t *testing.T) {
+	ctrl, ctx := gomock.WithContext(context.Background(), t)
+	backend := mocks.NewMockService(ctrl)
+	backend.EXPECT().Create(
+		gomock.Eq(ctx),
+		pullPolicy(""),
+		deepEqual(defaultCreateOptions(false)),
+	)
+
+	createOpts := createOptions{
+		noBuild: true,
+	}
+	buildOpts := buildOptions{}
+	project := sampleProject()
+	err := runCreate(ctx, nil, backend, createOpts, buildOpts, project, nil)
+	require.NoError(t, err)
+}
+
+func sampleProject() *types.Project {
+	return &types.Project{
+		Name: "test",
+		Services: types.Services{
+			{
+				Name: "svc",
+				Build: &types.BuildConfig{
+					Context: ".",
+				},
+			},
+		},
+	}
+}
+
+func defaultCreateOptions(includeBuild bool) api.CreateOptions {
+	var build *api.BuildOptions
+	if includeBuild {
+		bo := defaultBuildOptions()
+		build = &bo
+	}
+	return api.CreateOptions{
+		Build:                build,
+		Services:             nil,
+		RemoveOrphans:        false,
+		IgnoreOrphans:        false,
+		Recreate:             "diverged",
+		RecreateDependencies: "diverged",
+		Inherit:              true,
+		Timeout:              nil,
+		QuietPull:            false,
+	}
+}
+
+func defaultBuildOptions() api.BuildOptions {
+	return api.BuildOptions{
+		Args:     make(types.MappingWithEquals),
+		Progress: "auto",
+	}
+}
+
+// deepEqual returns a nice diff on failure vs gomock.Eq when used
+// on structs.
+func deepEqual(x interface{}) gomock.Matcher {
+	return gomock.GotFormatterAdapter(
+		gomock.GotFormatterFunc(func(got interface{}) string {
+			return cmp.Diff(x, got)
+		}),
+		gomock.Eq(x),
+	)
+}
+
+func spewAdapter(m gomock.Matcher) gomock.Matcher {
+	return gomock.GotFormatterAdapter(
+		gomock.GotFormatterFunc(func(got interface{}) string {
+			return spew.Sdump(got)
+		}),
+		m,
+	)
+}
+
+type withPullPolicy struct {
+	policy string
+}
+
+func pullPolicy(policy string) gomock.Matcher {
+	return spewAdapter(withPullPolicy{policy: policy})
+}
+
+func (w withPullPolicy) Matches(x interface{}) bool {
+	proj, ok := x.(*types.Project)
+	if !ok || proj == nil || len(proj.Services) == 0 {
+		return false
+	}
+
+	for _, svc := range proj.Services {
+		if svc.PullPolicy != w.policy {
+			return false
+		}
+	}
+
+	return true
+}
+
+func (w withPullPolicy) String() string {
+	return fmt.Sprintf("has pull policy %q for all services", w.policy)
+}

cmd/compose/down.go

@@ -22,6 +22,7 @@ import (
 	"os"
 	"time"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/utils"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
@@ -39,12 +40,12 @@ type downOptions struct {
 	images        string
 }
 
-func downCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func downCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := downOptions{
 		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 +57,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, dockerCli, 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,8 +77,8 @@ func downCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	return downCmd
 }
 
-func runDown(ctx context.Context, backend api.Service, opts downOptions) error {
-	project, name, err := opts.projectOrName()
+func runDown(ctx context.Context, dockerCli command.Cli, backend api.Service, opts downOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}
@@ -94,5 +94,6 @@ func runDown(ctx context.Context, backend api.Service, opts downOptions) error {
 		Timeout:       timeout,
 		Images:        opts.images,
 		Volumes:       opts.volumes,
+		Services:      services,
 	})
 }

cmd/compose/events.go

@@ -21,6 +21,7 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 
 	"github.com/spf13/cobra"
@@ -31,7 +32,7 @@ type eventsOpts struct {
 	json bool
 }
 
-func eventsCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func eventsCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := eventsOpts{
 		composeOptions: &composeOptions{
 			ProjectOptions: p,
@@ -41,17 +42,17 @@ func eventsCommand(p *ProjectOptions, streams api.Streams, backend api.Service)
 		Use:   "events [OPTIONS] [SERVICE...]",
 		Short: "Receive real time events from containers.",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runEvents(ctx, streams, backend, opts, args)
+			return runEvents(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 
 	cmd.Flags().BoolVar(&opts.json, "json", false, "Output events as a stream of json objects")
 	return cmd
 }
 
-func runEvents(ctx context.Context, streams api.Streams, backend api.Service, opts eventsOpts, services []string) error {
-	name, err := opts.toProjectName()
+func runEvents(ctx context.Context, dockerCli command.Cli, backend api.Service, opts eventsOpts, services []string) error {
+	name, err := opts.toProjectName(dockerCli)
 	if err != nil {
 		return err
 	}
@@ -71,9 +72,9 @@ func runEvents(ctx context.Context, streams api.Streams, backend api.Service, op
 				if err != nil {
 					return err
 				}
-				fmt.Fprintln(streams.Out(), string(marshal))
+				fmt.Fprintln(dockerCli.Out(), string(marshal))
 			} else {
-				fmt.Fprintln(streams.Out(), event)
+				fmt.Fprintln(dockerCli.Out(), event)
 			}
 			return nil
 		},

cmd/compose/exec.go

@@ -21,6 +21,7 @@ import (
 
 	"github.com/compose-spec/compose-go/types"
 	"github.com/docker/cli/cli"
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/docker/compose/v2/pkg/compose"
 	"github.com/spf13/cobra"
@@ -42,7 +43,7 @@ type execOpts struct {
 	interactive bool
 }
 
-func execCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func execCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := execOpts{
 		composeOptions: &composeOptions{
 			ProjectOptions: p,
@@ -58,17 +59,17 @@ func execCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 			return nil
 		}),
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runExec(ctx, backend, opts)
+			return runExec(ctx, dockerCli, backend, opts)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 
 	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.")
+	runCmd.Flags().BoolVarP(&opts.noTty, "no-TTY", "T", !dockerCli.Out().IsTerminal(), "Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.")
 	runCmd.Flags().StringVarP(&opts.workingDir, "workdir", "w", "", "Path to workdir directory for this command.")
 
 	runCmd.Flags().BoolVarP(&opts.interactive, "interactive", "i", true, "Keep STDIN open even if not attached.")
@@ -80,8 +81,8 @@ func execCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 	return runCmd
 }
 
-func runExec(ctx context.Context, backend api.Service, opts execOpts) error {
-	projectName, err := opts.toProjectName()
+func runExec(ctx context.Context, dockerCli command.Cli, backend api.Service, opts execOpts) error {
+	projectName, err := opts.toProjectName(dockerCli)
 	if err != nil {
 		return err
 	}

cmd/compose/images.go

@@ -23,6 +23,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/docker/pkg/stringid"
 	"github.com/docker/go-units"
 	"github.com/spf13/cobra"
@@ -38,7 +39,7 @@ type imageOptions struct {
 	Format string
 }
 
-func imagesCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func imagesCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := imageOptions{
 		ProjectOptions: p,
 	}
@@ -46,17 +47,17 @@ func imagesCommand(p *ProjectOptions, streams api.Streams, backend api.Service)
 		Use:   "images [OPTIONS] [SERVICE...]",
 		Short: "List images used by the created containers",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runImages(ctx, streams, backend, opts, args)
+			return runImages(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	imgCmd.Flags().StringVar(&opts.Format, "format", "table", "Format the output. Values: [table | json].")
 	imgCmd.Flags().BoolVarP(&opts.Quiet, "quiet", "q", false, "Only display IDs")
 	return imgCmd
 }
 
-func runImages(ctx context.Context, streams api.Streams, backend api.Service, opts imageOptions, services []string) error {
-	projectName, err := opts.toProjectName()
+func runImages(ctx context.Context, dockerCli command.Cli, backend api.Service, opts imageOptions, services []string) error {
+	projectName, err := opts.toProjectName(dockerCli)
 	if err != nil {
 		return err
 	}
@@ -80,7 +81,7 @@ func runImages(ctx context.Context, streams api.Streams, backend api.Service, op
 			}
 		}
 		for _, img := range ids {
-			fmt.Fprintln(streams.Out(), img)
+			fmt.Fprintln(dockerCli.Out(), img)
 		}
 		return nil
 	}
@@ -89,7 +90,7 @@ func runImages(ctx context.Context, streams api.Streams, backend api.Service, op
 		return images[i].ContainerName < images[j].ContainerName
 	})
 
-	return formatter.Print(images, opts.Format, streams.Out(),
+	return formatter.Print(images, opts.Format, dockerCli.Out(),
 		func(w io.Writer) {
 			for _, img := range images {
 				id := stringid.TruncateID(img.ID)

cmd/compose/kill.go

@@ -20,6 +20,7 @@ import (
 	"context"
 	"os"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -32,7 +33,7 @@ type killOptions struct {
 	signal        string
 }
 
-func killCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func killCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := killOptions{
 		ProjectOptions: p,
 	}
@@ -40,21 +41,21 @@ func killCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		Use:   "kill [OPTIONS] [SERVICE...]",
 		Short: "Force stop service containers.",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runKill(ctx, backend, opts, args)
+			return runKill(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 
 	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.")
 
 	return cmd
 }
 
-func runKill(ctx context.Context, backend api.Service, opts killOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runKill(ctx context.Context, dockerCli command.Cli, backend api.Service, opts killOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}

cmd/compose/list.go

@@ -22,6 +22,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/cmd/formatter"
 
 	"github.com/docker/cli/opts"
@@ -37,13 +38,13 @@ type lsOptions struct {
 	Filter opts.FilterOpt
 }
 
-func listCommand(streams api.Streams, backend api.Service) *cobra.Command {
+func listCommand(dockerCli command.Cli, backend api.Service) *cobra.Command {
 	lsOpts := lsOptions{Filter: opts.NewFilterOpt()}
 	lsCmd := &cobra.Command{
 		Use:   "ls [OPTIONS]",
 		Short: "List running compose projects",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runList(ctx, streams, backend, lsOpts)
+			return runList(ctx, dockerCli, backend, lsOpts)
 		}),
 		Args:              cobra.NoArgs,
 		ValidArgsFunction: noCompletion(),
@@ -60,7 +61,7 @@ var acceptedListFilters = map[string]bool{
 	"name": true,
 }
 
-func runList(ctx context.Context, streams api.Streams, backend api.Service, lsOpts lsOptions) error {
+func runList(ctx context.Context, dockerCli command.Cli, backend api.Service, lsOpts lsOptions) error {
 	filters := lsOpts.Filter.Value()
 	err := filters.Validate(acceptedListFilters)
 	if err != nil {
@@ -71,12 +72,6 @@ func runList(ctx context.Context, streams api.Streams, backend api.Service, lsOp
 	if err != nil {
 		return err
 	}
-	if lsOpts.Quiet {
-		for _, s := range stackList {
-			fmt.Fprintln(streams.Out(), s.Name)
-		}
-		return nil
-	}
 
 	if filters.Len() > 0 {
 		var filtered []api.Stack
@@ -89,8 +84,15 @@ func runList(ctx context.Context, streams api.Streams, backend api.Service, lsOp
 		stackList = filtered
 	}
 
+	if lsOpts.Quiet {
+		for _, s := range stackList {
+			fmt.Fprintln(dockerCli.Out(), s.Name)
+		}
+		return nil
+	}
+
 	view := viewFromStackList(stackList)
-	return formatter.Print(view, lsOpts.Format, streams.Out(), func(w io.Writer) {
+	return formatter.Print(view, lsOpts.Format, dockerCli.Out(), func(w io.Writer) {
 		for _, stack := range view {
 			_, _ = fmt.Fprintf(w, "%s\t%s\t%s\n", stack.Name, stack.Status, stack.ConfigFiles)
 		}

cmd/compose/logs.go

@@ -19,6 +19,7 @@ package compose
 import (
 	"context"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/cmd/formatter"
@@ -37,7 +38,7 @@ type logsOptions struct {
 	timestamps bool
 }
 
-func logsCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func logsCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := logsOptions{
 		ProjectOptions: p,
 	}
@@ -45,9 +46,9 @@ func logsCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 		Use:   "logs [OPTIONS] [SERVICE...]",
 		Short: "View output from containers",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runLogs(ctx, streams, backend, opts, args)
+			return runLogs(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	flags := logsCmd.Flags()
 	flags.BoolVarP(&opts.follow, "follow", "f", false, "Follow log output.")
@@ -60,12 +61,12 @@ func logsCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 	return logsCmd
 }
 
-func runLogs(ctx context.Context, streams api.Streams, backend api.Service, opts logsOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runLogs(ctx context.Context, dockerCli command.Cli, backend api.Service, opts logsOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}
-	consumer := formatter.NewLogConsumer(ctx, streams.Out(), streams.Err(), !opts.noColor, !opts.noPrefix, false)
+	consumer := formatter.NewLogConsumer(ctx, dockerCli.Out(), dockerCli.Err(), !opts.noColor, !opts.noPrefix, false)
 	return backend.Logs(ctx, name, consumer, api.LogOptions{
 		Project:    project,
 		Services:   services,

cmd/compose/options.go

@@ -0,0 +1,76 @@
+/*
+   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 (
+	"fmt"
+
+	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/compose/v2/pkg/utils"
+)
+
+func applyPlatforms(project *types.Project, buildForSinglePlatform bool) error {
+	defaultPlatform := project.Environment["DOCKER_DEFAULT_PLATFORM"]
+	for i := range project.Services {
+		// mutable reference so platform fields can be updated
+		service := &project.Services[i]
+
+		if service.Build == nil {
+			continue
+		}
+
+		// default platform only applies if the service doesn't specify
+		if defaultPlatform != "" && service.Platform == "" {
+			if len(service.Build.Platforms) > 0 && !utils.StringContains(service.Build.Platforms, defaultPlatform) {
+				return fmt.Errorf("service %q build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: %s", service.Name, defaultPlatform)
+			}
+			service.Platform = defaultPlatform
+		}
+
+		if service.Platform != "" {
+			if len(service.Build.Platforms) > 0 {
+				if !utils.StringContains(service.Build.Platforms, service.Platform) {
+					return fmt.Errorf("service %q build configuration does not support platform: %s", service.Name, service.Platform)
+				}
+			}
+
+			if buildForSinglePlatform || len(service.Build.Platforms) == 0 {
+				// if we're building for a single platform, we want to build for the platform we'll use to run the image
+				// similarly, if no build platforms were explicitly specified, it makes sense to build for the platform
+				// the image is designed for rather than allowing the builder to infer the platform
+				service.Build.Platforms = []string{service.Platform}
+			}
+		}
+
+		// services can specify that they should be built for multiple platforms, which can be used
+		// with `docker compose build` to produce a multi-arch image
+		// other cases, such as `up` and `run`, need a single architecture to actually run
+		// if there is only a single platform present (which might have been inferred
+		// from service.Platform above), it will be used, even if it requires emulation.
+		// if there's more than one platform, then the list is cleared so that the builder
+		// can decide.
+		// TODO(milas): there's no validation that the platform the builder will pick is actually one
+		// 	of the supported platforms from the build definition
+		// 	e.g. `build.platforms: [linux/arm64, linux/amd64]` on a `linux/ppc64` machine would build
+		// 	for `linux/ppc64` instead of returning an error that it's not a valid platform for the service.
+		if buildForSinglePlatform && len(service.Build.Platforms) > 1 {
+			// empty indicates that the builder gets to decide
+			service.Build.Platforms = nil
+		}
+	}
+	return nil
+}

cmd/compose/options_test.go

@@ -0,0 +1,130 @@
+/*
+   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 (
+	"testing"
+
+	"github.com/compose-spec/compose-go/types"
+	"github.com/stretchr/testify/require"
+)
+
+func TestApplyPlatforms_InferFromRuntime(t *testing.T) {
+	makeProject := func() *types.Project {
+		return &types.Project{
+			Services: []types.ServiceConfig{
+				{
+					Name:  "test",
+					Image: "foo",
+					Build: &types.BuildConfig{
+						Context: ".",
+						Platforms: []string{
+							"linux/amd64",
+							"linux/arm64",
+							"alice/32",
+						},
+					},
+					Platform: "alice/32",
+				},
+			},
+		}
+	}
+
+	t.Run("SinglePlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, true))
+		require.EqualValues(t, []string{"alice/32"}, project.Services[0].Build.Platforms)
+	})
+
+	t.Run("MultiPlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, false))
+		require.EqualValues(t, []string{"linux/amd64", "linux/arm64", "alice/32"},
+			project.Services[0].Build.Platforms)
+	})
+}
+
+func TestApplyPlatforms_DockerDefaultPlatform(t *testing.T) {
+	makeProject := func() *types.Project {
+		return &types.Project{
+			Environment: map[string]string{
+				"DOCKER_DEFAULT_PLATFORM": "linux/amd64",
+			},
+			Services: []types.ServiceConfig{
+				{
+					Name:  "test",
+					Image: "foo",
+					Build: &types.BuildConfig{
+						Context: ".",
+						Platforms: []string{
+							"linux/amd64",
+							"linux/arm64",
+						},
+					},
+				},
+			},
+		}
+	}
+
+	t.Run("SinglePlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, true))
+		require.EqualValues(t, []string{"linux/amd64"}, project.Services[0].Build.Platforms)
+	})
+
+	t.Run("MultiPlatform", func(t *testing.T) {
+		project := makeProject()
+		require.NoError(t, applyPlatforms(project, false))
+		require.EqualValues(t, []string{"linux/amd64", "linux/arm64"},
+			project.Services[0].Build.Platforms)
+	})
+}
+
+func TestApplyPlatforms_UnsupportedPlatform(t *testing.T) {
+	makeProject := func() *types.Project {
+		return &types.Project{
+			Environment: map[string]string{
+				"DOCKER_DEFAULT_PLATFORM": "commodore/64",
+			},
+			Services: []types.ServiceConfig{
+				{
+					Name:  "test",
+					Image: "foo",
+					Build: &types.BuildConfig{
+						Context: ".",
+						Platforms: []string{
+							"linux/amd64",
+							"linux/arm64",
+						},
+					},
+				},
+			},
+		}
+	}
+
+	t.Run("SinglePlatform", func(t *testing.T) {
+		project := makeProject()
+		require.EqualError(t, applyPlatforms(project, true),
+			`service "test" build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: commodore/64`)
+	})
+
+	t.Run("MultiPlatform", func(t *testing.T) {
+		project := makeProject()
+		require.EqualError(t, applyPlatforms(project, false),
+			`service "test" build.platforms does not support value set by DOCKER_DEFAULT_PLATFORM: commodore/64`)
+	})
+}

cmd/compose/pause.go

@@ -19,6 +19,7 @@ package compose
 import (
 	"context"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -28,7 +29,7 @@ type pauseOptions struct {
 	*ProjectOptions
 }
 
-func pauseCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func pauseCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := pauseOptions{
 		ProjectOptions: p,
 	}
@@ -36,15 +37,15 @@ func pauseCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		Use:   "pause [SERVICE...]",
 		Short: "Pause services",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runPause(ctx, backend, opts, args)
+			return runPause(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	return cmd
 }
 
-func runPause(ctx context.Context, backend api.Service, opts pauseOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runPause(ctx context.Context, dockerCli command.Cli, backend api.Service, opts pauseOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}
@@ -59,7 +60,7 @@ type unpauseOptions struct {
 	*ProjectOptions
 }
 
-func unpauseCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func unpauseCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := unpauseOptions{
 		ProjectOptions: p,
 	}
@@ -67,15 +68,15 @@ func unpauseCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		Use:   "unpause [SERVICE...]",
 		Short: "Unpause services",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runUnPause(ctx, backend, opts, args)
+			return runUnPause(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	return cmd
 }
 
-func runUnPause(ctx context.Context, backend api.Service, opts unpauseOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runUnPause(ctx context.Context, dockerCli command.Cli, backend api.Service, opts unpauseOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}

cmd/compose/port.go

@@ -22,6 +22,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -34,7 +35,7 @@ type portOptions struct {
 	index    int
 }
 
-func portCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func portCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := portOptions{
 		ProjectOptions: p,
 	}
@@ -52,17 +53,17 @@ func portCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *c
 			return nil
 		}),
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runPort(ctx, streams, backend, opts, args[0])
+			return runPort(ctx, dockerCli, backend, opts, args[0])
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, 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
 }
 
-func runPort(ctx context.Context, streams api.Streams, backend api.Service, opts portOptions, service string) error {
-	projectName, err := opts.toProjectName()
+func runPort(ctx context.Context, dockerCli command.Cli, backend api.Service, opts portOptions, service string) error {
+	projectName, err := opts.toProjectName(dockerCli)
 	if err != nil {
 		return err
 	}
@@ -74,6 +75,6 @@ func runPort(ctx context.Context, streams api.Streams, backend api.Service, opts
 		return err
 	}
 
-	fmt.Fprintf(streams.Out(), "%s:%d\n", ip, port)
+	fmt.Fprintf(dockerCli.Out(), "%s:%d\n", ip, port)
 	return nil
 }

cmd/compose/ps.go

@@ -18,23 +18,19 @@ package compose
 
 import (
 	"context"
+	"errors"
 	"fmt"
-	"io"
 	"sort"
-	"strconv"
 	"strings"
-	"time"
 
 	"github.com/docker/compose/v2/cmd/formatter"
-	"github.com/docker/compose/v2/pkg/utils"
-	"github.com/docker/docker/api/types"
-
-	formatter2 "github.com/docker/cli/cli/command/formatter"
-	"github.com/docker/go-units"
-	"github.com/pkg/errors"
-	"github.com/spf13/cobra"
-
 	"github.com/docker/compose/v2/pkg/api"
+	"github.com/docker/compose/v2/pkg/utils"
+
+	"github.com/docker/cli/cli/command"
+	cliformatter "github.com/docker/cli/cli/command/formatter"
+	cliflags "github.com/docker/cli/cli/flags"
+	"github.com/spf13/cobra"
 )
 
 type psOptions struct {
@@ -45,6 +41,7 @@ type psOptions struct {
 	Services bool
 	Filter   string
 	Status   []string
+	noTrunc  bool
 }
 
 func (p *psOptions) parseFilter() error {
@@ -66,7 +63,7 @@ func (p *psOptions) parseFilter() error {
 	return nil
 }
 
-func psCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func psCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := psOptions{
 		ProjectOptions: p,
 	}
@@ -77,22 +74,23 @@ func psCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cob
 			return opts.parseFilter()
 		},
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runPs(ctx, streams, backend, args, opts)
+			return runPs(ctx, dockerCli, backend, args, opts)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	flags := psCmd.Flags()
-	flags.StringVar(&opts.Format, "format", "table", "Format the output. Values: [table | json]")
+	flags.StringVar(&opts.Format, "format", "table", cliflags.FormatHelp)
 	flags.StringVar(&opts.Filter, "filter", "", "Filter services by a property (supported filters: status).")
 	flags.StringArrayVar(&opts.Status, "status", []string{}, "Filter services by status. Values: [paused | restarting | removing | running | dead | created | exited]")
 	flags.BoolVarP(&opts.Quiet, "quiet", "q", false, "Only display IDs")
 	flags.BoolVar(&opts.Services, "services", false, "Display services")
 	flags.BoolVarP(&opts.All, "all", "a", false, "Show all stopped containers (including those created by the run command)")
+	flags.BoolVar(&opts.noTrunc, "no-trunc", false, "Don't truncate output")
 	return psCmd
 }
 
-func runPs(ctx context.Context, streams api.Streams, backend api.Service, services []string, opts psOptions) error {
-	project, name, err := opts.projectOrName(services...)
+func runPs(ctx context.Context, dockerCli command.Cli, backend api.Service, services []string, opts psOptions) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}
@@ -125,38 +123,33 @@ func runPs(ctx context.Context, streams api.Streams, backend api.Service, servic
 
 	if opts.Quiet {
 		for _, c := range containers {
-			fmt.Fprintln(streams.Out(), c.ID)
+			fmt.Fprintln(dockerCli.Out(), c.ID)
 		}
 		return nil
 	}
 
 	if opts.Services {
 		services := []string{}
-		for _, s := range containers {
-			if !utils.StringContains(services, s.Service) {
-				services = append(services, s.Service)
+		for _, c := range containers {
+			s := c.Service
+			if !utils.StringContains(services, s) {
+				services = append(services, s)
 			}
 		}
-		fmt.Fprintln(streams.Out(), strings.Join(services, "\n"))
+		fmt.Fprintln(dockerCli.Out(), strings.Join(services, "\n"))
 		return nil
 	}
 
-	return formatter.Print(containers, opts.Format, streams.Out(),
-		writer(containers),
-		"NAME", "IMAGE", "COMMAND", "SERVICE", "CREATED", "STATUS", "PORTS")
-}
-
-func writer(containers []api.ContainerSummary) func(w io.Writer) {
-	return func(w io.Writer) {
-		for _, container := range containers {
-			ports := displayablePorts(container)
-			createdAt := time.Unix(container.Created, 0)
-			created := units.HumanDuration(time.Now().UTC().Sub(createdAt)) + " ago"
-			status := container.Status
-			command := formatter2.Ellipsis(container.Command, 20)
-			_, _ = fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n", container.Name, container.Image, strconv.Quote(command), container.Service, created, status, ports)
-		}
+	if opts.Format == "" {
+		opts.Format = dockerCli.ConfigFile().PsFormat
 	}
+
+	containerCtx := cliformatter.Context{
+		Output: dockerCli.Out(),
+		Format: formatter.NewContainerFormat(opts.Format, opts.Quiet, false),
+		Trunc:  !opts.noTrunc,
+	}
+	return formatter.ContainerWrite(containerCtx, containers)
 }
 
 func filterByStatus(containers []api.ContainerSummary, statuses []string) []api.ContainerSummary {
@@ -177,21 +170,3 @@ func hasStatus(c api.ContainerSummary, statuses []string) bool {
 	}
 	return false
 }
-
-func displayablePorts(c api.ContainerSummary) string {
-	if c.Publishers == nil {
-		return ""
-	}
-
-	ports := make([]types.Port, len(c.Publishers))
-	for i, pub := range c.Publishers {
-		ports[i] = types.Port{
-			IP:          pub.URL,
-			PrivatePort: uint16(pub.TargetPort),
-			PublicPort:  uint16(pub.PublishedPort),
-			Type:        pub.Protocol,
-		}
-	}
-
-	return formatter2.DisplayablePorts(ports)
-}

cmd/compose/ps_test.go

@@ -18,11 +18,11 @@ package compose
 
 import (
 	"context"
-	"io"
 	"os"
 	"path/filepath"
 	"testing"
 
+	"github.com/docker/cli/cli/config/configfile"
 	"github.com/docker/cli/cli/streams"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/docker/compose/v2/pkg/mocks"
@@ -69,7 +69,11 @@ func TestPsTable(t *testing.T) {
 		}).AnyTimes()
 
 	opts := psOptions{ProjectOptions: &ProjectOptions{ProjectName: "test"}}
-	err = runPs(ctx, stream{out: streams.NewOut(f)}, backend, nil, opts)
+	stdout := streams.NewOut(f)
+	cli := mocks.NewMockCli(ctrl)
+	cli.EXPECT().Out().Return(stdout).AnyTimes()
+	cli.EXPECT().ConfigFile().Return(&configfile.ConfigFile{}).AnyTimes()
+	err = runPs(ctx, cli, backend, nil, opts)
 	assert.NoError(t, err)
 
 	_, err = f.Seek(0, 0)
@@ -80,21 +84,3 @@ func TestPsTable(t *testing.T) {
 
 	assert.Contains(t, string(output), "8080/tcp, 8443/tcp")
 }
-
-type stream struct {
-	out *streams.Out
-	err io.Writer
-	in  *streams.In
-}
-
-func (s stream) Out() *streams.Out {
-	return s.out
-}
-
-func (s stream) Err() io.Writer {
-	return s.err
-}
-
-func (s stream) In() *streams.In {
-	return s.in
-}

cmd/compose/publish.go

@@ -0,0 +1,59 @@
+/*
+   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/docker/cli/cli/command"
+	"github.com/spf13/cobra"
+
+	"github.com/docker/compose/v2/pkg/api"
+)
+
+type publishOptions struct {
+	*ProjectOptions
+	resolveImageDigests bool
+}
+
+func publishCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
+	opts := publishOptions{
+		ProjectOptions: p,
+	}
+	cmd := &cobra.Command{
+		Use:   "publish [OPTIONS] [REPOSITORY]",
+		Short: "Publish compose application",
+		RunE: Adapt(func(ctx context.Context, args []string) error {
+			return runPublish(ctx, dockerCli, backend, opts, args[0])
+		}),
+		Args: cobra.ExactArgs(1),
+	}
+	flags := cmd.Flags()
+	flags.BoolVar(&opts.resolveImageDigests, "resolve-image-digests", false, "Pin image tags to digests.")
+	return cmd
+}
+
+func runPublish(ctx context.Context, dockerCli command.Cli, backend api.Service, opts publishOptions, repository string) error {
+	project, err := opts.ToProject(dockerCli, nil)
+	if err != nil {
+		return err
+	}
+
+	return backend.Publish(ctx, project, repository, api.PublishOptions{
+		ResolveImageDigests: opts.resolveImageDigests,
+	})
+}

cmd/compose/pull.go

@@ -22,11 +22,11 @@ import (
 	"os"
 
 	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/cli/cli/command"
 	"github.com/morikuni/aec"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
-	"github.com/docker/compose/v2/pkg/utils"
 )
 
 type pullOptions struct {
@@ -38,9 +38,10 @@ type pullOptions struct {
 	includeDeps        bool
 	ignorePullFailures bool
 	noBuildable        bool
+	policy             string
 }
 
-func pullCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func pullCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := pullOptions{
 		ProjectOptions: p,
 	}
@@ -54,9 +55,9 @@ func pullCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 			return nil
 		}),
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runPull(ctx, backend, opts, args)
+			return runPull(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	flags := cmd.Flags()
 	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Pull without printing progress information.")
@@ -67,37 +68,41 @@ func pullCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	flags.MarkHidden("no-parallel") //nolint:errcheck
 	cmd.Flags().BoolVar(&opts.ignorePullFailures, "ignore-pull-failures", false, "Pull what it can and ignores images with pull failures.")
 	cmd.Flags().BoolVar(&opts.noBuildable, "ignore-buildable", false, "Ignore images that can be built.")
+	cmd.Flags().StringVar(&opts.policy, "policy", "", `Apply pull policy ("missing"|"always").`)
 	return cmd
 }
 
-func withSelectedServicesOnly(project *types.Project, services []string) error {
-	enabled, err := project.GetServices(services...)
-	if err != nil {
-		return err
-	}
-	for _, s := range project.Services {
-		if !utils.StringContains(services, s.Name) {
-			project.DisabledServices = append(project.DisabledServices, s)
-		}
-	}
-	project.Services = enabled
-
-	return nil
-}
-
-func runPull(ctx context.Context, backend api.Service, opts pullOptions, services []string) error {
-	project, err := opts.ToProject(services)
-	if err != nil {
-		return err
-	}
-
+func (opts pullOptions) apply(project *types.Project, services []string) error {
 	if !opts.includeDeps {
-		err := withSelectedServicesOnly(project, services)
+		err := project.ForServices(services, types.IgnoreDependencies)
 		if err != nil {
 			return err
 		}
 	}
 
+	if opts.policy != "" {
+		for i, service := range project.Services {
+			if service.Image == "" {
+				continue
+			}
+			service.PullPolicy = opts.policy
+			project.Services[i] = service
+		}
+	}
+	return nil
+}
+
+func runPull(ctx context.Context, dockerCli command.Cli, backend api.Service, opts pullOptions, services []string) error {
+	project, err := opts.ToProject(dockerCli, services)
+	if err != nil {
+		return err
+	}
+
+	err = opts.apply(project, services)
+	if err != nil {
+		return err
+	}
+
 	return backend.Pull(ctx, project, api.PullOptions{
 		Quiet:           opts.quiet,
 		IgnoreFailures:  opts.ignorePullFailures,

cmd/compose/pullOptions_test.go

@@ -0,0 +1,57 @@
+/*
+   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 (
+	"testing"
+
+	"github.com/compose-spec/compose-go/types"
+	"gotest.tools/v3/assert"
+)
+
+func TestApplyPullOptions(t *testing.T) {
+	project := &types.Project{
+		Services: []types.ServiceConfig{
+			{
+				Name: "must-build",
+				// No image, local build only
+				Build: &types.BuildConfig{
+					Context: ".",
+				},
+			},
+			{
+				Name:  "has-build",
+				Image: "registry.example.com/myservice",
+				Build: &types.BuildConfig{
+					Context: ".",
+				},
+			},
+			{
+				Name:  "must-pull",
+				Image: "registry.example.com/another-service",
+			},
+		},
+	}
+	err := pullOptions{
+		policy: types.PullPolicyMissing,
+	}.apply(project, nil)
+	assert.NilError(t, err)
+
+	assert.Equal(t, project.Services[0].PullPolicy, "") // still default
+	assert.Equal(t, project.Services[1].PullPolicy, types.PullPolicyMissing)
+	assert.Equal(t, project.Services[2].PullPolicy, types.PullPolicyMissing)
+}

cmd/compose/push.go

@@ -19,6 +19,8 @@ package compose
 import (
 	"context"
 
+	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -32,7 +34,7 @@ type pushOptions struct {
 	Quiet          bool
 }
 
-func pushCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func pushCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := pushOptions{
 		ProjectOptions: p,
 	}
@@ -40,9 +42,9 @@ func pushCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		Use:   "push [OPTIONS] [SERVICE...]",
 		Short: "Push service images",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runPush(ctx, backend, opts, args)
+			return runPush(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	pushCmd.Flags().BoolVar(&opts.Ignorefailures, "ignore-push-failures", false, "Push what it can and ignores images with push failures")
 	pushCmd.Flags().BoolVar(&opts.IncludeDeps, "include-deps", false, "Also push images of services declared as dependencies")
@@ -51,14 +53,14 @@ func pushCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 	return pushCmd
 }
 
-func runPush(ctx context.Context, backend api.Service, opts pushOptions, services []string) error {
-	project, err := opts.ToProject(services)
+func runPush(ctx context.Context, dockerCli command.Cli, backend api.Service, opts pushOptions, services []string) error {
+	project, err := opts.ToProject(dockerCli, services)
 	if err != nil {
 		return err
 	}
 
 	if !opts.IncludeDeps {
-		err := withSelectedServicesOnly(project, services)
+		err := project.ForServices(services, types.IgnoreDependencies)
 		if err != nil {
 			return err
 		}

cmd/compose/remove.go

@@ -19,6 +19,7 @@ package compose
 import (
 	"context"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/spf13/cobra"
 )
@@ -30,7 +31,7 @@ type removeOptions struct {
 	volumes bool
 }
 
-func removeCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func removeCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := removeOptions{
 		ProjectOptions: p,
 	}
@@ -44,9 +45,9 @@ can override this with -v. To list all volumes, use "docker volume ls".
 
 Any data which is not in a volume will be lost.`,
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runRemove(ctx, backend, opts, args)
+			return runRemove(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	f := cmd.Flags()
 	f.BoolVarP(&opts.force, "force", "f", false, "Don't ask to confirm removal")
@@ -58,26 +59,17 @@ Any data which is not in a volume will be lost.`,
 	return cmd
 }
 
-func runRemove(ctx context.Context, backend api.Service, opts removeOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runRemove(ctx context.Context, dockerCli command.Cli, backend api.Service, opts removeOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		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,
 		Volumes:  opts.volumes,
 		Project:  project,
+		Stop:     opts.stop,
 	})
 }

cmd/compose/restart.go

@@ -20,6 +20,7 @@ import (
 	"context"
 	"time"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -27,37 +28,56 @@ import (
 
 type restartOptions struct {
 	*ProjectOptions
-	timeout int
+	timeChanged bool
+	timeout     int
+	noDeps      bool
 }
 
-func restartCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func restartCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := restartOptions{
 		ProjectOptions: p,
 	}
 	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)
+			return runRestart(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, 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
 }
 
-func runRestart(ctx context.Context, backend api.Service, opts restartOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runRestart(ctx context.Context, dockerCli command.Cli, backend api.Service, opts restartOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli)
 	if err != nil {
 		return err
 	}
 
-	timeout := time.Duration(opts.timeout) * time.Second
+	if project != nil && len(services) > 0 {
+		err := project.EnableServices(services...)
+		if err != nil {
+			return err
+		}
+	}
+
+	var timeout *time.Duration
+	if opts.timeChanged {
+		timeoutValue := time.Duration(opts.timeout) * time.Second
+		timeout = &timeoutValue
+	}
+
 	return backend.Restart(ctx, name, api.RestartOptions{
-		Timeout:  &timeout,
+		Timeout:  timeout,
 		Services: services,
 		Project:  project,
+		NoDeps:   opts.noDeps,
 	})
 }

cmd/compose/run.go

@@ -21,9 +21,13 @@ import (
 	"fmt"
 	"strings"
 
+	xprogress "github.com/docker/buildx/util/progress"
+
 	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/cli/command"
+	"github.com/docker/cli/opts"
 	"github.com/mattn/go-shellwords"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -48,6 +52,8 @@ type runOptions struct {
 	workdir       string
 	entrypoint    string
 	entrypointCmd []string
+	capAdd        opts.ListOpts
+	capDrop       opts.ListOpts
 	labels        []string
 	volumes       []string
 	publish       []string
@@ -59,20 +65,26 @@ 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
+
+	// --service-ports and --publish are incompatible
+	if !options.servicePorts {
 		target.Ports = []types.ServicePortConfig{}
-	}
-	if len(opts.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,27 +92,17 @@ func (opts runOptions) apply(project *types.Project) error {
 			target.Ports = append(target.Ports, config...)
 		}
 	}
-	if len(opts.volumes) > 0 {
-		for _, v := range opts.volumes {
-			volume, err := loader.ParseVolume(v)
-			if err != nil {
-				return err
-			}
-			target.Volumes = append(target.Volumes, volume)
-		}
-	}
 
-	if opts.noDeps {
-		for _, s := range project.Services {
-			if s.Name != opts.Service {
-				project.DisabledServices = append(project.DisabledServices, s)
-			}
+	for _, v := range options.volumes {
+		volume, err := loader.ParseVolume(v)
+		if err != nil {
+			return err
 		}
-		project.Services = types.Services{target}
+		target.Volumes = append(target.Volumes, volume)
 	}
 
 	for i, s := range project.Services {
-		if s.Name == opts.Service {
+		if s.Name == options.Service {
 			project.Services[i] = target
 			break
 		}
@@ -108,72 +110,84 @@ func (opts runOptions) apply(project *types.Project) error {
 	return nil
 }
 
-func runCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
-	opts := runOptions{
+func runCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
+	options := runOptions{
 		composeOptions: &composeOptions{
 			ProjectOptions: p,
 		},
+		capAdd:  opts.NewListOpts(nil),
+		capDrop: opts.NewListOpts(nil),
 	}
 	createOpts := createOptions{}
+	buildOpts := buildOptions{
+		ProjectOptions: p,
+	}
 	cmd := &cobra.Command{
 		Use:   "run [OPTIONS] SERVICE [COMMAND] [ARGS...]",
 		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(dockerCli, []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)
+
+			if createOpts.quietPull {
+				buildOpts.Progress = xprogress.PrinterModeQuiet
+			}
+
+			options.ignoreOrphans = utils.StringToBool(project.Environment[ComposeIgnoreOrphans])
+			return runRun(ctx, backend, project, options, createOpts, buildOpts, dockerCli)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, 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", !dockerCli.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)
@@ -191,8 +205,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) error {
-	err := opts.apply(project)
+func runRun(ctx context.Context, backend api.Service, project *types.Project, options runOptions, createOpts createOptions, buildOpts buildOptions, dockerCli command.Cli) error {
+	err := options.apply(project)
 	if err != nil {
 		return err
 	}
@@ -203,14 +217,23 @@ 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)
-	})
+		var buildForDeps *api.BuildOptions
+		if !createOpts.noBuild {
+			// allow dependencies needing build to be implicitly selected
+			bo, err := buildOpts.toAPIBuildOptions(nil)
+			if err != nil {
+				return err
+			}
+			buildForDeps = &bo
+		}
+		return startDependencies(ctx, backend, *project, buildForDeps, options.Service, options.ignoreOrphans)
+	}, dockerCli.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,29 +241,43 @@ func runRun(ctx context.Context, backend api.Service, project *types.Project, op
 		labels[parts[0]] = parts[1]
 	}
 
+	var buildForRun *api.BuildOptions
+	if !createOpts.noBuild {
+		// dependencies have already been started above, so only the service
+		// being run might need to be built at this point
+		bo, err := buildOpts.toAPIBuildOptions([]string{options.Service})
+		if err != nil {
+			return err
+		}
+		buildForRun = &bo
+	}
+
 	// 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,
+		Build:             buildForRun,
+		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
 		}
 	}
@@ -256,7 +293,7 @@ func runRun(ctx context.Context, backend api.Service, project *types.Project, op
 	return err
 }
 
-func startDependencies(ctx context.Context, backend api.Service, project types.Project, requestedServiceName string, ignoreOrphans bool) error {
+func startDependencies(ctx context.Context, backend api.Service, project types.Project, buildOpts *api.BuildOptions, requestedServiceName string, ignoreOrphans bool) error {
 	dependencies := types.Services{}
 	var requestedService types.ServiceConfig
 	for _, service := range project.Services {
@@ -270,6 +307,7 @@ func startDependencies(ctx context.Context, backend api.Service, project types.P
 	project.Services = dependencies
 	project.DisabledServices = append(project.DisabledServices, requestedService)
 	err := backend.Create(ctx, &project, api.CreateOptions{
+		Build:         buildOpts,
 		IgnoreOrphans: ignoreOrphans,
 	})
 	if err != nil {

cmd/compose/scale.go

@@ -0,0 +1,108 @@
+/*
+   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"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/docker/cli/cli/command"
+
+	"github.com/compose-spec/compose-go/types"
+	"golang.org/x/exp/maps"
+
+	"github.com/docker/compose/v2/pkg/api"
+	"github.com/spf13/cobra"
+)
+
+type scaleOptions struct {
+	*ProjectOptions
+	noDeps bool
+}
+
+func scaleCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
+	opts := scaleOptions{
+		ProjectOptions: p,
+	}
+	scaleCmd := &cobra.Command{
+		Use:   "scale [SERVICE=REPLICAS...]",
+		Short: "Scale services ",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: Adapt(func(ctx context.Context, args []string) error {
+			serviceTuples, err := parseServicesReplicasArgs(args)
+			if err != nil {
+				return err
+			}
+			return runScale(ctx, dockerCli, backend, opts, serviceTuples)
+		}),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
+	}
+	flags := scaleCmd.Flags()
+	flags.BoolVar(&opts.noDeps, "no-deps", false, "Don't start linked services.")
+
+	return scaleCmd
+}
+
+func runScale(ctx context.Context, dockerCli command.Cli, backend api.Service, opts scaleOptions, serviceReplicaTuples map[string]int) error {
+	services := maps.Keys(serviceReplicaTuples)
+	project, err := opts.ToProject(dockerCli, services)
+	if err != nil {
+		return err
+	}
+
+	if opts.noDeps {
+		if err := project.ForServices(services, types.IgnoreDependencies); err != nil {
+			return err
+		}
+	}
+
+	for key, value := range serviceReplicaTuples {
+		for i, service := range project.Services {
+			if service.Name != key {
+				continue
+			}
+			if service.Deploy == nil {
+				service.Deploy = &types.DeployConfig{}
+			}
+			scale := uint64(value)
+			service.Deploy.Replicas = &scale
+			project.Services[i] = service
+			break
+		}
+	}
+
+	return backend.Scale(ctx, project, api.ScaleOptions{Services: services})
+}
+
+func parseServicesReplicasArgs(args []string) (map[string]int, error) {
+	serviceReplicaTuples := map[string]int{}
+	for _, arg := range args {
+		key, val, ok := strings.Cut(arg, "=")
+		if !ok || key == "" || val == "" {
+			return nil, fmt.Errorf("invalid scale specifier: %s", arg)
+		}
+		intValue, err := strconv.Atoi(val)
+
+		if err != nil {
+			return nil, fmt.Errorf("invalid scale specifier: can't parse replica value as int: %v", arg)
+		}
+		serviceReplicaTuples[key] = intValue
+	}
+	return serviceReplicaTuples, nil
+}

cmd/compose/start.go

@@ -19,6 +19,7 @@ package compose
 import (
 	"context"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/spf13/cobra"
 )
@@ -27,7 +28,7 @@ type startOptions struct {
 	*ProjectOptions
 }
 
-func startCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func startCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := startOptions{
 		ProjectOptions: p,
 	}
@@ -35,15 +36,15 @@ func startCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 		Use:   "start [SERVICE...]",
 		Short: "Start services",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runStart(ctx, backend, opts, args)
+			return runStart(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	return startCmd
 }
 
-func runStart(ctx context.Context, backend api.Service, opts startOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runStart(ctx context.Context, dockerCli command.Cli, backend api.Service, opts startOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}

cmd/compose/stop.go

@@ -20,6 +20,7 @@ import (
 	"context"
 	"time"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -31,7 +32,7 @@ type stopOptions struct {
 	timeout     int
 }
 
-func stopCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
+func stopCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := stopOptions{
 		ProjectOptions: p,
 	}
@@ -42,18 +43,18 @@ func stopCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
 			opts.timeChanged = cmd.Flags().Changed("timeout")
 		},
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runStop(ctx, backend, opts, args)
+			return runStop(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, 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
 }
 
-func runStop(ctx context.Context, backend api.Service, opts stopOptions, services []string) error {
-	project, name, err := opts.projectOrName(services...)
+func runStop(ctx context.Context, dockerCli command.Cli, backend api.Service, opts stopOptions, services []string) error {
+	project, name, err := opts.projectOrName(dockerCli, services...)
 	if err != nil {
 		return err
 	}

cmd/compose/top.go

@@ -24,6 +24,7 @@ import (
 	"strings"
 	"text/tabwriter"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -33,7 +34,7 @@ type topOptions struct {
 	*ProjectOptions
 }
 
-func topCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func topCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	opts := topOptions{
 		ProjectOptions: p,
 	}
@@ -41,15 +42,15 @@ func topCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *co
 		Use:   "top [SERVICES...]",
 		Short: "Display the running processes",
 		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runTop(ctx, streams, backend, opts, args)
+			return runTop(ctx, dockerCli, backend, opts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	return topCmd
 }
 
-func runTop(ctx context.Context, streams api.Streams, backend api.Service, opts topOptions, services []string) error {
-	projectName, err := opts.toProjectName()
+func runTop(ctx context.Context, dockerCli command.Cli, backend api.Service, opts topOptions, services []string) error {
+	projectName, err := opts.toProjectName(dockerCli)
 	if err != nil {
 		return err
 	}
@@ -63,8 +64,8 @@ func runTop(ctx context.Context, streams api.Streams, backend api.Service, opts
 	})
 
 	for _, container := range containers {
-		fmt.Fprintf(streams.Out(), "%s\n", container.Name)
-		err := psPrinter(streams.Out(), func(w io.Writer) {
+		fmt.Fprintf(dockerCli.Out(), "%s\n", container.Name)
+		err := psPrinter(dockerCli.Out(), func(w io.Writer) {
 			for _, proc := range container.Processes {
 				info := []interface{}{}
 				for _, p := range proc {

cmd/compose/up.go

@@ -18,11 +18,16 @@ package compose
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"strings"
+	"time"
 
-	"github.com/docker/compose/v2/cmd/formatter"
+	xprogress "github.com/docker/buildx/util/progress"
 
 	"github.com/compose-spec/compose-go/types"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/compose/v2/cmd/formatter"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/pkg/api"
@@ -48,11 +53,12 @@ type upOptions struct {
 	noAttach           []string
 	timestamp          bool
 	wait               bool
+	waitTimeout        int
 }
 
 func (opts upOptions) apply(project *types.Project, services []string) error {
 	if opts.noDeps {
-		err := withSelectedServicesOnly(project, services)
+		err := project.ForServices(services, types.IgnoreDependencies)
 		if err != nil {
 			return err
 		}
@@ -68,9 +74,10 @@ func (opts upOptions) apply(project *types.Project, services []string) error {
 	return nil
 }
 
-func upCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cobra.Command {
+func upCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
 	up := upOptions{}
 	create := createOptions{}
+	build := buildOptions{ProjectOptions: p}
 	upCmd := &cobra.Command{
 		Use:   "up [OPTIONS] [SERVICE...]",
 		Short: "Create and start containers",
@@ -79,20 +86,23 @@ func upCommand(p *ProjectOptions, streams api.Streams, backend api.Service) *cob
 			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"])
+		RunE: p.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
+			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("cannot combine %s and --remove-orphans", ComposeIgnoreOrphans)
 			}
-			return runUp(ctx, streams, backend, create, up, project, services)
+			if len(up.attach) != 0 && up.attachDependencies {
+				return errors.New("cannot combine --attach and --attach-dependencies")
+			}
+			return runUp(ctx, dockerCli, backend, create, up, build, project, services)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 	flags := upCmd.Flags()
 	flags.BoolVarP(&up.Detach, "detach", "d", false, "Detached mode: Run containers in the background")
 	flags.BoolVar(&create.Build, "build", false, "Build images before starting containers.")
-	flags.BoolVar(&create.noBuild, "no-build", false, "Don't build an image, even if it's missing.")
-	flags.StringVar(&create.Pull, "pull", "missing", `Pull image before running ("always"|"missing"|"never")`)
+	flags.BoolVar(&create.noBuild, "no-build", false, "Don't build an image, even if it's policy.")
+	flags.StringVar(&create.Pull, "pull", "policy", `Pull image before running ("always"|"missing"|"never")`)
 	flags.BoolVar(&create.removeOrphans, "remove-orphans", false, "Remove containers for services not defined in the Compose file.")
 	flags.StringArrayVar(&create.scale, "scale", []string{}, "Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.")
 	flags.BoolVar(&up.noColor, "no-color", false, "Produce monochrome output.")
@@ -102,16 +112,17 @@ 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, "timeout", "t", 10, "Use this timeout 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.")
 	flags.BoolVarP(&create.noInherit, "renew-anon-volumes", "V", false, "Recreate anonymous volumes instead of retrieving data from the previous containers.")
-	flags.BoolVar(&up.attachDependencies, "attach-dependencies", false, "Attach to dependent containers.")
 	flags.BoolVar(&create.quietPull, "quiet-pull", false, "Pull without printing progress information.")
-	flags.StringArrayVar(&up.attach, "attach", []string{}, "Attach to service output.")
-	flags.StringArrayVar(&up.noAttach, "no-attach", []string{}, "Don't attach to specified service.")
+	flags.StringArrayVar(&up.attach, "attach", []string{}, "Restrict attaching to the specified services. Incompatible with --attach-dependencies.")
+	flags.StringArrayVar(&up.noAttach, "no-attach", []string{}, "Do not attach (stream logs) to the specified services.")
+	flags.BoolVar(&up.attachDependencies, "attach-dependencies", false, "Automatically attach to log output of dependent services.")
 	flags.BoolVar(&up.wait, "wait", false, "Wait for services to be running|healthy. Implies detached mode.")
+	flags.IntVar(&up.waitTimeout, "wait-timeout", 0, "Maximum duration to wait for the project to be running|healthy.")
 
 	return upCmd
 }
@@ -141,7 +152,16 @@ func validateFlags(up *upOptions, create *createOptions) error {
 	return nil
 }
 
-func runUp(ctx context.Context, streams api.Streams, backend api.Service, createOptions createOptions, upOptions upOptions, project *types.Project, services []string) error {
+func runUp(
+	ctx context.Context,
+	dockerCli command.Cli,
+	backend api.Service,
+	createOptions createOptions,
+	upOptions upOptions,
+	buildOptions buildOptions,
+	project *types.Project,
+	services []string,
+) error {
 	if len(project.Services) == 0 {
 		return fmt.Errorf("no service selected")
 	}
@@ -156,24 +176,26 @@ func runUp(ctx context.Context, streams api.Streams, backend api.Service, create
 		return err
 	}
 
-	var consumer api.LogConsumer
-	if !upOptions.Detach {
-		consumer = formatter.NewLogConsumer(ctx, streams.Out(), streams.Err(), !upOptions.noColor, !upOptions.noPrefix, upOptions.timestamp)
+	var build *api.BuildOptions
+	// this check is technically redundant as createOptions::apply()
+	// already removed all the build sections
+	if !createOptions.noBuild {
+		if createOptions.quietPull {
+			buildOptions.Progress = xprogress.PrinterModeQuiet
+		}
+		// BuildOptions here is nested inside CreateOptions, so
+		// no service list is passed, it will implicitly pick all
+		// services being created, which includes any explicitly
+		// specified via "services" arg here as well as deps
+		bo, err := buildOptions.toAPIBuildOptions(nil)
+		if err != nil {
+			return err
+		}
+		build = &bo
 	}
 
-	attachTo := services
-	if len(upOptions.attach) > 0 {
-		attachTo = upOptions.attach
-	}
-	if upOptions.attachDependencies {
-		attachTo = project.ServiceNames()
-	}
-	if len(attachTo) == 0 {
-		attachTo = project.ServiceNames()
-	}
-	attachTo = utils.Remove(attachTo, upOptions.noAttach...)
-
 	create := api.CreateOptions{
+		Build:                build,
 		Services:             services,
 		RemoveOrphans:        createOptions.removeOrphans,
 		IgnoreOrphans:        createOptions.ignoreOrphans,
@@ -188,15 +210,52 @@ func runUp(ctx context.Context, streams api.Streams, backend api.Service, create
 		return backend.Create(ctx, project, create)
 	}
 
+	var consumer api.LogConsumer
+	var attach []string
+	if !upOptions.Detach {
+		consumer = formatter.NewLogConsumer(ctx, dockerCli.Out(), dockerCli.Err(), !upOptions.noColor, !upOptions.noPrefix, upOptions.timestamp)
+
+		var attachSet utils.Set[string]
+		if len(upOptions.attach) != 0 {
+			// services are passed explicitly with --attach, verify they're valid and then use them as-is
+			attachSet = utils.NewSet(upOptions.attach...)
+			unexpectedSvcs := attachSet.Diff(utils.NewSet(project.ServiceNames()...))
+			if len(unexpectedSvcs) != 0 {
+				return fmt.Errorf("cannot attach to services not included in up: %s", strings.Join(unexpectedSvcs.Elements(), ", "))
+			}
+		} else {
+			// mark services being launched (and potentially their deps) for attach
+			// if they didn't opt-out via Compose YAML
+			attachSet = utils.NewSet[string]()
+			var dependencyOpt types.DependencyOption = types.IgnoreDependencies
+			if upOptions.attachDependencies {
+				dependencyOpt = types.IncludeDependencies
+			}
+			if err := project.WithServices(services, func(s types.ServiceConfig) error {
+				if s.Attach == nil || *s.Attach {
+					attachSet.Add(s.Name)
+				}
+				return nil
+			}, dependencyOpt); err != nil {
+				return err
+			}
+		}
+		// filter out any services that have been explicitly marked for ignore with `--no-attach`
+		attachSet.RemoveAll(upOptions.noAttach...)
+		attach = attachSet.Elements()
+	}
+
+	timeout := time.Duration(upOptions.waitTimeout) * time.Second
 	return backend.Up(ctx, project, api.UpOptions{
 		Create: create,
 		Start: api.StartOptions{
 			Project:      project,
 			Attach:       consumer,
-			AttachTo:     attachTo,
+			AttachTo:     attach,
 			ExitCodeFrom: upOptions.exitCodeFrom,
 			CascadeStop:  upOptions.cascadeStop,
 			Wait:         upOptions.wait,
+			WaitTimeout:  timeout,
 			Services:     services,
 		},
 	})

cmd/compose/version.go

@@ -20,6 +20,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/cmd/formatter"
 
 	"github.com/spf13/cobra"
@@ -32,14 +33,14 @@ type versionOptions struct {
 	short  bool
 }
 
-func versionCommand() *cobra.Command {
+func versionCommand(dockerCli command.Cli) *cobra.Command {
 	opts := versionOptions{}
 	cmd := &cobra.Command{
 		Use:   "version [OPTIONS]",
 		Short: "Show the Docker Compose version information",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			runVersion(opts)
+			runVersion(opts, dockerCli)
 			return nil
 		},
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
@@ -56,14 +57,14 @@ func versionCommand() *cobra.Command {
 	return cmd
 }
 
-func runVersion(opts versionOptions) {
+func runVersion(opts versionOptions, dockerCli command.Cli) {
 	if opts.short {
-		fmt.Println(strings.TrimPrefix(internal.Version, "v"))
+		fmt.Fprintln(dockerCli.Out(), strings.TrimPrefix(internal.Version, "v"))
 		return
 	}
 	if opts.format == formatter.JSON {
-		fmt.Printf("{\"version\":%q}\n", internal.Version)
+		fmt.Fprintf(dockerCli.Out(), "{\"version\":%q}\n", internal.Version)
 		return
 	}
-	fmt.Println("Docker Compose version", internal.Version)
+	fmt.Fprintln(dockerCli.Out(), "Docker Compose version", internal.Version)
 }

cmd/compose/viz.go

@@ -0,0 +1,97 @@
+/*
+   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/cli/cli/command"
+	"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, dockerCli command.Cli, 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, dockerCli, 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, dockerCli command.Cli, backend api.Service, opts *vizOptions) error {
+	_, _ = fmt.Fprintln(os.Stderr, "viz command is EXPERIMENTAL")
+	project, err := opts.ToProject(dockerCli, 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,73 @@
+/*
+   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/cli/cli/command"
+	"github.com/docker/compose/v2/pkg/api"
+	"github.com/spf13/cobra"
+)
+
+type waitOptions struct {
+	*ProjectOptions
+
+	services []string
+
+	downProject bool
+}
+
+func waitCommand(p *ProjectOptions, dockerCli command.Cli, 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, dockerCli, 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, dockerCli command.Cli, backend api.Service, opts *waitOptions) (int64, error) {
+	_, name, err := opts.projectOrName(dockerCli)
+	if err != nil {
+		return 0, err
+	}
+
+	return backend.Wait(ctx, name, api.WaitOptions{
+		Services:                   opts.services,
+		DownProjectOnContainerExit: opts.downProject,
+	})
+}

cmd/compose/watch.go

@@ -19,43 +19,94 @@ package compose
 import (
 	"context"
 	"fmt"
-	"os"
 
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/compose/v2/internal/locker"
 	"github.com/docker/compose/v2/pkg/api"
+	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 )
 
 type watchOptions struct {
 	*ProjectOptions
 	quiet bool
+	noUp  bool
 }
 
-func watchCommand(p *ProjectOptions, backend api.Service) *cobra.Command {
-	opts := watchOptions{
+func watchCommand(p *ProjectOptions, dockerCli command.Cli, backend api.Service) *cobra.Command {
+	watchOpts := watchOptions{
+		ProjectOptions: p,
+	}
+	buildOpts := buildOptions{
 		ProjectOptions: p,
 	}
 	cmd := &cobra.Command{
 		Use:   "watch [SERVICE...]",
-		Short: "EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated",
+		Short: "Watch build context for service and rebuild/refresh containers when files are updated",
 		PreRunE: Adapt(func(ctx context.Context, args []string) error {
 			return nil
 		}),
-		RunE: Adapt(func(ctx context.Context, args []string) error {
-			return runWatch(ctx, backend, opts, args)
+		RunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
+			if cmd.Parent().Name() == "alpha" {
+				logrus.Warn("watch command is now available as a top level command")
+			}
+			return runWatch(ctx, dockerCli, backend, watchOpts, buildOpts, args)
 		}),
-		ValidArgsFunction: completeServiceNames(p),
+		ValidArgsFunction: completeServiceNames(dockerCli, p),
 	}
 
-	cmd.Flags().BoolVar(&opts.quiet, "quiet", false, "hide build output")
+	cmd.Flags().BoolVar(&watchOpts.quiet, "quiet", false, "hide build output")
+	cmd.Flags().BoolVar(&watchOpts.noUp, "no-up", false, "Do not build & start services before watching")
 	return cmd
 }
 
-func runWatch(ctx context.Context, backend api.Service, opts watchOptions, services []string) error {
-	fmt.Fprintln(os.Stderr, "watch command is EXPERIMENTAL")
-	project, err := opts.ToProject(nil)
+func runWatch(ctx context.Context, dockerCli command.Cli, backend api.Service, watchOpts watchOptions, buildOpts buildOptions, services []string) error {
+	project, err := watchOpts.ToProject(dockerCli, nil)
 	if err != nil {
 		return err
 	}
 
-	return backend.Watch(ctx, project, services, api.WatchOptions{})
+	if err := applyPlatforms(project, true); err != nil {
+		return err
+	}
+
+	build, err := buildOpts.toAPIBuildOptions(nil)
+	if err != nil {
+		return err
+	}
+
+	// validation done -- ensure we have the lockfile for this project before doing work
+	l, err := locker.NewPidfile(project.Name)
+	if err != nil {
+		return fmt.Errorf("cannot take exclusive lock for project %q: %w", project.Name, err)
+	}
+	if err := l.Lock(); err != nil {
+		return fmt.Errorf("cannot take exclusive lock for project %q: %w", project.Name, err)
+	}
+
+	if !watchOpts.noUp {
+		upOpts := api.UpOptions{
+			Create: api.CreateOptions{
+				Build:                &build,
+				Services:             services,
+				RemoveOrphans:        false,
+				Recreate:             api.RecreateDiverged,
+				RecreateDependencies: api.RecreateNever,
+				Inherit:              true,
+				QuietPull:            watchOpts.quiet,
+			},
+			Start: api.StartOptions{
+				Project:     project,
+				Attach:      nil,
+				CascadeStop: false,
+				Services:    services,
+			},
+		}
+		if err := backend.Up(ctx, project, upOpts); err != nil {
+			return err
+		}
+	}
+	return backend.Watch(ctx, project, services, api.WatchOptions{
+		Build: build,
+	})
 }

cmd/formatter/container.go

@@ -0,0 +1,281 @@
+/*
+   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 formatter
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/docker/cli/cli/command/formatter"
+	"github.com/docker/compose/v2/pkg/api"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/pkg/stringid"
+	"github.com/docker/go-units"
+)
+
+const (
+	defaultContainerTableFormat = "table {{.Name}}\t{{.Image}}\t{{.Command}}\t{{.Service}}\t{{.RunningFor}}\t{{.Status}}\t{{.Ports}}"
+
+	nameHeader       = "NAME"
+	serviceHeader    = "SERVICE"
+	commandHeader    = "COMMAND"
+	runningForHeader = "CREATED"
+	mountsHeader     = "MOUNTS"
+	localVolumes     = "LOCAL VOLUMES"
+	networksHeader   = "NETWORKS"
+)
+
+// NewContainerFormat returns a Format for rendering using a Context
+func NewContainerFormat(source string, quiet bool, size bool) formatter.Format {
+	switch source {
+	case formatter.TableFormatKey, "": // table formatting is the default if none is set.
+		if quiet {
+			return formatter.DefaultQuietFormat
+		}
+		format := defaultContainerTableFormat
+		if size {
+			format += `\t{{.Size}}`
+		}
+		return formatter.Format(format)
+	case formatter.RawFormatKey:
+		if quiet {
+			return `container_id: {{.ID}}`
+		}
+		format := `container_id: {{.ID}}
+image: {{.Image}}
+command: {{.Command}}
+created_at: {{.CreatedAt}}
+state: {{- pad .State 1 0}}
+status: {{- pad .Status 1 0}}
+names: {{.Names}}
+labels: {{- pad .Labels 1 0}}
+ports: {{- pad .Ports 1 0}}
+`
+		if size {
+			format += `size: {{.Size}}\n`
+		}
+		return formatter.Format(format)
+	default: // custom format
+		if quiet {
+			return formatter.DefaultQuietFormat
+		}
+		return formatter.Format(source)
+	}
+}
+
+// ContainerWrite renders the context for a list of containers
+func ContainerWrite(ctx formatter.Context, containers []api.ContainerSummary) error {
+	render := func(format func(subContext formatter.SubContext) error) error {
+		for _, container := range containers {
+			err := format(&ContainerContext{trunc: ctx.Trunc, c: container})
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	return ctx.Write(NewContainerContext(), render)
+}
+
+// ContainerContext is a struct used for rendering a list of containers in a Go template.
+type ContainerContext struct {
+	formatter.HeaderContext
+	trunc bool
+	c     api.ContainerSummary
+
+	// FieldsUsed is used in the pre-processing step to detect which fields are
+	// used in the template. It's currently only used to detect use of the .Size
+	// field which (if used) automatically sets the '--size' option when making
+	// the API call.
+	FieldsUsed map[string]interface{}
+}
+
+// NewContainerContext creates a new context for rendering containers
+func NewContainerContext() *ContainerContext {
+	containerCtx := ContainerContext{}
+	containerCtx.Header = formatter.SubHeaderContext{
+		"ID":         formatter.ContainerIDHeader,
+		"Name":       nameHeader,
+		"Service":    serviceHeader,
+		"Image":      formatter.ImageHeader,
+		"Command":    commandHeader,
+		"CreatedAt":  formatter.CreatedAtHeader,
+		"RunningFor": runningForHeader,
+		"Ports":      formatter.PortsHeader,
+		"State":      formatter.StateHeader,
+		"Status":     formatter.StatusHeader,
+		"Size":       formatter.SizeHeader,
+		"Labels":     formatter.LabelsHeader,
+	}
+	return &containerCtx
+}
+
+// MarshalJSON makes ContainerContext implement json.Marshaler
+func (c *ContainerContext) MarshalJSON() ([]byte, error) {
+	return formatter.MarshalJSON(c)
+}
+
+// ID returns the container's ID as a string. Depending on the `--no-trunc`
+// option being set, the full or truncated ID is returned.
+func (c *ContainerContext) ID() string {
+	if c.trunc {
+		return stringid.TruncateID(c.c.ID)
+	}
+	return c.c.ID
+}
+
+func (c *ContainerContext) Name() string {
+	return c.c.Name
+}
+
+// Names returns a comma-separated string of the container's names, with their
+// slash (/) prefix stripped. Additional names for the container (related to the
+// legacy `--link` feature) are omitted.
+func (c *ContainerContext) Names() string {
+	names := formatter.StripNamePrefix(c.c.Names)
+	if c.trunc {
+		for _, name := range names {
+			if len(strings.Split(name, "/")) == 1 {
+				names = []string{name}
+				break
+			}
+		}
+	}
+	return strings.Join(names, ",")
+}
+
+func (c *ContainerContext) Service() string {
+	return c.c.Service
+}
+
+func (c *ContainerContext) Image() string {
+	return c.c.Image
+}
+
+func (c *ContainerContext) Command() string {
+	command := c.c.Command
+	if c.trunc {
+		command = formatter.Ellipsis(command, 20)
+	}
+	return strconv.Quote(command)
+}
+
+func (c *ContainerContext) CreatedAt() string {
+	return time.Unix(c.c.Created, 0).String()
+}
+
+func (c *ContainerContext) RunningFor() string {
+	createdAt := time.Unix(c.c.Created, 0)
+	return units.HumanDuration(time.Now().UTC().Sub(createdAt)) + " ago"
+}
+
+func (c *ContainerContext) ExitCode() int {
+	return c.c.ExitCode
+}
+
+func (c *ContainerContext) State() string {
+	return c.c.State
+}
+
+func (c *ContainerContext) Status() string {
+	return c.c.Status
+}
+
+func (c *ContainerContext) Health() string {
+	return c.c.Health
+}
+
+func (c *ContainerContext) Publishers() api.PortPublishers {
+	return c.c.Publishers
+}
+
+func (c *ContainerContext) Ports() string {
+	var ports []types.Port
+	for _, publisher := range c.c.Publishers {
+		ports = append(ports, types.Port{
+			IP:          publisher.URL,
+			PrivatePort: uint16(publisher.TargetPort),
+			PublicPort:  uint16(publisher.PublishedPort),
+			Type:        publisher.Protocol,
+		})
+	}
+	return formatter.DisplayablePorts(ports)
+}
+
+// Labels returns a comma-separated string of labels present on the container.
+func (c *ContainerContext) Labels() string {
+	if c.c.Labels == nil {
+		return ""
+	}
+
+	var joinLabels []string
+	for k, v := range c.c.Labels {
+		joinLabels = append(joinLabels, fmt.Sprintf("%s=%s", k, v))
+	}
+	return strings.Join(joinLabels, ",")
+}
+
+// Label returns the value of the label with the given name or an empty string
+// if the given label does not exist.
+func (c *ContainerContext) Label(name string) string {
+	if c.c.Labels == nil {
+		return ""
+	}
+	return c.c.Labels[name]
+}
+
+// Mounts returns a comma-separated string of mount names present on the container.
+// If the trunc option is set, names can be truncated (ellipsized).
+func (c *ContainerContext) Mounts() string {
+	var mounts []string
+	for _, name := range c.c.Mounts {
+		if c.trunc {
+			name = formatter.Ellipsis(name, 15)
+		}
+		mounts = append(mounts, name)
+	}
+	return strings.Join(mounts, ",")
+}
+
+// LocalVolumes returns the number of volumes using the "local" volume driver.
+func (c *ContainerContext) LocalVolumes() string {
+	return fmt.Sprintf("%d", c.c.LocalVolumes)
+}
+
+// Networks returns a comma-separated string of networks that the container is
+// attached to.
+func (c *ContainerContext) Networks() string {
+	return strings.Join(c.c.Networks, ",")
+}
+
+// Size returns the container's size and virtual size (e.g. "2B (virtual 21.5MB)")
+func (c *ContainerContext) Size() string {
+	if c.FieldsUsed == nil {
+		c.FieldsUsed = map[string]interface{}{}
+	}
+	c.FieldsUsed["Size"] = struct{}{}
+	srw := units.HumanSizeWithPrecision(float64(c.c.SizeRw), 3)
+	sv := units.HumanSizeWithPrecision(float64(c.c.SizeRootFs), 3)
+
+	sf := srw
+	if c.c.SizeRootFs > 0 {
+		sf = fmt.Sprintf("%s (virtual %s)", srw, sv)
+	}
+	return sf
+}

cmd/formatter/formatter.go

@@ -23,8 +23,6 @@ import (
 	"strings"
 
 	"github.com/docker/compose/v2/pkg/api"
-
-	"github.com/pkg/errors"
 )
 
 // Print prints formatted lists in different formats
@@ -67,7 +65,7 @@ func Print(toJSON interface{}, format string, outWriter io.Writer, writerFn func
 			_, _ = fmt.Fprintln(outWriter, outJSON)
 		}
 	default:
-		return errors.Wrapf(api.ErrParsingFailed, "format value %q could not be parsed", format)
+		return fmt.Errorf("format value %q could not be parsed: %w", format, api.ErrParsingFailed)
 	}
 	return nil
 }

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, os.Args[1:])
+
 			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

@@ -13,7 +13,8 @@
 // limitations under the License.
 
 variable "GO_VERSION" {
-  default = "1.20.0"
+  # default ARG value set in Dockerfile
+  default = null
 }
 
 variable "BUILD_TAGS" {
@@ -24,15 +25,21 @@ 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
+target "meta-helper" {}
+
 target "_common" {
   args = {
     GO_VERSION = GO_VERSION
@@ -80,13 +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 -covermode=atomic"
+  }
+  output = [outdir("./bin/build")]
+  platforms = ["local"]
 }
 
 target "binary" {
   inherits = ["_common"]
   target = "binary"
-  output = [bindir("build")]
+  output = [outdir("./bin/build")]
   platforms = ["local"]
 }
 
@@ -110,7 +127,7 @@ target "binary-cross" {
 target "release" {
   inherits = ["binary-cross"]
   target = "release"
-  output = [bindir("release")]
+  output = [outdir("./bin/release")]
 }
 
 target "docs-validate" {
@@ -124,3 +141,8 @@ target "docs-update" {
   target = "docs-update"
   output = ["./docs"]
 }
+
+target "image-cross" {
+  inherits = ["meta-helper", "binary-cross"]
+  output = ["type=image"]
+}

docs/reference/compose.md

@@ -1,38 +1,40 @@
 # 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 |
-| [`create`](compose_create.md)   | Creates containers for a service.                                       |
-| [`down`](compose_down.md)       | Stop and remove containers, networks                                    |
-| [`events`](compose_events.md)   | Receive real time events from containers.                               |
-| [`exec`](compose_exec.md)       | Execute a command in a running container.                               |
-| [`images`](compose_images.md)   | List images used by the created containers                              |
-| [`kill`](compose_kill.md)       | Force stop service containers.                                          |
-| [`logs`](compose_logs.md)       | View output from containers                                             |
-| [`ls`](compose_ls.md)           | List running compose projects                                           |
-| [`pause`](compose_pause.md)     | Pause services                                                          |
-| [`port`](compose_port.md)       | Print the public port for a port binding.                               |
-| [`ps`](compose_ps.md)           | List containers                                                         |
-| [`pull`](compose_pull.md)       | Pull service images                                                     |
-| [`push`](compose_push.md)       | Push service images                                                     |
-| [`restart`](compose_restart.md) | Restart service containers                                              |
-| [`rm`](compose_rm.md)           | Removes stopped service containers                                      |
-| [`run`](compose_run.md)         | Run a one-off command on a service.                                     |
-| [`start`](compose_start.md)     | Start services                                                          |
-| [`stop`](compose_stop.md)       | Stop services                                                           |
-| [`top`](compose_top.md)         | Display the running processes                                           |
-| [`unpause`](compose_unpause.md) | Unpause services                                                        |
-| [`up`](compose_up.md)           | Create and start containers                                             |
-| [`version`](compose_version.md) | Show the Docker Compose version information                             |
+| Name                            | Description                                                                           |
+|:--------------------------------|:--------------------------------------------------------------------------------------|
+| [`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               |
+| [`create`](compose_create.md)   | Creates containers for a service.                                                     |
+| [`down`](compose_down.md)       | Stop and remove containers, networks                                                  |
+| [`events`](compose_events.md)   | Receive real time events from containers.                                             |
+| [`exec`](compose_exec.md)       | Execute a command in a running container.                                             |
+| [`images`](compose_images.md)   | List images used by the created containers                                            |
+| [`kill`](compose_kill.md)       | Force stop service containers.                                                        |
+| [`logs`](compose_logs.md)       | View output from containers                                                           |
+| [`ls`](compose_ls.md)           | List running compose projects                                                         |
+| [`pause`](compose_pause.md)     | Pause services                                                                        |
+| [`port`](compose_port.md)       | Print the public port for a port binding.                                             |
+| [`ps`](compose_ps.md)           | List containers                                                                       |
+| [`pull`](compose_pull.md)       | Pull service images                                                                   |
+| [`push`](compose_push.md)       | Push service images                                                                   |
+| [`restart`](compose_restart.md) | Restart service containers                                                            |
+| [`rm`](compose_rm.md)           | Removes stopped service containers                                                    |
+| [`run`](compose_run.md)         | Run a one-off command on a service.                                                   |
+| [`scale`](compose_scale.md)     | Scale services                                                                        |
+| [`start`](compose_start.md)     | Start services                                                                        |
+| [`stop`](compose_stop.md)       | Stop services                                                                         |
+| [`top`](compose_top.md)         | Display the running processes                                                         |
+| [`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                                         |
+| [`watch`](compose_watch.md)     | Watch build context for service and rebuild/refresh containers when files are updated |
 
 
 ### Options
@@ -41,10 +43,12 @@ Docker Compose
 |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
 | `--ansi`               | `string`      | `auto`  | Control when to print ANSI control characters ("never"\|"always"\|"auto")                           |
 | `--compatibility`      |               |         | Run compose in backward compatibility mode                                                          |
-| `--env-file`           | `string`      |         | Specify an alternate environment file.                                                              |
+| `--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                                                                                        |
 
@@ -53,7 +57,7 @@ Docker Compose
 
 ## Description
 
-You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
+You can use the compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
 multiple services in Docker containers.
 
 ### Use `-f` to specify the name and path of one or more Compose files
@@ -115,12 +119,19 @@ $ docker compose -f ~/sandbox/rails/compose.yaml pull db
 
 ### Use `-p` to specify a project name
 
-Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
-specify the flag, Compose uses the current directory name.
-Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
-
-Many Compose subcommands can be run without a Compose file by passing
-the project name.
+Each configuration has a project name. Compose sets the project name using
+the following mechanisms, in order of precedence:
+- The `-p` command line flag
+- The `COMPOSE_PROJECT_NAME` environment variable
+- The top level `name:` variable from the config file (or the last `name:`
+from a series of config files specified using `-f`)
+- The `basename` of the project directory containing the config file (or
+containing the first config file specified using `-f`)
+- The `basename` of the current directory if no config file is specified
+Project names must contain only lowercase letters, decimal digits, dashes,
+and underscores, and must begin with a lowercase letter or decimal digit. If
+the `basename` of the project directory or current directory violates this
+constraint, you must use one of the other mechanisms.
 
 ```console
 $ docker compose -p my_project ps -a
@@ -135,16 +146,16 @@ demo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
 ### Use profiles to enable optional services
 
 Use `--profile` to specify one or more active profiles
-Calling `docker compose --profile frontend up` will start the services with the profile `frontend` and services
+Calling `docker compose --profile frontend up` starts the services with the profile `frontend` and services
 without any specified profiles.
-You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.
+You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` is enabled.
 
 Profiles can also be set by `COMPOSE_PROFILES` environment variable.
 
 ### Configuring parallelism
 
 Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
-Calling `docker compose --parallel 1 pull` will pull the pullable images defined in the Compose file
+Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
 one at a time. This can also be used to control build concurrency.
 
 Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
@@ -160,5 +171,30 @@ and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag.
 
 If flags are explicitly set on the command line, the associated environment variable is ignored.
 
-Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
+Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops 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_dry-run.md

@@ -1,7 +1,7 @@
 # docker compose alpha dry-run
 
 <!---MARKER_GEN_START-->
-EXPERIMENTAL - Dry run command allow you to test a command without applying changes
+Dry run command allows you to test a command without applying changes.
 
 
 <!---MARKER_GEN_END-->

docs/reference/compose_alpha_publish.md

@@ -0,0 +1,15 @@
+# docker compose alpha publish
+
+<!---MARKER_GEN_START-->
+Publish compose application
+
+### Options
+
+| Name                      | Type | Default | Description                     |
+|:--------------------------|:-----|:--------|:--------------------------------|
+| `--dry-run`               |      |         | Execute command in dry run mode |
+| `--resolve-image-digests` |      |         | Pin image tags to digests.      |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/compose_alpha_scale.md

@@ -0,0 +1,15 @@
+# docker compose alpha scale
+
+<!---MARKER_GEN_START-->
+Scale services. 
+
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+| `--no-deps` |      |         | Don't start linked services    |
+
+
+<!---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

@@ -1,13 +1,15 @@
 # docker compose alpha watch
 
 <!---MARKER_GEN_START-->
-EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated
+Watch build context for service and rebuild/refresh containers when files are updated
 
 ### Options
 
-| Name      | Type | Default | Description       |
-|:----------|:-----|:--------|:------------------|
-| `--quiet` |      |         | hide build output |
+| Name        | Type | Default | Description                                   |
+|:------------|:-----|:--------|:----------------------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode               |
+| `--no-up`   |      |         | Do not build & start services before watching |
+| `--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.                      |
@@ -29,6 +31,6 @@ Parse, resolve and render compose file in canonical format
 
 ## Description
 
-`docker compose config` renders the actual data model to be applied on the Docker engine.
-it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
+`docker compose config` renders the actual data model to be applied on the Docker Engine.
+It merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
 the canonical format.

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

@@ -5,15 +5,16 @@ Creates containers for a service.
 
 ### Options
 
-| Name               | Type          | Default   | Description                                                                                   |
-|:-------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------|
-| `--build`          |               |           | Build images before starting containers.                                                      |
-| `--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.         |
-| `--pull`           | `string`      | `missing` | Pull image before running ("always"\|"missing"\|"never")                                      |
-| `--remove-orphans` |               |           | Remove containers for services not defined in the Compose file.                               |
-| `--scale`          | `stringArray` |           | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. |
+| 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 policy.                                                    |
+| `--no-recreate`    |               |          | If containers already exist, don't recreate them. Incompatible with --force-recreate.         |
+| `--pull`           | `string`      | `policy` | Pull image before running ("always"\|"missing"\|"never"\|"build")                             |
+| `--remove-orphans` |               |          | Remove containers for services not defined in the Compose file.                               |
+| `--scale`          | `stringArray` |          | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present. |
 
 
 <!---MARKER_GEN_END-->

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-->
@@ -21,12 +22,12 @@ Stops containers and removes containers, networks, volumes, and images created b
 
 By default, the only things removed are:
 
-- Containers for services defined in the Compose file
-- Networks defined in the networks section of the Compose file
-- The default network, if one is used
+- Containers for services defined in the Compose file.
+- Networks defined in the networks section of the Compose file.
+- The default network, if one is used.
 
 Networks and volumes defined as external are never removed.
 
-Anonymous volumes are not removed by default. However, as they don’t have a stable name, they will not be automatically
+Anonymous volumes are not removed by default. However, as they don’t have a stable name, they are not automatically
 mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or
 named volumes.

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

@@ -5,14 +5,16 @@ List containers
 
 ### Options
 
-| Name                  | Type          | Default | Description                                                                                                   |
-|:----------------------|:--------------|:--------|:--------------------------------------------------------------------------------------------------------------|
-| `-a`, `--all`         |               |         | Show all stopped containers (including those created by the run command)                                      |
-| [`--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                                                                                              |
-| `--services`          |               |         | Display services                                                                                              |
-| [`--status`](#status) | `stringArray` |         | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited] |
+| 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 output using a custom template:<br>'table':            Print output in table format with column headers (default)<br>'table TEMPLATE':   Print output in table format using the given Go template<br>'json':             Print in JSON format<br>'TEMPLATE':         Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
+| `--no-trunc`          |               |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `-q`, `--quiet`       |               |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--services`          |               |         | Display services                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`--status`](#status) | `stringArray` |         | Filter services by status. Values: [paused \| restarting \| removing \| running \| dead \| created \| exited]                                                                                                                                                                                                                                                                                                                        |
 
 
 <!---MARKER_GEN_END-->
@@ -27,7 +29,7 @@ NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS
 example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
 ```
 
-By default, only running containers are shown. `--all` flag can be used to include stopped containers
+By default, only running containers are shown. `--all` flag can be used to include stopped containers.
 
 ```console
 $ docker compose ps --all
@@ -51,7 +53,7 @@ $ docker compose ps --format json
 ```
 
 The JSON output allows you to use the information in other tools for further
-processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/){:target="_blank" rel="noopener" class="_"}
+processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/)
 to pretty-print the JSON:
 
 ```console

docs/reference/compose_pull.md

@@ -5,12 +5,14 @@ Pull service images
 
 ### Options
 
-| Name                     | Type | Default | Description                                             |
-|:-------------------------|:-----|:--------|:--------------------------------------------------------|
-| `--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.            |
-| `-q`, `--quiet`          |      |         | Pull without printing progress information.             |
+| 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.            |
+| `--policy`               | `string` |         | Apply pull policy ("missing"\|"always").                |
+| `-q`, `--quiet`          |          |         | Pull without printing progress information.             |
 
 
 <!---MARKER_GEN_END-->
@@ -23,7 +25,7 @@ those images.
 
 ## Examples
 
-suppose you have this `compose.yaml`:
+Consider the following `compose.yaml`:
 
 ```yaml
 services:
@@ -64,5 +66,4 @@ $ docker compose pull db
    ⠹ c8752d5b785c Waiting                                                  9.3s
 ```
 
-`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
+`docker compose pull` tries to pull image for services with a build section. If pull fails, it lets you know this service image must be built. You can skip this by setting `--ignore-buildable` flag.

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,7 +7,9 @@ Restart service containers
 
 | Name              | Type  | Default | Description                           |
 |:------------------|:------|:--------|:--------------------------------------|
-| `-t`, `--timeout` | `int` | `10`    | Specify a shutdown timeout in seconds |
+| `--dry-run`       |       |         | Execute command in dry run mode       |
+| `--no-deps`       |       |         | Don't restart dependent services.     |
+| `-t`, `--timeout` | `int` | `0`     | Specify a shutdown timeout in seconds |
 
 
 <!---MARKER_GEN_END-->
@@ -21,6 +23,6 @@ after running this command. For example, changes to environment variables (which
 after a container is built, but before the container's command is executed) are not updated
 after restarting.
 
-If you are looking to configure a service's restart policy, please refer to
+If you are looking to configure a service's restart policy, refer to
 [restart](https://github.com/compose-spec/compose-spec/blob/master/spec.md#restart)
 or [restart_policy](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#restart_policy).

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_scale.md

@@ -0,0 +1,15 @@
+# docker compose scale
+
+<!---MARKER_GEN_START-->
+Scale services 
+
+### Options
+
+| Name        | Type | Default | Description                     |
+|:------------|:-----|:--------|:--------------------------------|
+| `--dry-run` |      |         | Execute command in dry run mode |
+| `--no-deps` |      |         | Don't start linked services.    |
+
+
+<!---MARKER_GEN_END-->
+

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,31 +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.            |
-| `-t`, `--timeout`            | `int`         | `10`      | 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.                                         |
+| 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` |          | Restrict attaching to the specified services. Incompatible with --attach-dependencies.                   |
+| `--attach-dependencies`      |               |          | Automatically attach to log output of dependent services.                                                |
+| `--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` |          | Do not attach (stream logs) to the specified services.                                                   |
+| `--no-build`                 |               |          | Don't build an image, even if it's policy.                                                               |
+| `--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`      | `policy` | 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`      | Maximum duration to wait for the project 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/compose_watch.md

@@ -0,0 +1,16 @@
+# docker compose watch
+
+<!---MARKER_GEN_START-->
+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               |
+| `--no-up`   |      |         | Do not build & start services before watching |
+| `--quiet`   |      |         | hide build output                             |
+
+
+<!---MARKER_GEN_END-->
+

docs/reference/docker_compose.yaml

@@ -1,7 +1,7 @@
 command: docker compose
 short: Docker Compose
 long: |-
-    You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
+    You can use the compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
     multiple services in Docker containers.
 
     ### Use `-f` to specify the name and path of one or more Compose files
@@ -63,12 +63,19 @@ long: |-
 
     ### Use `-p` to specify a project name
 
-    Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
-    specify the flag, Compose uses the current directory name.
-    Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
-
-    Many Compose subcommands can be run without a Compose file by passing
-    the project name.
+    Each configuration has a project name. Compose sets the project name using
+    the following mechanisms, in order of precedence:
+    - The `-p` command line flag
+    - The `COMPOSE_PROJECT_NAME` environment variable
+    - The top level `name:` variable from the config file (or the last `name:`
+    from a series of config files specified using `-f`)
+    - The `basename` of the project directory containing the config file (or
+    containing the first config file specified using `-f`)
+    - The `basename` of the current directory if no config file is specified
+    Project names must contain only lowercase letters, decimal digits, dashes,
+    and underscores, and must begin with a lowercase letter or decimal digit. If
+    the `basename` of the project directory or current directory violates this
+    constraint, you must use one of the other mechanisms.
 
     ```console
     $ docker compose -p my_project ps -a
@@ -83,16 +90,16 @@ long: |-
     ### Use profiles to enable optional services
 
     Use `--profile` to specify one or more active profiles
-    Calling `docker compose --profile frontend up` will start the services with the profile `frontend` and services
+    Calling `docker compose --profile frontend up` starts the services with the profile `frontend` and services
     without any specified profiles.
-    You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.
+    You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` is enabled.
 
     Profiles can also be set by `COMPOSE_PROFILES` environment variable.
 
     ### Configuring parallelism
 
     Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
-    Calling `docker compose --parallel 1 pull` will pull the pullable images defined in the Compose file
+    Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
     one at a time. This can also be used to control build concurrency.
 
     Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
@@ -108,8 +115,33 @@ long: |-
 
     If flags are explicitly set on the command line, the associated environment variable is ignored.
 
-    Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
+    Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops 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
@@ -133,12 +165,15 @@ cname:
     - docker compose restart
     - docker compose rm
     - docker compose run
+    - docker compose scale
     - docker compose start
     - docker compose stop
     - docker compose top
     - docker compose unpause
     - docker compose up
     - docker compose version
+    - docker compose wait
+    - docker compose watch
 clink:
     - docker_compose_build.yaml
     - docker_compose_config.yaml
@@ -159,12 +194,15 @@ clink:
     - docker_compose_restart.yaml
     - docker_compose_rm.yaml
     - docker_compose_run.yaml
+    - docker_compose_scale.yaml
     - docker_compose_start.yaml
     - docker_compose_stop.yaml
     - docker_compose_top.yaml
     - docker_compose_unpause.yaml
     - docker_compose_up.yaml
     - docker_compose_version.yaml
+    - docker_compose_wait.yaml
+    - docker_compose_watch.yaml
 options:
     - option: ansi
       value_type: string
@@ -192,13 +230,14 @@ options:
       default_value: "false"
       description: Execute command in dry run mode
       deprecated: false
-      hidden: true
+      hidden: false
       experimental: false
       experimentalcli: false
       kubernetes: false
       swarm: false
     - option: env-file
-      value_type: string
+      value_type: stringArray
+      default_value: '[]'
       description: Specify an alternate environment file.
       deprecated: false
       hidden: false
@@ -247,6 +286,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: |-
@@ -302,6 +351,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,35 @@
+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
+options:
+    - option: resolve-image-digests
+      value_type: bool
+      default_value: "false"
+      description: Pin image tags to digests.
+      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_scale.yaml

@@ -0,0 +1,35 @@
+command: docker compose alpha scale
+short: Scale services
+long: Scale services
+usage: docker compose alpha scale [SERVICE=REPLICAS...]
+pname: docker compose alpha
+plink: docker_compose_alpha.yaml
+options:
+    - option: no-deps
+      value_type: bool
+      default_value: "false"
+      description: Don't start linked services.
+      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_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
+