Worktree Tending

Overview

This skill helps manage git worktrees using a customized workflow with scripts stored in ~/bin/. Worktrees enable working on multiple branches simultaneously by creating separate working directories that share the same git repository. All worktrees are stored in .tree/ subdirectories.

Core Workflow

The typical worktree lifecycle:

1. Create a new worktree for a branch using git newtree
2. Work in that worktree (user navigates manually)
3. Close the worktree when done, optionally merging back to main

Important: Always Display Worktrees

CRITICAL INSTRUCTION: After completing any worktree operation (create, merge, delete, archive), you MUST always run git worktree list and display the current state of all worktrees before yielding control back to the user.

This helps the user maintain awareness of their worktree state and verify that operations completed successfully.

Example output format:

**Current worktrees (N total):**

- `/path/to/repo` - detached HEAD (commit-hash)
- `/path/to/repo.bare` - detached HEAD (commit-hash)
- `feature-name` - branch: feature-name
- `maincomp` - branch: main

Available Operations

Creating a New Worktree

To create a new worktree for a branch:

git newtree <tree-name> [branch-name]

Behavior:

• Creates worktree at .tree/<tree-name>
• If branch exists, checks it out; otherwise creates new branch
• Branch name defaults to tree-name if not specified
• Copies .env, .envrc, and .claude/ to the new worktree if present
• Reports the path for manual navigation

Examples:

git newtree feature-x              # Creates .tree/feature-x with branch 'feature-x'
git newtree fix check/lint-graphql # Creates .tree/fix with existing branch 'check/lint-graphql'

When to use: User asks to create a new worktree, start work on a new branch, or work on a branch in parallel.

Listing Active Worktrees

To show all active worktrees with status:

git worktree list

Output format:

/path/to/repo                      commit-hash (detached HEAD)
/path/to/repo/.tree/feature-x      commit-hash [feature-x]
/path/to/repo/.tree/maincomp       commit-hash [main]

Interactive selection with fzf: When closing or switching worktrees, use fzf for interactive selection of worktrees from the list.

When to use: User asks to see active worktrees, list branches being worked on, or needs to select a worktree to close.

Closing a Worktree

When closing a worktree, always ask the user whether to merge back to main or just remove the worktree.

Option 1: Merge to Main and Cleanup

Use git maingulp to merge changes back to main and cleanup:

cd .tree/maincomp  # or wherever main branch worktree is
git maingulp <branch-name> <worktree-path>

Requirements:

• Must be run from the main branch worktree
• Performs fast-forward merge (rebases main onto branch)
• Pushes main to remote
• Removes worktree and deletes branch

Example:

cd .tree/maincomp
git maingulp feature-x .tree/feature-x

When to use: Work is complete and ready to be merged into main.

Option 2: Just Remove Worktree

Use git killtree to remove worktree without merging:

git killtree <worktree-path> [--force]

Behavior:

• Removes worktree at specified path
• Deletes branch only if fully merged (unless --force)
• Use --force to remove dirty worktree and force-delete unmerged branch

Examples:

git killtree .tree/feature-x          # Remove worktree, delete if merged
git killtree .tree/experiment --force # Force remove unmerged work

When to use: Work is abandoned, experimental, or will be merged manually later.

Interactive Worktree Selection

When the user asks to close a worktree without specifying which one, use fzf for interactive selection:

# First list worktrees
git worktree list

# Parse the output and use fzf to let user select
# Then confirm merge vs. remove decision

Example interaction:

1. User: "Close a worktree"
2. Show git worktree list output
3. Use fzf or present choices for selection
4. Ask: "Merge to main or just remove?"
5. Execute appropriate command

References

See references/git-scripts-reference.md for detailed documentation of all git scripts including git-archivebranch and git-substat.

Working Directory Conventions

• Main repo (root worktree): Should stay in detached HEAD on freshest origin/main
  • After merging branches, update with: git checkout --detach origin/main
  • This prevents conflicts with other worktrees checking out branches
• Worktrees: Located in .tree/ subdirectory
• Main branch: Typically lives in .tree/maincomp or similar
• Feature branches: Each in its own .tree/<name> directory

Common Patterns

Starting new feature work:

git newtree my-feature
cd .tree/my-feature
# work on feature

Completing and merging feature:

cd .tree/maincomp
git maingulp my-feature .tree/my-feature

Abandoning experimental work:

git killtree .tree/experiment --force