Init Command and Config Generation
Relevant source files
The following files were used as context for generating this wiki page:
The init command is the primary entry point for onboarding a project to Docktree. Its purpose is to scan an existing repository containing Docker Compose files, identify infrastructure components that can be shared across worktrees, and generate a docktree.yml configuration file. This automation reduces manual setup effort and ensures that project-specific isolation rules (such as unique ports and tenant databases) are correctly defined from the start.
Sources: internal/cli/init.go:1-24, skills/docktree-init/SKILL.md:1-10
Initialization Workflow
The initialization process follows a structured pipeline: repository detection, environment scanning, candidate identification, and proposal generation. The command supports multiple execution modes, including a non-destructive dry-run and an interactive application mode designed for AI agents or automated scripts.
Execution Modes
The init command behavior is controlled by several flags:
- Default: Generates a
docktree.yml.proposedfile containing a suggested configuration. --dry-run: Prints the proposed configuration directly to stdout without writing any files.--force: Overwrites an existingdocktree.ymland uses candidate defaults directly.--apply: Consumes a JSON payload fromstdinto resolve configuration decisions and write the finaldocktree.yml.
Sources: internal/cli/init.go:26-54, internal/cli/init.go:119-150
Logic Flow
The following diagram illustrates the internal logic of the runInit function as it processes a repository.
This diagram represents the sequential steps taken to analyze the project and generate the configuration.
Sources: internal/cli/init.go:56-117
Service Detection and Analysis
Docktree analyzes the services defined in Docker Compose files to find candidates for the "Platform Tier"—services that can be shared across worktrees instead of being duplicated.
Shareable Candidates
The system specifically looks for "Kind" signatures in container images (e.g., postgres, mysql, mongodb, redis). It attempts to find environment variables that look like connection strings (URLEnvs) to facilitate automated rewriting when worktrees use isolated tenant databases.
Secrets Wrappers and Warnings
A critical part of the analysis is detecting "secrets wrappers" like Infisical, Doppler, or Vault. If a consumer service uses these wrappers, Docktree issues a warning because the connection environment variables may be injected at runtime, making them "invisible" to Docktree's rewriting engine.
Sources: internal/cli/init.go:94-112, internal/cli/init.go:343-363, internal/cli/init_test.go:193-214
Interactive Configuration (--apply)
The --apply workflow is designed for programmatic interaction, where an external process (like an AI agent) provides answers to "Todos" identified during the scan.
InitTodo and Answers
The scan generates InitTodo objects for every decision the CLI cannot make autonomously, such as choosing between full_share and per_database tenancy.
This sequence shows the interaction between the user/agent and the CLI to finalize configuration.
Sources: internal/cli/init.go:153-191, internal/cli/types.go:196-202, skills/docktree-init/SKILL.md:15-52
Tenancy Options by Service Kind
Different service types support different isolation modes:
| Service Kind | Supported Tenancy Modes | Default Mode |
|---|---|---|
postgres | full_share, per_database | full_share |
mysql | full_share, per_database | full_share |
mongodb | full_share, per_database | full_share |
redis | full_share | full_share |
s3 | full_share | full_share |
generic | full_share | full_share |
Sources: internal/cli/init.go:271-278, internal/config/config.go:189-197
Configuration Structures
The generated configuration is based on a set of internal defaults that provide reasonable isolation for most Docker Compose projects.
Default Config Settings
If no docktree.yml exists, the following defaults are used during the generation process:
| Component | Default Value | Description |
|---|---|---|
worktrees.root | ../${repo}.worktrees | Relative path where worktrees are created. |
setup.copy | [.env] | Files copied from the main repo to worktrees. |
setup.symlink | [node_modules] | Directories symlinked to save disk space. |
ports.range | 41000-49999 | The range of host ports available for allocation. |
state.directory | .docktree | Internal directory for managing worktree state. |
Sources: internal/config/config.go:119-145, internal/config/config_test.go:11-28
Infrastructure Detection Helpers
The init logic utilizes several helper functions to discover the local environment:
detectGitignoredEnvFiles: Searches for files starting with.envthat are ignored by git (excluding templates).detectSymlinkableDirs: Checks for common heavy directories likenode_modules,vendor, ortarget.isGitignored: Usesgit check-ignoreto verify if a path should be handled as a local secret/config.
Sources: internal/cli/init.go:294-342
Summary
The "Init Command and Config Generation" system provides a robust mechanism for bootstrapping Docktree in any Docker Compose-based project. By combining automated service kind detection with an interactive "Todo" system, it ensures that developers can achieve environment isolation while maintaining shared infrastructure where appropriate. The use of a .proposed file by default allows for safe inspection before finalizing the docktree.yml configuration.
Sources: internal/cli/init.go:113-117, skills/docktree-init/SKILL.md:54-60