If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/docker/compose shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 24+ active contributors
• Distributed ownership (top contributor 21% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live docker/compose repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/docker/compose.

What it runs against: a local clone of docker/compose — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in docker/compose | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of docker/compose. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/docker/compose.git
#   cd compose
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of docker/compose and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "docker/compose(\\.git)?\\b" \\
  && ok "origin remote is docker/compose" \\
  || miss "origin remote is not docker/compose (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/main.go" \\
  && ok "cmd/main.go" \\
  || miss "missing critical file: cmd/main.go"
test -f "cmd/compose/compose.go" \\
  && ok "cmd/compose/compose.go" \\
  || miss "missing critical file: cmd/compose/compose.go"
test -f "cmd/compose/up.go" \\
  && ok "cmd/compose/up.go" \\
  || miss "missing critical file: cmd/compose/up.go"
test -f "cmd/compose/options.go" \\
  && ok "cmd/compose/options.go" \\
  || miss "missing critical file: cmd/compose/options.go"
test -f "cmd/formatter/formatter.go" \\
  && ok "cmd/formatter/formatter.go" \\
  || miss "missing critical file: cmd/formatter/formatter.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/docker/compose"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Docker Compose is a Go CLI tool that orchestrates multi-container Docker applications by defining services, networks, and volumes in a single YAML compose file (following the compose-spec standard). Users run docker compose up to automatically create, configure, and start all services with networking and volume management baked in. Modular command structure under cmd/compose/ where each Docker Compose subcommand (up, down, build, exec, logs, etc.) has a dedicated file (compose.go is router, up.go, down.go, etc. are implementations). Core orchestration logic delegates to compose-go/v2 library for spec parsing; pkg/ likely contains shared business logic and service definitions.

DevOps engineers and application developers who need to spin up reproducible multi-container environments locally or in CI/CD pipelines without writing shell scripts—particularly those using Docker Desktop on Windows/macOS or deploying on Linux servers.

Highly mature and production-ready. The codebase shows 1.3M lines of Go with comprehensive CI workflows (.github/workflows/ci.yml, merge, PR review, scorecards), active dependabot management, and is bundled into Docker Desktop. The go.mod pins v2.10.2 of compose-spec/compose-go and v29.4.3 of docker/cli, indicating tight integration with official Docker tooling.

Low risk for core stability but moderate dependency surface: the project depends on docker/cli, moby/moby/client, containerd, and buildx—all heavy dependencies. No obvious single-maintainer risk given it's official Docker Inc. property. Breaking changes to compose-spec are possible but documented via GitHub releases and CHANGELOG.

Active development with CI-driven merge workflows and dependabot dependency bumps. The repo includes alpha commands (cmd/compose/alpha.go) suggesting experimental features in flight. .github/workflows/docs-upstream.yml suggests ongoing spec documentation syncing with compose-spec upstream.

git clone https://github.com/docker/compose.git && cd compose && make build (Makefile present at root). See BUILDING.md for detailed build steps. Requires Go 1.25.5 or compatible (see .go-version).

Daily commands: make build produces a docker-compose binary. For development: go run ./cmd/compose up -f docker-compose.yml. For running tests: go test ./... (test files follow *_test.go pattern throughout cmd/compose/).

• cmd/main.go — Entry point for the Docker Compose CLI; all command execution flows through here.
• cmd/compose/compose.go — Root command definition and orchestration logic; establishes the CLI structure and plugin system.
• cmd/compose/up.go — Core 'up' command implementation; defines the primary workflow for starting multi-container applications.
• cmd/compose/options.go — Shared CLI option parsing and validation; used across all commands for consistent flag handling.
• cmd/formatter/formatter.go — Central output formatting abstraction; handles display modes (JSON, plain, pretty) used by all commands.
• cmd/display/mode.go — Display mode dispatch logic; routes output rendering through appropriate formatter implementations.
• go.mod — Module dependencies; declares compose-spec, containerd, docker/cli, and buildx as critical runtime dependencies.

Add a New Compose Command

1. Create a new file in cmd/compose/ (e.g., mycommand.go) with a function matching pattern: func runMyCommand(ctx context.Context, backend api.Service) error (cmd/compose/mycommand.go)
2. Register the command in compose.go by adding a &cobra.Command{} entry to the root command's subcommands slice with proper Use, Short, RunE, and Flags definitions. (cmd/compose/compose.go)
3. Add common flags (project, compose file, env file) using cmd/compose/options.go helper functions like projectFlag() and composeFileFlag(). (cmd/compose/options.go)
4. Use cmd/formatter or cmd/display packages to format output; call formatter.NewFormatter() and use its Write() method for consistent output handling. (cmd/display/mode.go)
5. Write tests following the pattern in *_test.go files; leverage mock Docker API via the backend parameter (api.Service interface). (cmd/compose/compose_test.go)

Add a New Output Format

1. Create a new formatter implementation in cmd/formatter/ (e.g., formatter_myformat.go) that implements the formatter.Formatter interface. (cmd/formatter/formatter.go)
2. Implement required methods: Write(io.Writer, interface{}) error and SetTimestamp(bool), matching the pattern in formatter_json.go or formatter_pretty.go. (cmd/formatter/json.go)
3. Register the new format in cmd/display/mode.go by adding a case in the NewFormatter() or dispatch function to instantiate your custom formatter. (cmd/display/mode.go)
4. Add corresponding display mode constant to cmd/display/mode.go (e.g., const ModeMyFormat) and update the mode selection logic. (cmd/display/mode.go)
5. Test by writing unit tests in formatter_myformat_test.go following patterns in json_test.go and formatter_test.go. (cmd/formatter/formatter_test.go)

Add CLI Option Parsing for a Command

1. Define flag variable in your command file (e.g., var myFlag string = "") at package level. (cmd/compose/mycommand.go)
2. If the option is reusable across commands, add a helper function in cmd/compose/options.go (e.g., func myOptionFlag(cmd *cobra.Command)) that calls cmd.Flags().StringVar(). (cmd/compose/options.go)
3. In your command's cobra.Command.Run or PreRun, call the flag helper or directly read Flags().GetString() to retrieve the parsed value. (cmd/compose/mycommand.go)
4. Add validation logic in cmd/compose/options.go using the opts struct; leverage existing validators like validateProjectName() as a template. (cmd/compose/options.go)
5. Test parsing and validation in options_test.go or mycommand_test.go following patterns in the existing test files. (cmd/compose/options_test.go)

• Go 1.25.5 — Enables fast native binary compilation, cross-platform support (Windows, macOS, Linux), and minimal runtime footprint for distribution as single executable.
• Cobra CLI framework — Provides structured command-line parsing, automatic help generation, and subcommand routing used across all 40+ compose commands.
• compose-spec/compose-go/v2 — Parses and validates docker-compose.yml files; provides the canonical compose specification implementation and schema validation.
• docker/cli (SDK) — Interfaces with Docker daemon via gRPC and REST; handles container lifecycle, image operations, and network management.
• containerd/containerd/v2 — Low-level container runtime abstraction; enables direct container management and streaming logs without Docker daemon in some scenarios.
• docker/buildx — Extends compose build to support multi-platform image building (linux/amd64, linux/arm64, etc.) and advanced build features.

• Single monolithic CLI binary instead of plugin-based microservices

  • Why: Simplifies distribution, reduces deployment complexity, and ensures consistent behavior across all subcommands.
  • Consequence: Larger binary size (~100MB) and slower feature development cycles; must rebuild entire binary for each change.

• Synchronous command execution rather than background job queue

  • Why: Matches expected Unix tool behavior; users expect blocking calls and immediate feedback.
  • Consequence: Long operations (image builds, container startup) block the CLI; requires terminal timeout handling and progress indicators.

• Project isolation via project name / namespace rather than explicit workspace directories

  • Why: Keeps compose files portable and self-contained; aligns with Docker Compose spec.
  • Consequence: Users can accidentally interact with wrong project; requires explicit --project-name flags or .env file conventions.

• undefined

  • Why: undefined
  • Consequence: undefined

The project depends tightly on docker/cli v29.4.3 and moby/moby/client—version skew can cause runtime failures. Building requires a specific Go version pinned in .go-version; using a different version may cause subtle failures. The Makefile likely has implicit build targets; run make help or inspect Makefile to see all targets. Some tests may require a running Docker daemon (e.g., compose_oci_test.go name suggests OCI/Docker integration tests). Windows builds may have gotchas related to github.com/Microsoft/go-winio dependency.

• Compose Specification (Compose-Spec) — The YAML schema that defines services, networks, volumes, and build config; understanding spec versions is essential to know which features Compose implements
• Docker Plugin Architecture — Compose is deployed as a Docker CLI plugin (installed in ~/.docker/cli-plugins/); understanding plugin contracts and lifecycle is needed to debug integration issues
• OCI Image Spec & Container Runtimes — Compose delegates container execution to OCI-compliant runtimes via containerd; the compose_oci_test.go and containerd/v2 dependency show deep OCI integration
• Cobra CLI Framework (Command Structure) — Every subcommand in cmd/compose/ is a Cobra *Command struct with flags and args; understanding how Cobra routes commands and parses flags is essential for adding new subcommands
• Docker API Client Patterns (Moby) — Compose calls moby/moby/client to create containers, networks, and volumes; understanding image pull, container creation, and exec APIs is needed to fix container lifecycle bugs
• OpenTelemetry Tracing & OTLP — go.opentelemetry.io dependencies indicate Compose exports structured traces to observability backends; cmdtrace is likely used to debug command execution via trace spans
• File System Watches & Hot Reload (fsnotify) — tilt-dev/fsnotify and fsnotify/fsevents suggest Compose can watch for docker-compose.yml changes and auto-reload; understanding watch semantics is needed for file monitoring features

• compose-spec/compose-spec — The official specification that docker/compose implements; needed to understand spec compliance and contribute upstream changes
• docker/cli — The Docker CLI that Compose integrates with; Compose is a plugin that runs alongside docker commands
• moby/moby — The open-source Docker Engine; Compose orchestrates containers via moby's client API
• docker/compose-switch — Legacy compatibility layer that redirects old docker-compose (v1 Python) calls to the v2 Go implementation
• docker/buildx — Companion tool for building multi-platform images; Compose integrates with buildx for container builds in up/build commands

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for cmd/compose/options.go

The options.go file handles critical CLI flag parsing and validation, but only has a basic options_test.go. Given that pullOptions_test.go exists separately for pull command options, the main options file likely lacks coverage for complex flag combinations, type coercions, and edge cases. This is high-value because incorrect option parsing directly impacts user experience and can cause silent failures.

• [ ] Examine cmd/compose/options.go and cmd/compose/options_test.go to identify untested branches and flag combinations
• [ ] Add tests for edge cases: conflicting flags, missing required options, invalid type conversions
• [ ] Add integration tests for multi-command option inheritance and override behavior
• [ ] Run coverage reports to ensure >85% line coverage for options.go
• [ ] Document any discovered parsing ambiguities in test comments

Add integration tests for cmd/compose/hooks.go hook execution lifecycle

The hooks.go file (with basic hooks_test.go) implements pre/post command hooks - a critical feature for CI/CD pipelines. The existing test file appears minimal. Missing are: hook failure handling, parallel hook execution, hook environment variable injection, and hook execution order validation. These tests would prevent regressions in a frequently-used feature.

• [ ] Review cmd/compose/hooks.go and cmd/compose/hooks_test.go to identify coverage gaps
• [ ] Add tests for hook execution order (pre vs post), hook failure modes (exit codes, signal handling)
• [ ] Add tests for environment variable propagation to hooks and hook stdout/stderr capture
• [ ] Test hook timeout behavior and resource cleanup on hook failure
• [ ] Add tests for hook execution with containerized compose workflows

Add missing integration tests for cmd/compose/cp.go copy command edge cases

The cp.go command (file copy between host and containers) lacks a corresponding _test.go file, while other commands like exec.go, run.go, and attach.go have tests. This command handles complex path resolution, permission handling, and cross-platform path separator issues. Add tests for: relative vs absolute paths, symlink handling, permission preservation, and cross-platform edge cases (Windows vs Unix paths).

• [ ] Create cmd/compose/cp_test.go with TestCopy* test functions
• [ ] Add tests for path normalization: relative paths, absolute paths, ../ sequences, symlinks
• [ ] Add tests for permission preservation across host/container boundary
• [ ] Add tests for cross-platform path separators (Windows backslash vs Unix forward slash)
• [ ] Add tests for edge cases: empty files, large files, special characters in filenames
• [ ] Verify tests pass on both Windows and Linux (consider adding Windows-specific path tests)

• Add missing test coverage for cmd/compose/export.go and cmd/compose/generate.go—these commands exist but likely have minimal test files or gaps in scenario coverage
• Improve error messages in cmd/compose/config.go validation to show which compose-spec rule was violated, matching the pattern used in better Docker error messages
• Document the purpose and usage of cmd/cmdtrace/cmd_span.go and cmd/compatibility/convert.go in a new DEVELOPMENT_GUIDE.md section—these internal tools are undocumented

The Docker Compose codebase demonstrates reasonable security practices with proper dependency management and structured CI/CD workflows. However, there are moderate concerns regarding pre-release dependencies (secret-detector), telemetry endpoint security (OpenTelemetry OTLP), and Docker image pinning practices. The codebase would benefit from stricter image digest pinning, comprehensive TLS configuration for telemetry, and explicit security policy documentation. No critical vulnerabilities were identified in the provided analysis, but runtime configuration security (especially for sensitive data in telemetry) should be validated during code review.

• Medium · Use of Secret Detector Library Without Clear Documentation — go.mod - github.com/DefangLabs/secret-detector dependency. The codebase includes a dependency on 'DefangLabs/secret-detector' (v0.0.0-20250403165618-22662109213e), which appears to be a pre-release version with a commit hash. While the library itself is designed for security purposes (detecting secrets), the use of a pre-release version without clear versioning and documentation could introduce unexpected behavior changes. Additionally, the purpose of secret detection within Docker Compose should be carefully scoped to avoid false positives or performance issues. Fix: Evaluate whether the secret-detector library should use a stable release version. Ensure it's only used during development/pre-commit phases and not in production runtime. Add explicit documentation about its usage scope and update to a stable release version when available.
• Medium · OpenTelemetry OTLP Endpoints May Lack TLS Verification — go.mod - go.opentelemetry.io/otel/exporters dependencies. The codebase uses OpenTelemetry OTLP trace exporters (otlptrace and otlptracegrpc) for telemetry. If OTLP endpoints are not properly configured with TLS verification and authentication, sensitive trace data containing environment variables, service information, or container configurations could be sent to untrusted endpoints. Fix: Ensure all OTLP endpoint configurations require TLS verification. Implement proper authentication (mTLS or API key based) for trace exporters. Document secure configuration patterns and provide examples in the contributing guide.
• Medium · Dockerfile Multi-Stage Build Configuration Exposure — Dockerfile - Build arguments and FROM statements. The Dockerfile uses multiple build arguments (GO_VERSION, GOLANGCI_LINT_VERSION, etc.) and external base images. While documented, ensure that image pinning uses digests rather than tags to prevent unexpected base image changes from introducing vulnerabilities. Fix: Pin all base images using SHA256 digests instead of version tags. Document the process for updating base images and add automated checks to verify image provenance and signatures.
• Low · HTTP Used in Go Package Documentation Link — README.md - PkgGoDev badge. The README contains package documentation links that may use HTTP. While this is a minor issue for documentation links, it's good practice to use HTTPS exclusively. Fix: Verify all external links in documentation use HTTPS. Update any HTTP references to HTTPS equivalents.
• Low · Incomplete Code Review - Missing Security Policy Details — .github/SECURITY.md. .github/SECURITY.md exists but content was not provided in the analysis. Security policies should clearly document the vulnerability disclosure process and supported versions receiving security updates. Fix: Ensure SECURITY.md includes: vulnerability disclosure process, security contact information, supported versions with security updates, and responsible disclosure timeline expectations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.