Configuration Reference (docktree.yml)

Relevant source files

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

• internal/config/config.go
• internal/cli/init.go
• internal/cli/up.go
• internal/cli/worktree.go
• README.md
• internal/config/config_test.go

The docktree.yml file is the central configuration hub for Docktree projects. Its primary purpose is to define how Docker Compose services should be isolated and managed across multiple git worktrees. By specifying project-level overrides, it enables features like automatic port allocation, shared database provisioning, and setup automation (copying .env files or symlinking node_modules).

This configuration allows Docktree to wrap standard docker compose commands, transforming them to use unique project names, container names, and networks for each worktree. While Docktree can function without this file using built-in defaults, docktree.yml is required for advanced features such as the shared platform tier and custom volume sharing.

Sources: internal/config/config.go:12-22, README.md:65-71

Configuration Structure

The configuration is organized into several functional blocks. The following diagram illustrates the high-level hierarchy of the Config struct used by the application to parse the YAML file.

The application uses a merging strategy where user-defined values in docktree.yml overwrite the default settings provided by the project plan.

Sources: internal/config/config.go:12-22, internal/config/config.go:133-157

Sectional Reference

Compose

The compose section defines the entry points for Docker Compose.

Field	Type	Default	Description
files	[]string	nil (Auto-detect)	List of paths to Compose files relative to the repo root.

Sources: internal/config/config.go:25-27, internal/config/config.go:104

Setup

The setup block automates worktree preparation steps, which are executed during docktree prepare or docktree up --sync.

Field	Type	Default	Description
copy	[]string	[".env"]	Files to copy from the main repo root to the worktree root.
symlink	[]string	["node_modules"]	Directories or files to symlink from the main repo to the worktree.
run	[]string	nil	Shell commands to execute in the worktree root during setup.

Sources: internal/config/config.go:37-41, internal/config/config.go:111-114

Ports

Docktree provides dynamic port allocation to prevent host-port collisions between worktrees.

Field	Type	Default	Description
mode	string	"dynamic"	Port allocation strategy.
bind_host	string	"127.0.0.1"	The host interface to bind published ports to.
range	string	"41000-49999"	Range of host ports available for allocation.

Sources: internal/config/config.go:90-94, internal/config/config.go:117-121

Shared Services

Shared services represent the "platform tier"—services that run once per repository rather than once per worktree (e.g., a shared PostgreSQL instance).

Shared Service Properties

Field	Type	Description
kind	string	Type of service (e.g., postgres, mysql, mongodb, redis, s3).
tenancy	string	Isolation mode: full_share (all use same data) or per_database.
url_envs	[]string	Environment variables (like DATABASE_URL) to rewrite with tenant credentials.
template	string	(Postgres only) Database to use as a template when creating tenant DBs.

Sources: internal/config/config.go:50-65, internal/cli/up.go:110-123

Volumes

By default, Docktree isolates all volumes by prefixing them with the worktree's unique project name. The volumes section allows for explicit sharing.

Field	Type	Description
share	[]string	Names of named volumes in the Compose file that should be shared across all worktrees.

Sources: internal/config/config.go:86-88, README.md:104-106

Transforms and State

These sections control internal behavior and naming conventions.

• Transforms: Controls how the CLI modifies the Compose project. For example, container_name: strip removes hardcoded container names to allow Docker to generate unique ones per project.
• State: Defines the directory where Docktree stores generated overrides and tracking files (default: .docktree). This directory is automatically added to .gitignore.

Sources: internal/config/config.go:96-108, internal/cli/worktree.go:193-210

Validation and Defaults

Docktree enforces strict validation on the configuration to prevent runtime errors. For instance, the kind of a shared service must be one of the supported types, and the tenancy mode must be compatible with that kind.

// Valid kinds + tenancy combos from internal/config/config.go
var allowedTenancyByKind = map[string]map[string]bool{
	"postgres": {"per_database": true, "full_share": true},
	"mysql":    {"per_database": true, "full_share": true},
	"mongodb":  {"per_database": true, "full_share": true},
	"redis":    {"full_share": true},
	"s3":       {"full_share": true},
	"generic":  {"full_share": true},
}

Sources: internal/config/config.go:159-166, internal/config/config.go:183-195

Conclusion

The docktree.yml file provides a powerful declarative interface for managing complex development environments. By centralizing setup steps and isolation logic, it ensures that developers and AI agents can spin up reproducible, collision-free environments across any number of git worktrees. Significant changes to this file should be validated using docktree up --validate to ensure the integrity of port ranges and shared service configurations.

Sources: internal/cli/up.go:278-285