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

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 and .envrc files 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: Usually has detached HEAD
• 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