Using git worktrees

Using Git Worktrees

Use this skill when multiple coding tasks in the same repository should stay isolated from each other.

Goal

Increase coding success rate by preventing task overlap, branch contamination, and context confusion.

Use worktrees to keep each task in its own directory and branch.

Core Rules

1. Isolate one task per worktree

Use a separate worktree when:

• fixing a different bug
• building a separate feature
• trying an experimental approach
• reviewing or testing a different branch
• you want to pause one task without polluting another

Do not pile unrelated work into the same checkout just because it is already open.

2. Name branches and worktrees clearly

Names should make the task obvious.

Prefer names like:

• bugfix/login-timeout
• feature/export-csv
• experiment/new-parser

Avoid vague names like:

• test
• stuff
• temp2

3. Keep worktrees near the repository, but clearly separate

Use a predictable layout so it is obvious:

• which directory is the main repo
• which directories are separate task worktrees
• which branch belongs to which task

4. Verify branch state before editing

Before starting work in a worktree, confirm:

• current branch
• branch purpose
• whether there are uncommitted changes
• whether the worktree already exists for the task

5. Clean up finished worktrees

When a task is merged, abandoned, or no longer needed:

• confirm work is committed or intentionally discarded
• remove the worktree cleanly
• avoid leaving a pile of stale directories that create confusion later

Minis-Specific Workflow

Why worktrees help on Minis

On Minis, context switching is expensive because:

• screen space is limited
• shell sessions are lightweight but focused
• it is easy to lose track of what branch a directory represents
• multiple tasks in one checkout can create messy diffs quickly

Worktrees reduce that confusion by making each task physically separate.

Practical directory strategy

Prefer a simple layout such as:

• main repo in one directory
• sibling worktrees/ directory for isolated tasks

Example:

• /var/minis/shared/myrepo/
• /var/minis/shared/myrepo-worktrees/bugfix-login-timeout/
• /var/minis/shared/myrepo-worktrees/feature-export-csv/

Shell usage

Use shell commands to:

• inspect existing worktrees
• create a new branch-backed worktree
• verify current branch and path
• remove stale worktrees after task completion

Safe Sequence

Use this order:

1. Identify the repository root.
2. Identify the exact task that should be isolated.
3. Check existing branches and worktrees.
4. Choose a clear branch name.
5. Create a dedicated worktree in a clearly named directory.
6. Verify branch and path before editing.
7. Do the task-specific work only in that worktree.
8. Clean up after the task is finished or abandoned.

When to Avoid Extra Worktrees

Do not create a new worktree if:

• the task is a tiny change already in progress on the correct branch
• the repository is so small and the task so trivial that isolation adds more friction than value
• the user explicitly wants everything kept in one branch for a short-lived task

Common Failure Modes

Watch for:

• editing the wrong worktree
• forgetting which branch maps to which directory
• creating vague branch names
• leaving uncommitted changes in multiple worktrees
• creating too many worktrees for tiny tasks
• deleting a worktree before confirming work is saved

Integration with Other Skills

• Use software-architecture if the new worktree is for a non-trivial feature and structure should be planned first.
• Use test-driven-development inside the worktree when implementing or fixing behavior safely.
• Use root-cause-tracing inside the worktree when the task is debugging-heavy.
• Use finishing-a-development-branch before removing or handing off a completed worktree.

Completion Checklist

Before calling the worktree setup good, check:

• Is this task worth isolating?
• Is the branch name clear?
• Is the worktree path clear?
• Did you verify the current branch before editing?
• Is unrelated work kept out of this worktree?
• Is there a cleanup plan after the task is done?

Response Template

• Repository root:
• Task to isolate:
• Branch name:
• Worktree path:
• Current verification:
• Why isolation helps here:
• Suggested next step:

Example Triggers

• "Set up a separate worktree for this bugfix."
• "I need to work on two features in parallel without mixing them."
• "Create an isolated branch workspace for this experiment."
• "Help me avoid contaminating my current branch."
• "Use git worktrees to keep this task separate."