worktree-manager

Worktree Manager

Skill to manage git worktrees following the folder strategy .worktrees/ inside the repository.

Worktree Structure

~/Projects/<github|gitlab>/<project>/
├── .worktrees/                     # ignorado por .gitignore
│   ├── feature-x/                  # worktree para branch feature-x
│   └── bugfix-123/                 # worktree para branch bugfix-123
├── src/                            # archivos del repo (master/main)
└── .gitignore                      # debe incluir .worktrees/

Process

Step 0: Verify context

git rev-parse --is-inside-work-tree
git branch --show-current

---

Available Commands

1. Initial Setup

Run once per project to enable worktrees:

grep -q "^\.worktrees/$" .gitignore 2>/dev/null || echo ".worktrees/" >> .gitignore
mkdir -p .worktrees

If .worktrees/ was not in .gitignore, commit:

git add .gitignore
git commit -m "chore: ignore worktrees folder"

2. Create Worktree (new branch)

# Sintaxis: git worktree add .worktrees/<nombre-branch> -b <nombre-branch>
git worktree add .worktrees/feature-nueva-funcionalidad -b feature-nueva-funcionalidad

The branch must follow conventions:

• feature/<descripcion> or feature-<descripcion> for new features
• bugfix/<descripcion> or bugfix-<descripcion> for fixes
• hotfix/<descripcion> for urgent fixes
• chore/<descripcion> for maintenance tasks

3. Create Worktree from existing branch

To review a PR or work on an existing remote branch:

git fetch origin
git worktree add .worktrees/<nombre-branch> origin/<nombre-branch>

4. List Worktrees

git worktree list

5. Work in Worktree

IMPORTANT: cd does not persist between Bash tool calls in Claude Code. Use absolute paths or chain with &&:

# Encadenar con && para que cd persista
cd .worktrees/<nombre-branch> && git status

# O usar paths absolutos
git -C .worktrees/<nombre-branch> status

IMPORTANT: Do not use git add . — always add specific files:

cd .worktrees/<nombre-branch> && git add src/feature.ts src/feature.test.ts
git commit -m "feat: descripcion del cambio"
git push -u origin <nombre-branch>

6. Cleanup after Merge

Once the PR has been merged, clean up from the root directory:

git worktree remove .worktrees/<nombre-branch>
git push origin --delete <nombre-branch>
git branch -d <nombre-branch>

7. Prune Orphaned References

git worktree prune

---

Key Principles

Principle	Description
Worktrees are temporary	They are not permanent homes, they are deleted after the merge
Main always clean	The main repo is always on main/master
Descriptive names	Worktree folder = branch name
Mandatory cleanup	Always clean up after the PR merge

---

Questions for the User

Before creating a worktree, ask:

1. Branch name: "What do you want to name the branch?" (suggest format feature-* or bugfix-*)
2. Confirm structure: If it is the first time, confirm that .worktrees/ will be added to .gitignore

Before cleanup, confirm:

1. PR merged?: "Has the PR already been merged? Confirm before deleting the worktree."
2. Remote branch: "Also delete the remote branch?"

---

For complete workflow examples, read references/workflow-examples.md. To resolve common errors, read references/troubleshooting.md.