Skip to content
devflow

Worktrees

Git worktrees let you have multiple refs checked out simultaneously in different directories. They are devflow’s only Git workspace model: the primary checkout is the default workspace, and devflow switch materializes every additional workspace as a linked worktree. Jujutsu projects use equivalent native workspaces.

Why worktrees?

Section titled “Why worktrees?”
  • True parallel development — work on two features at once without stashing.
  • Instant context switching — switching workspace = changing directory; no rebuild, each worktree keeps its own node_modules, build cache, virtualenv.
  • PR reviews without disruption — check out a review in a new worktree while your feature (and its database) keeps running.
  • Parallel AI agents — each agent task gets its own directory and its own database; agents can’t trample each other. See AI agents.

Configuration

Section titled “Configuration”
worktree:
  path_template: "../{repo}.{workspace}"  # where worktrees are created
  copy_files:                             # files/dirs copied from the main worktree
    - .env.local
    - .env
  copy_ignored: false                     # deprecated broad copy; prefer caches
  copy_ai_configs: false                   # deprecated broad copy; prefer explicit files
  extra_ai_dirs: []                       # additional AI tool dirs to copy
FieldDefaultEffect
path_template../{repo}.{workspace}Placeholders: {repo} (config name: or project directory name), {workspace} (collision-safe service key), {branch} (legacy alias for {workspace}). Relative to the project root.
copy_files[.env, .env.local]Files or directories copied from the main worktree into each new one when present. Reflink/CoW copy when the filesystem supports it.
copy_ignoredfalseDeprecated broad copying of ignored entries. Use fingerprinted caches for reusable artifacts.
copy_ai_configsfalseDeprecated broad copying of AI tool settings. Use explicit copy_files entries or tracked project guides.
extra_ai_dirs[]Additional directories to treat like AI config dirs.

Path normalization

Section titled “Path normalization”

{workspace} uses the collision-safe service_key (identity details), not the raw VCS name.

workspace feature/Auth  +  template ../{repo}.{workspace}
→ ../my-project.feature_auth_cc2526bd757f

What happens on creation

Section titled “What happens on creation”

devflow switch -c feature/x:

  1. Reuses the existing worktree if one is already checked out for that branch.
  2. Creates the VCS ref if needed (from --from <parent> or your current context).
  3. Creates the worktree via libgit2 — tracked files only. Stale worktree metadata for the same name is pruned automatically when its directory no longer exists.
  4. Copies configured payloads through confined directory handles, preserving symlink entries without following destination links. Failed copies block readiness and are retried. Matching artifact caches are materialized separately.
  5. Registers the raw name, collision-safe service key, immutable creation parent, and worktree path in local state.
  6. Creates/switches service workspaces and runs hooks inside the new worktree — post-create hooks like npm ci or write-env target the right directory.
  7. Emits DEVFLOW_CD=<path> so the shell wrapper moves you there.

Hooks are worktree-aware

Section titled “Hooks are worktree-aware”
  • Hook working directory is the target workspace directory.
  • {{ worktree_path }} is available in templates.
  • is_worktree / not_worktree conditions let hooks opt in or out of worktree context.

Manually created worktrees

Section titled “Manually created worktrees”

git worktree add ../myapp.hotfix hotfix works too: the devflow post-checkout hook detects worktree context and runs the same setup (file copying + service workspace creation + hooks). To trigger it explicitly from inside a worktree:

Terminal window
devflow worktree-setup

Safety on removal

Section titled “Safety on removal”

devflow remove <ws> and GUI/TUI deletion run a non-mutating preflight first. They refuse dirty worktrees and protect the default/current workspace; --force explicitly accepts dirty-worktree or partial-cleanup risk.

After preflight, devflow runs removal hooks while the directory still exists, stops processes, and deletes service instances. Only after those steps succeed does it remove the worktree, delete its VCS ref, and unregister state. A service deletion failure therefore leaves the code and worktree available for retry. GUI force deletion is a separate second confirmation.

Agent configuration

Section titled “Agent configuration”

Agent policy merging is retired. Generate project guides with devflow agent skill --target all, and use explicit worktree.copy_files entries for project files that each workspace needs.

Section titled “Related”