Lifecycle Commands (up, down, stop)
Relevant source files
The following files were used as context for generating this wiki page:
The lifecycle commands in Docktree serve as a specialized wrapper around docker compose to facilitate isolated development environments across different Git worktrees. By managing port allocations, volume names, and container naming conventions, these commands ensure that multiple instances of the same project can run concurrently on a single host without resource collisions.
These commands orchestrate the state of a worktree-specific project, including the synthesis of dynamic Docker Compose overrides and the management of shared platform services. While up handles initialization and start-up, down and stop manage the cessation of services with varying degrees of resource cleanup.
Command Execution Flow
The cli.Run function acts as the entry point, determining whether to render human-readable text or machine-readable JSON based on global flags. Commands that involve long-running Docker operations, such as up and down, are wrapped with a progress printer when running in a TTY environment.
The up Command
The up command is the primary entry point for starting a worktree's environment. It performs a complex sequence of environment preparation, port registry locking, and Compose file synthesis before invoking the underlying Docker engine.
Initialization and Synthesis
The command first identifies the repository identity and loads the canonical configuration. If the --create flag is provided, it scaffolds a new worktree and prepares the environment. A critical step involves detecting shared.services in docktree.yml; if present, Docktree ensures the shared platform tier is running and generates a worktree-specific compose file that redirects consumer services to the shared platform instances.
Sources: internal/cli/up.go:34-110
Resource Allocation
Docktree utilizes a global port registry to prevent collisions. The up command acquires a lock on the registry, calculates required port mappings, and allocates available host ports within the configured range (default: 41000-49999).
Configuration Options
| Flag | Short | Description |
|---|---|---|
--file | -f | Use a specific Compose file instead of discovery. |
--build | Force rebuild of images with a build directive. | |
--create | Create and prepare a new worktree before starting. | |
--sync | Run setup copy/symlink/run steps before starting. | |
--validate | Check config and port validity without starting. | |
--dry-run | Show intended actions and override previews. |
Sources: internal/cli/help_doc.go:237-251
The down and stop Commands
While both commands halt running services, they differ in how they handle container removal and persistent data.
stop Logic
The stop command halts running containers but does not remove them. This is a passthrough to docker compose stop within the specific worktree context. It is designed for temporary pauses where the environment should remain intact for a quick restart.
Sources: internal/cli/help_doc.go:210-217, internal/cli/cli.go:55
down Logic
The down command stops and removes containers, networks, and images defined in the project. It offers more aggressive cleanup options:
- Default: Removes containers and networks.
--volumes(-v): Additionally drops per-worktree tenant databases and Docker volumes.--all(-a): Applies the command to all worktree instances discovered in the repository.
Sources: internal/cli/help_doc.go:151-164
Implementation via Passthrough
Several lifecycle commands are implemented as passthroughs to Docker Compose using the runComposePassthrough helper. This ensures that Docktree's project context (project name and file list) is correctly applied to standard Docker commands.
func runRestart(ctx *Context) (any, int, error) {
return runComposePassthrough(ctx, "restart", ctx.Args[1:], true, printRestartHelp)
}
func runStart(ctx *Context) (any, int, error) {
return runComposePassthrough(ctx, "start", ctx.Args[1:], true, printStartHelp)
}
Sources: internal/cli/compose_lifecycle.go:8-16
State and Rendering
After lifecycle changes, Docktree updates its internal state and global instance registry. The results are rendered based on the provided Context.
- UpResult: Contains information on allocated ports, synced files, and any environment warnings (e.g.,
.envconflicts). - DownResult: Reports which services were stopped and, if applicable, which tenant databases were dropped.
- Status Indicators: The renderer uses TUI components to show the state of services (Running, Paused, Partial, or Stopped).
Sources: internal/cli/render.go:28-100, internal/cli/render.go:167-200
Summary
The lifecycle commands provide a robust framework for managing ephemeral development environments. By automating the synthesis of Docker Compose overrides and managing a global port registry, Docktree allows developers to switch between Git worktrees seamlessly while maintaining total isolation of services and data.