Docker Compose Passthrough
Relevant source files
The following files were used as context for generating this wiki page:
Docker Compose Passthrough is a mechanism within Docktree that allows users to run standard Docker Compose commands while automatically injecting the current worktree's specific context. This ensures that commands like logs, exec, or restart target the correct isolated project, volumes, and containers associated with a specific git worktree without requiring the user to manually specify project names or file paths.
The passthrough system serves as a bridge between the Docktree CLI and the underlying docker compose binary. While Docktree provides "native" commands (like up, down, and status) that return structured JSON, passthrough commands generally stream raw output directly from Docker to the terminal, maintaining the familiar Docker Compose experience.
Sources: internal/cli/compose_passthrough.go:13-43, README.md:38-42, skills/docktree/SKILL.md:31-34
Core Architecture and Execution Flow
The passthrough logic is centered around the runComposePassthrough function. This function performs the necessary environment discovery to locate the correct Git repository and Docktree configuration, then constructs a docker.ComposeCommand to be executed.
Execution Process
- Context Detection: The system detects the Git repository and worktree root to load the relevant
docktree.ymlconfiguration. - State Loading: It retrieves the current instance state (e.g., the auto-generated
ProjectName) from the.docktreestate directory. - File Resolution: It identifies the active Compose files, which may include original files, generated overrides, and port-clear files.
- Command Construction: It prepends the specific subcommand (e.g.,
logs) and appends any user-provided arguments to thedocker composeexecution string. - Execution: The command is executed via the
dockerpackage, streaming output tostdoutandstderr.
Sources: internal/cli/compose_passthrough.go:13-43, internal/cli/compose_helpers.go:214-220
The diagram shows the logical flow from a user inputting a passthrough command to the eventual execution of the underlying Docker binary.
Supported Passthrough Subcommands
Docktree categorizes commands into those it wraps with native logic and those it passes through. Passthrough commands do not support the global --json flag for machine-readable output of the command results themselves, as they return raw Docker output.
| Subcommand | Description | Function Reference |
|---|---|---|
logs | Fetch the logs of containers | runLogs |
exec | Execute a command in a running container | runExec |
run | Run a one-off command (defaults to --rm) | runComposeRun |
restart | Restart containers | runRestart |
start | Start services | runStart |
stop | Stop containers without removing | runStop |
pause | Pause services | runPause |
unpause | Unpause services | runUnpause |
kill | Kill containers | runKill |
rm | Remove stopped containers | runRm |
Sources: internal/cli/compose_passthrough.go:48-124, internal/cli/compose_lifecycle.go:8-32, internal/cli/help_doc.go:102-132
The docker Universal Passthrough
For subcommands or specific Docker Compose flags not explicitly wrapped by a Docktree helper function (e.g., scale or top), the docktree docker command acts as a universal passthrough. It pre-fills the project name and active compose files for any arbitrary Docker Compose command.
Sources: internal/cli/compose_passthrough.go:133-162, internal/cli/help_doc.go:107
Specialized Passthrough Logic
Some passthrough commands require specific mutations before execution to align with Docktree's isolation goals.
Run Command Handling
The run command is specialized in runComposeRun. It automatically injects the --rm flag to ensure that one-off containers created within a worktree are cleaned up immediately, preventing resource clutter. It also includes a helper, stripRunSeparator, to handle the -- argument separator commonly used in CLI tools.
Sources: internal/cli/compose_passthrough.go:62-108
Lifecycle Management
Commands like restart, pause, and kill are managed in internal/cli/compose_lifecycle.go. These functions are thin wrappers around runComposePassthrough that provide specific help text and ensure the command is executed within the worktree's project context.
The sequence diagram illustrates how Docktree intercepts a logs command, enriches it with project context, and delegates execution.
Conclusion
Docker Compose Passthrough is a critical component that allows Docktree to remain a "drop-in" replacement for standard workflows. By handling the complexities of project naming and file resolution behind the scenes, it allows developers and AI agents to interact with isolated worktree environments using the familiar Docker Compose CLI interface.