Managing Git Worktrees
Use this skill to manage worktrees with a standard structure and tracking. Use the /sc-git-worktree command to invoke this skill.
Agent Delegation
This skill delegates to specialized agents via the Task tool:
| Operation |
Agent |
Returns |
| Create |
sc-worktree-create |
JSON: success, path, branch, tracking_row |
| Scan |
sc-worktree-scan |
JSON: success, worktrees list, recommendations |
| Cleanup |
sc-worktree-cleanup |
JSON: success, branch_deleted, tracking_update |
| Abort |
sc-worktree-abort |
JSON: success, worktree_removed, tracking_update |
| Update |
sc-worktree-update |
JSON: success, commits_pulled, conflicts (if any) |
To invoke an agent, use the Task tool with:
- Prompt file:
.claude/agents/<agent-name>.md
- Parameters as documented in each agent's Inputs section
Standards and paths
- Repo root: current directory.
- Default worktree base:
../{{REPO_NAME}}-worktrees.
- Worktrees live in
<worktree_base>/<branch>.
- Tracking document (if used):
<worktree_base>/worktree-tracking.md must be updated on create/scan/cleanup/abandon. Allow a toggle to disable tracking for repos that don't use it.
- Naming: worktree directory = branch name; branch naming follows repo policy (e.g., master release; develop/DevBranch integration; feature from integration; hotfix from master; release branches as needed).
- Branch protections/hooks: no direct commits to protected branches; ensure hooks/branch protections are respected across worktrees.
- Cleanliness: worktrees must be removed and tracking updated when work is complete or branch is merged.
Protected Branch Configuration
Protected branches (main, develop, master, etc.) require special handling to prevent accidental deletion:
# Configuration (typically in repo .claude/config or passed to agents)
git_flow:
enabled: true # boolean: whether git-flow workflow is used
main_branch: "main" # or "master" - the primary production branch
develop_branch: "develop" # only if git_flow.enabled = true
protected_branches:
- "main"
- "develop"
- "master"
# Can include additional patterns: "release/*", "hotfix/*"
Protected Branch Rules:
- If
git_flow.enabled: false → protect only main_branch
- If
git_flow.enabled: true → protect main_branch + develop_branch
- Additional branches can be added to
protected_branches array
- Cleanup/abort agents NEVER delete protected branches (local or remote)
- Protected branches can only be removed from worktrees, never deleted
- Use
--update to safely pull changes for protected branches in worktrees
Workflows
Scaffolding (if missing)
- Ensure base path exists:
<worktree_base>. If missing, create it.
- If tracking is enabled, ensure tracking doc exists with headers.
Create worktree (and branch)
- Inputs:
--branch <name>, --base <master|develop|...>, optional --path.
- Ensure scaffolding/tracking doc exists (if enabled); fetch all:
git fetch --all --prune.
- Confirm base branch exists and is up to date.
- Determine path: default
<worktree_base>/<branch> (or override).
- Create branch/worktree:
- If branch does not yet exist:
git worktree add -b <branch> <path> <base>.
- If branch exists:
git worktree add <path> <branch>.
- In the new worktree, ensure hooks apply and verify status is clean.
- If tracking enabled, add/refresh entry in tracking doc (branch, path, base, purpose, owner, created date, status).
- Agent option: delegate to
sc-worktree-create agent; it returns structured JSON (tracking row, status).
Scan/verify worktrees
- List worktrees:
git worktree list --porcelain.
- Cross-check tracking doc (if enabled); flag missing/stale entries or extra rows.
- For each worktree, check status and merge state:
git -C <path> status --shortgit -C <path> fetchgit branch --remotes --contains <branch> to see if merged.
- Identify issues: untracked changes, diverged branches, merged-but-not-cleaned worktrees, missing tracking entries.
- Update tracking doc with current state and issues (if enabled); propose cleanup where appropriate.
- Agent option: delegate to
sc-worktree-scan agent; it returns structured JSON.
Clean-up worktree (post-merge or finished work)
- Check if branch is protected: If branch is in protected_branches list, ONLY remove worktree, NEVER delete the branch.
- If
git status is not clean, stop and request explicit approval/coordination.
- Ensure all work is committed/pushed or explicitly confirmed to discard.
- Confirm target branch merged or otherwise approved for removal.
- Remove worktree:
git worktree remove <path> (use --force only with approval).
- For non-protected branches: If merged and no unique commits, delete the branch locally (
git branch -d <branch>) and remotely (git push origin --delete <branch>) by default; only skip if the user explicitly opts out. If the remote branch is already absent, continue without error. If not merged, only delete with explicit approval.
- For protected branches: Only remove worktree, preserve branch locally and remotely. Update tracking to note "worktree removed, branch preserved (protected)".
- If tracking enabled, update tracking doc to remove/mark cleaned with merge SHA/date.
- Agent option: delegate to
sc-worktree-cleanup agent; it returns structured JSON.
Abandon worktree (discard work)
- Check if branch is protected: If branch is in protected_branches list, ONLY remove worktree, NEVER delete the branch.
- If
git status is not clean, stop and request explicit approval/coordination.
- Confirm user approval to discard local changes and optionally delete the branch.
- Remove worktree:
git worktree remove <path> (force only with approval).
- For non-protected branches: If instructed, delete the branch locally (
git branch -D <branch>) and remotely (git push origin --delete <branch>).
- For protected branches: Only remove worktree, preserve branch locally and remotely. Require confirmation: "Branch is protected. Remove worktree but preserve branch?"
- If tracking enabled, update tracking doc to remove the entry and note abandonment.
- Agent option: delegate to
sc-worktree-abort agent; it returns structured JSON.
Update protected branch (pull latest changes)
- Verify branch is protected: Only operates on branches in protected_branches list. If no branch is specified, update all protected branches that have worktrees.
- Check if worktree exists at expected path; error if missing.
- If
git status is not clean, stop and report dirty state.
- Fetch and pull:
git fetch origin <branch> then git pull origin <branch>.
- If merge conflicts occur:
- Collect conflicted files:
git diff --name-only --diff-filter=U
- Return control to main agent with conflict details
- Main agent coordinates with user to resolve conflicts
- After resolution, user commits and continues
- If clean pull: Update tracking with last_checked timestamp and commits pulled count.
- Agent option: delegate to
sc-worktree-update agent; it returns structured JSON with success or conflict details.
Safety and reminders
- NEVER delete protected branches (main, develop, master) under any circumstances.
- Protected branches can only be removed from worktrees; the branch itself must always be preserved.
- Never delete branches or force-remove worktrees without explicit approval.
- Never clean/abandon a worktree with uncommitted changes unless explicitly approved.
- Keep tracking doc in sync on every operation when enabled.
- Respect branch protections and hooks; no direct commits to protected branches.
- Use background agents for long scans/cleanups; keep the main context focused on decisions and summaries.
- When updating protected branches in worktrees, handle merge conflicts by returning control to main agent for user coordination.
1---2name: sc-managing-worktrees3description: Create, manage, scan, update, and clean up git worktrees for parallel development with protected branch safeguards. Use when working on multiple branches simultaneously, isolating experiments, updating protected branches (main/develop), or when user mentions "worktree", "parallel branches", "feature isolation", "branch cleanup", "worktree status", or "update main/develop".4---5
6# Managing Git Worktrees
7
8Use this skill to manage worktrees with a standard structure and tracking. Use the `/sc-git-worktree` command to invoke this skill.
9
10## Agent Delegation
11
12This skill delegates to specialized agents via the **Task tool**:
13
14| Operation | Agent | Returns |
15|-----------|-------|---------|
16| Create | `sc-worktree-create` | JSON: success, path, branch, tracking_row |
17| Scan | `sc-worktree-scan` | JSON: success, worktrees list, recommendations |
18| Cleanup | `sc-worktree-cleanup` | JSON: success, branch_deleted, tracking_update |
19| Abort | `sc-worktree-abort` | JSON: success, worktree_removed, tracking_update |
20| Update | `sc-worktree-update` | JSON: success, commits_pulled, conflicts (if any) |
21
22To invoke an agent, use the Task tool with:
23- Prompt file: `.claude/agents/<agent-name>.md`
24- Parameters as documented in each agent's Inputs section
25
26## Standards and paths
27- Repo root: current directory.
28- Default worktree base: `../{{REPO_NAME}}-worktrees`.
29- Worktrees live in `<worktree_base>/<branch>`.
30- Tracking document (if used): `<worktree_base>/worktree-tracking.md` must be updated on create/scan/cleanup/abandon. Allow a toggle to disable tracking for repos that don't use it.
31- Naming: worktree directory = branch name; branch naming follows repo policy (e.g., master release; develop/DevBranch integration; feature from integration; hotfix from master; release branches as needed).
32- Branch protections/hooks: no direct commits to protected branches; ensure hooks/branch protections are respected across worktrees.
33- Cleanliness: worktrees must be removed and tracking updated when work is complete or branch is merged.
34
35## Protected Branch Configuration
36
37Protected branches (main, develop, master, etc.) require special handling to prevent accidental deletion:
38
39```yaml
40# Configuration (typically in repo .claude/config or passed to agents)
41git_flow:
42 enabled: true # boolean: whether git-flow workflow is used
43 main_branch: "main" # or "master" - the primary production branch
44 develop_branch: "develop" # only if git_flow.enabled = true
45
46protected_branches:
47 - "main"
48 - "develop"
49 - "master"
50 # Can include additional patterns: "release/*", "hotfix/*"
51```
52
53**Protected Branch Rules:**
54- If `git_flow.enabled: false` → protect only `main_branch`
55- If `git_flow.enabled: true` → protect `main_branch` + `develop_branch`
56- Additional branches can be added to `protected_branches` array
57- **Cleanup/abort agents NEVER delete protected branches** (local or remote)
58- Protected branches can only be removed from worktrees, never deleted
59- Use `--update` to safely pull changes for protected branches in worktrees
60
61## Workflows
62
63### Scaffolding (if missing)
64- Ensure base path exists: `<worktree_base>`. If missing, create it.
65- If tracking is enabled, ensure tracking doc exists with headers.
66
67### Create worktree (and branch)
681) Inputs: `--branch <name>`, `--base <master|develop|...>`, optional `--path`.
692) Ensure scaffolding/tracking doc exists (if enabled); fetch all: `git fetch --all --prune`.
703) Confirm base branch exists and is up to date.
714) Determine path: default `<worktree_base>/<branch>` (or override).
725) Create branch/worktree:
73 - If branch does not yet exist: `git worktree add -b <branch> <path> <base>`.
74 - If branch exists: `git worktree add <path> <branch>`.
756) In the new worktree, ensure hooks apply and verify status is clean.
767) If tracking enabled, add/refresh entry in tracking doc (branch, path, base, purpose, owner, created date, status).
778) Agent option: delegate to `sc-worktree-create` agent; it returns structured JSON (tracking row, status).
78
79### Scan/verify worktrees
801) List worktrees: `git worktree list --porcelain`.
812) Cross-check tracking doc (if enabled); flag missing/stale entries or extra rows.
823) For each worktree, check status and merge state:
83 - `git -C <path> status --short`
84 - `git -C <path> fetch`
85 - `git branch --remotes --contains <branch>` to see if merged.
864) Identify issues: untracked changes, diverged branches, merged-but-not-cleaned worktrees, missing tracking entries.
875) Update tracking doc with current state and issues (if enabled); propose cleanup where appropriate.
886) Agent option: delegate to `sc-worktree-scan` agent; it returns structured JSON.
89
90### Clean-up worktree (post-merge or finished work)
911) **Check if branch is protected**: If branch is in protected_branches list, ONLY remove worktree, NEVER delete the branch.
922) If `git status` is not clean, stop and request explicit approval/coordination.
933) Ensure all work is committed/pushed or explicitly confirmed to discard.
944) Confirm target branch merged or otherwise approved for removal.
955) Remove worktree: `git worktree remove <path>` (use `--force` only with approval).
966) For **non-protected branches**: If merged and no unique commits, delete the branch locally (`git branch -d <branch>`) and remotely (`git push origin --delete <branch>`) by default; only skip if the user explicitly opts out. If the remote branch is already absent, continue without error. If not merged, only delete with explicit approval.
977) For **protected branches**: Only remove worktree, preserve branch locally and remotely. Update tracking to note "worktree removed, branch preserved (protected)".
988) If tracking enabled, update tracking doc to remove/mark cleaned with merge SHA/date.
999) Agent option: delegate to `sc-worktree-cleanup` agent; it returns structured JSON.
100
101### Abandon worktree (discard work)
1021) **Check if branch is protected**: If branch is in protected_branches list, ONLY remove worktree, NEVER delete the branch.
1032) If `git status` is not clean, stop and request explicit approval/coordination.
1043) Confirm user approval to discard local changes and optionally delete the branch.
1054) Remove worktree: `git worktree remove <path>` (force only with approval).
1065) For **non-protected branches**: If instructed, delete the branch locally (`git branch -D <branch>`) and remotely (`git push origin --delete <branch>`).
1076) For **protected branches**: Only remove worktree, preserve branch locally and remotely. Require confirmation: "Branch is protected. Remove worktree but preserve branch?"
1087) If tracking enabled, update tracking doc to remove the entry and note abandonment.
1098) Agent option: delegate to `sc-worktree-abort` agent; it returns structured JSON.
110
111### Update protected branch (pull latest changes)
1121) **Verify branch is protected**: Only operates on branches in protected_branches list. If no branch is specified, update all protected branches that have worktrees.
1132) Check if worktree exists at expected path; error if missing.
1143) If `git status` is not clean, stop and report dirty state.
1154) Fetch and pull: `git fetch origin <branch>` then `git pull origin <branch>`.
1165) **If merge conflicts occur**:
117 - Collect conflicted files: `git diff --name-only --diff-filter=U`
118 - Return control to main agent with conflict details
119 - Main agent coordinates with user to resolve conflicts
120 - After resolution, user commits and continues
1216) **If clean pull**: Update tracking with last_checked timestamp and commits pulled count.
1227) Agent option: delegate to `sc-worktree-update` agent; it returns structured JSON with success or conflict details.
123
124## Safety and reminders
125- **NEVER delete protected branches** (main, develop, master) under any circumstances.
126- Protected branches can only be removed from worktrees; the branch itself must always be preserved.
127- Never delete branches or force-remove worktrees without explicit approval.
128- Never clean/abandon a worktree with uncommitted changes unless explicitly approved.
129- Keep tracking doc in sync on every operation when enabled.
130- Respect branch protections and hooks; no direct commits to protected branches.
131- Use background agents for long scans/cleanups; keep the main context focused on decisions and summaries.
132- When updating protected branches in worktrees, handle merge conflicts by returning control to main agent for user coordination.
majiayu000