Setup File Synchronization

Relevant source files

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

• internal/setup/setup.go
• internal/setup/setup_test.go
• internal/cli/sync.go
• internal/cli/up.go
• internal/cli/worktree.go
• internal/config/config.go

The Setup File Synchronization system in Docktree manages the propagation of configuration files, environment variables, and directory structures from a primary repository root to various git worktrees. Its primary purpose is to ensure that isolated worktree environments remain consistent with the main repository's configuration while allowing for unique execution contexts.

The system handles three main operations: copying files (e.g., .env), creating symlinks for heavy directories (e.g., node_modules), and executing arbitrary shell commands to prepare the environment. This ensures that when a developer switches to a specific worktree, all necessary dependencies and configurations are correctly mirrored or initialized.
Sources: internal/setup/setup.go:1-35, internal/config/config.go:41-45

Architecture and Components

The synchronization logic is split between the setup package, which provides the low-level primitives for file manipulation, and the cli package, which orchestrates these primitives during command execution (such as docktree up or docktree sync).

Core Configuration Structure

Synchronization is governed by the SetupConfig defined in the project's configuration model.

Field	Type	Description
Copy	[]string	List of relative paths to be copied from source to target. Defaults to [.env].
Symlink	[]string	List of relative paths to be symlinked. Defaults to [node_modules].
Run	[]string	List of shell commands to execute in the target directory after file operations.

Sources: internal/config/config.go:41-45, internal/config/config.go:121-124

Preparation Flow

The Prepare function is the central entry point for initializing a worktree. It executes operations in a specific order: copying, then symlinking, then running commands.

Synchronization Logic

Docktree maintains environment parity by detecting "stale" files—files that exist in the main repository but are missing or different in a specific worktree.

Staleness Detection

Staleness is determined by comparing SHA-256 hashes of files listed in the Setup.Copy configuration. If a source file exists but the target file is missing or has a different hash, it is marked as stale.

The sync Command Workflow

The docktree sync command groups worktree instances by their repository root and applies updates. It avoids overwriting files in worktrees where containers are currently running to prevent state corruption.

Implementation Details

File Operations

The system uses standard Go os and io packages to perform atomic-like copies and symlink management.

• copyFile: Copies content and preserves file modes. It ensures parent directories exist before writing.
• symlinkPath: Creates a symbolic link. If a symlink already exists at the target, it is removed and recreated. If a regular file exists where a symlink should be, it returns an error to prevent accidental data loss.
• runCommand: Executes shell commands using sh -c to allow for pipeline and environment variable support within the setup strings.

Sources: internal/setup/setup.go:88-142, internal/cli/sync.go:138-161

Command Integration

The setup synchronization is integrated into several CLI workflows:

1. docktree up --sync: Triggers a preparation step before starting containers.
2. docktree create: Preparation is automatically performed after a new git worktree is added.
3. docktree prepare: Explicitly runs the setup logic for the current directory.

Sources: internal/cli/up.go:78-85, internal/cli/worktree.go:39-51, internal/cli/worktree.go:102-108

Summary

The Setup File Synchronization system provides a robust mechanism for maintaining configuration consistency across multiple isolated development environments. By combining hash-based staleness detection with safe file operations and command execution, Docktree ensures that git worktrees are fully functional and mirror the primary repository's required state.