Git Worktree Identity & Isolation
Relevant source files
The following files were used as context for generating this wiki page:
Docktree provides a mechanism for running Docker Compose services across multiple Git worktrees without resource collisions. It achieves this by ensuring that each worktree has a unique identity, isolated networking, and dedicated port allocations. This isolation allows developers (and AI agents) to spin up independent stacks for different branches on the same host.
The system relies on three primary pillars of isolation:
- Project Identity: Generating stable, unique Docker Compose project names based on repository and branch metadata.
- Resource Allocation: Dynamically mapping host ports and isolating container names and volumes.
- Tiered Architecture: Separating worktree-specific services from repo-scoped "platform" services (like shared databases).
Sources: README.md:3-10, internal/cli/up.go:102-120
Worktree Identification and Naming
Docktree determines the identity of a runtime instance by inspecting the Git state of the current directory. It distinguishes between the "Main Repo Root" (where the primary .git directory and docktree.yml configuration reside) and the "Worktree Root" (the specific checkout directory).
Instance Name Generation
The InstanceName function creates a Docker-safe, 64-character limited project name. It combines the slugified repository name and worktree/branch name with a 6-character SHA1 hash derived from the absolute paths of the repo and worktree. This ensures that even if two worktrees have the same branch name but different paths, they will not collide.
The diagram above shows how Git metadata and file system paths are transformed into a unique project identifier.
Sources: internal/git/identity.go:81-103, internal/git/identity.go:169-183
Worktree Path Resolution
When creating new worktrees via docktree create, the system uses a template-based approach to determine the file system location.
| Variable | Description |
|---|---|
${repo} | The base name of the repository |
${branch} | The Git branch name |
${branch_slug} | A filesystem-safe, slugified version of the branch name |
Sources: internal/cli/worktree.go:94-115, internal/config/config.go:117
Resource Isolation Mechanics
Docktree achieves technical isolation by generating dynamic overrides for standard Docker Compose files.
Port Allocation
To prevent host port collisions, Docktree manages a local port registry. During the up process, it scans the project for requested ports and allocates available host ports from a configurable range (default 41000-49999).
- Registry Lock: Prevents race conditions during concurrent
upcommands. - Allocation: Maps container ports to unique host ports.
- Override Generation: Writes a
.docktree/generated/<instance>.override.ymlcontaining the new port mappings.
Sources: internal/cli/up.go:189-225, internal/config/config.go:127-131
Volume and Network Isolation
By default, Docker volumes are isolated per worktree. However, Docktree supports "Shared Volumes" through configuration, allowing specific data to persist across different worktrees while keeping the runtime environment separate.
The diagram illustrates how services in different worktrees maintain their own volumes while optionally sharing specific global resources defined in volumes.share.
Sources: internal/config/config.go:88-90, internal/cli/up.go:174-180
Shared Platform Tier
For heavy services like databases (Postgres, MySQL, MongoDB), Docktree provides a "Platform Tier." This allows a single repository-scoped instance of a service to serve multiple worktrees.
Tenancy Models
Isolation within the shared platform is managed via tenancy settings in docktree.yml:
- full_share: All worktrees connect to the exact same service instance and database.
- per_database: Docktree provisions a unique logical database (tenant) within the shared service for each worktree and rewrites connection strings (e.g.,
DATABASE_URL) in the worktree containers.
Networking and DNS
Platform services are attached to a dedicated external network named docktree-platform-<repo-slug>-net. Worktree services are automatically joined to this network during synthesis, allowing them to reach shared services using the service names as DNS aliases.
Sources: internal/compose/platform.go:18-26, internal/compose/platform.go:142-160, internal/config/config.go:58-69
Configuration and State
Isolation settings are primarily controlled via the docktree.yml file, while runtime state is maintained in a local .docktree directory.
Isolation Configuration
ports:
bind_host: "127.0.0.1"
range: "41000-49999"
volumes:
share:
- cache-data # Persistent across worktrees
state:
directory: ".docktree"
Sources: internal/config/config.go:113-140, README.md:73-86
State Directory Hierarchy
The state directory (default .docktree) contains the generated artifacts that define a worktree's isolated identity:
state.json: Metadata about the current instance (branch, hash, ports).generated/<instance>.override.yml: The primary isolation override.generated/<instance>.clear.yml: Used to clear existing port definitions from base files.
Sources: internal/cli/up.go:230-245, internal/cli/worktree.go:187-195
Conclusion
Git Worktree Identity & Isolation in Docktree is a multi-layered system that transforms standard Docker Compose definitions into worktree-aware deployments. By combining cryptographic identity generation, dynamic port management, and sophisticated service synthesis for shared platforms, it ensures that local development environments remain entirely independent and collision-free across multiple concurrent branches.