Code Organization

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• internal/cli/up.go
• internal/cli/init.go
• internal/config/config.go
• internal/compose/platform.go
• internal/docker/cleanup.go

Docktree is a Go-based CLI tool designed to manage Docker Compose projects across multiple Git worktrees. Its primary goal is to prevent collisions in project names, host ports, and container names by providing isolation for each worktree while supporting shared infrastructure components.

The codebase is organized into a clear hierarchy that separates the CLI entry point, internal library logic (handling Git, Docker, and Compose), and infrastructure for testing and deployment. Library code is kept within the internal/ directory to enforce encapsulation, ensuring that external consumers cannot depend on implementation details.

Sources: CONTRIBUTING.md:46-52, README.md:3-9

Project Structure Overview

The repository follows a standard Go project layout, separating executable commands from reusable internal packages.

Directory	Description
cmd/docktree/	CLI entry point and main application initialization.
internal/	Core library code, including compose handling, port allocation, and CLI logic.
tests/	Integration and end-to-end smoke tests for concurrent operations.
testdata/	Static fixtures and sample compose files used by the test suite.
Formula/	Homebrew formula for distribution on macOS and Linux.
skills/	Documentation and configuration for AI agent integration.

Sources: CONTRIBUTING.md:46-52, README.md:16-24, skills/docktree/SKILL.md

Internal Architecture

The internal/ directory contains the bulk of the project's logic, further subdivided into specialized packages.

Package Responsibilities

• cli: Implements the command-line interface, argument parsing, and command execution logic (e.g., up, init, down).
• config: Defines the docktree.yml schema and handles loading, validation, and defaulting of project configurations.
• compose: Manages the synthesis of Compose files, including generating worktree-specific overrides and the shared platform tier.
• docker: Provides wrappers for Docker and Docker Compose execution, as well as resource discovery and cleanup.
• git: Handles repository detection and worktree metadata extraction.
• ports: Manages a registry for dynamic port allocation and locking to prevent collisions.
• setup: Handles environment synchronization (copying/symlinking files) between the main repository and worktrees.

Sources: CONTRIBUTING.md:46-52, internal/cli/up.go:19-35, internal/config/config.go:13-23

Dependency Flow

The following diagram illustrates how the CLI package interacts with specialized internal packages to orchestrate a worktree startup.

The diagram shows the CLI as the central orchestrator, delegating specific tasks like repository detection (Git), configuration loading (Config), and resource management (Compose, Ports) to specialized packages before ultimately interacting with external systems.

Sources: internal/cli/up.go:37-180, internal/cli/init.go:48-90

Configuration Management

The internal/config package defines the Config struct, which serves as the source of truth for Docktree's behavior. It manages the docktree.yml file, supporting a merge-based approach where user-provided values override defaults.

Key Configuration Structs

type Config struct {
    Compose    ComposeConfig   `yaml:"compose"`
    Setup      SetupConfig     `yaml:"setup"`
    Shared     SharedConfig    `yaml:"shared,omitempty"`
    Volumes    VolumeSetConfig `yaml:"volumes"`
    Ports      PortsConfig     `yaml:"ports"`
    Transforms TransformConfig `yaml:"transforms"`
    State      StateConfig     `yaml:"state"`
}

Sources: internal/config/config.go:13-23

Configuration Loading Flow

The sequence demonstrates the initialization process where default settings are layered with user-defined configurations from the disk and validated for consistency.

Sources: internal/config/config.go:121-143, internal/cli/up.go:50-55

Command Orchestration

The internal/cli package uses a specific execution pattern for each command. For instance, the runUp function in internal/cli/up.go follows a sequence of:

1. Identity Discovery: Detecting the repo and worktree context using commonIdentity().
2. Synthesis: Generating isolated Compose files via compose.SynthesizeWorktree.
3. Resource Allocation: Locking the port registry and allocating unique host ports.
4. Execution: Running docker compose up -d with generated override files.

Common Execution Context

The CLI uses a Context struct (defined in the cli package) to manage Stdout, Stderr, and Renderer (Human vs. JSON output) across different commands.

Sources: internal/cli/up.go:37-180, internal/cli/render.go:19-25

Resource Cleanup and Discovery

The internal/docker package contains specialized logic for identifying resources managed by Docktree. It uses Docker labels (e.g., docktree.managed=true) to filter containers, networks, and volumes.

Function	Package	Description
ListDocktreeProjects	docker	Scans Docker for containers with Docktree labels to identify active/stale projects.
RemoveProjectResources	docker	Deletes containers, networks, and volumes associated with a specific project name.
ListDocktreeVolumes	docker	Retrieves volumes associated with Docktree-managed instances.

Sources: internal/docker/cleanup.go:23-45, internal/docker/cleanup.go:66-96

Summary of Code Organization

The Docktree project is structured to ensure strict isolation between different worktree environments while maintaining a shared repo-scoped platform. By separating the CLI orchestration (internal/cli) from the core domain logic (internal/compose, internal/ports), the architecture remains modular and testable. The use of the internal/ directory prevents leakage of implementation details, enforcing a clear boundary for the tool's core functionality.

Sources: CONTRIBUTING.md:46-52, README.md:3-9