using-git-worktrees
Imported from alexei-led/cc-thingz/dist/pi/skills/using-git-worktrees.
Install
npx skills add https://github.com/alexei-led/cc-thingz/tree/master/dist/pi/skills/using-git-worktrees
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alexei-led-cc-thingz@llmmart
git clone https://github.com/alexei-led/cc-thingz.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alexei-led/cc-thingz collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Git Worktrees
A worktree gives parallel work its own folder and branch while the main worktree stays clean on the integration branch. Each project gets one sibling root, <project>.worktrees/, with one directory per branch named by its slug (/ → -, so feature/auth → feature-auth). Remove the worktree and branch after the PR merges.
A plain branch switch with no parallel work needs no worktree: check git status --short, then git switch <branch>. Trivial solo one-liners may also stay in the main worktree.
Create
Check git status --short and git worktree list first. Leave uncommitted changes where they are and never stash them silently; pass --allow-dirty only when the user has authorized isolating new work while keeping them.
scripts/setup-worktree.sh <branch> [--base <ref>] [--allow-dirty] [--setup] [--test]
The script runs git worktree add from the main worktree root. It checks out an existing local or origin branch instead of recreating it, and refuses an existing path, a branch checked out in another worktree, or a dirty tree without --allow-dirty. It reports base divergence from local refs without fetching.
--setupdoes a frozen install with the declared package manager and lockfile (uv for Python). Conflicting lockfiles or manager declarations stop it. A setup failure exits non-zero but still prints the path.--testruns the detected baseline tests. Failures only warn.- A skipped setup or test is not a pass.
Clean up one worktree
scripts/cleanup-worktree.sh [branch]
A cleanup request authorizes removal of a clean, verified merged worktree and its branch without another confirmation. The script fetches first and verifies Git ancestry, a merged PR bound to the repository/base/head, or an equivalent squash patch without gh. It preserves new commits and uncommitted files, including ignored files. For an exception, show the exact target, full tip OID, commits and files at risk, then ask once. After consent, recheck the tip and files and run --force <branch> yourself; never require the user to copy and run the command. Main, protected, and locked worktrees remain guarded even with force. For bulk or stale cleanup and command-local hook consent, use cleanup-git. Leave git pull out of cleanup; update the integration worktree separately only when clean and requested.
For cases the scripts refuse or don't cover, read workflow.md.
Output
WORKTREE READY | WORKTREE REMOVED | BLOCKED
Branch: <branch>
Path: <project>.worktrees/<slug>
Next: cd <path>, or the script's refusal reason
Report cleanup as done only after verifying the worktree and branch are gone. Name the merge proof or the explicitly approved exception.
Files (cc-thingz)
-
references
-
workflow.md 1.6 KB
Loading…
-
-
scripts
-
cleanup-worktree.sh 4.9 KB
Loading… -
setup-worktree.sh 8.2 KB
Loading…
-
-
SKILL.md 3.7 KB
--- {"description":"Creates and removes isolated git worktrees for parallel development. Use when starting feature work needing isolation, working on multiple branches simultaneously, or removing one specific worktree and its branch after its PR merges. NOT for simple branch switching, sweeping multiple stale worktrees or merged branches at once (use cleanup-git), or git hook/config setup (use configuring-git-hygiene).","name":"using-git-worktrees"} --- <!-- Pi platform guidance --> <!-- Use installed tool names. Discover callable tools before batching independent calls in codemode; model-only UI/orchestration tools must be called directly. --> <!-- Read required skill/instruction files through direct read when exposed or through Code Mode. If an optional pruning extension is installed, verify its output protection semantics; do not assume nested-path protection. Code Mode composes calls; subagents or controllers own durable workflows. Async subagents notify natively: yield rather than poll. --> # Git Worktrees A worktree gives parallel work its own folder and branch while the main worktree stays clean on the integration branch. Each project gets one sibling root, `<project>.worktrees/`, with one directory per branch named by its slug (`/` → `-`, so `feature/auth` → `feature-auth`). Remove the worktree and branch after the PR merges. A plain branch switch with no parallel work needs no worktree: check `git status --short`, then `git switch <branch>`. Trivial solo one-liners may also stay in the main worktree. ## Create Check `git status --short` and `git worktree list` first. Leave uncommitted changes where they are and never stash them silently; pass `--allow-dirty` only when the user has authorized isolating new work while keeping them. ```bash scripts/setup-worktree.sh <branch> [--base <ref>] [--allow-dirty] [--setup] [--test] ``` The script runs `git worktree add` from the main worktree root. It checks out an existing local or `origin` branch instead of recreating it, and refuses an existing path, a branch checked out in another worktree, or a dirty tree without `--allow-dirty`. It reports base divergence from local refs without fetching. - `--setup` does a frozen install with the declared package manager and lockfile (uv for Python). Conflicting lockfiles or manager declarations stop it. A setup failure exits non-zero but still prints the path. - `--test` runs the detected baseline tests. Failures only warn. - A skipped setup or test is not a pass. ## Clean up one worktree ```bash scripts/cleanup-worktree.sh [branch] ``` A cleanup request authorizes removal of a clean, verified merged worktree and its branch without another confirmation. The script fetches first and verifies Git ancestry, a merged PR bound to the repository/base/head, or an equivalent squash patch without `gh`. It preserves new commits and uncommitted files, including ignored files. For an exception, show the exact target, full tip OID, commits and files at risk, then ask once. After consent, recheck the tip and files and run `--force <branch>` yourself; never require the user to copy and run the command. Main, protected, and locked worktrees remain guarded even with force. For bulk or stale cleanup and command-local hook consent, use cleanup-git. Leave `git pull` out of cleanup; update the integration worktree separately only when clean and requested. For cases the scripts refuse or don't cover, read [workflow.md](references/workflow.md). ## Output ```text WORKTREE READY | WORKTREE REMOVED | BLOCKED Branch: <branch> Path: <project>.worktrees/<slug> Next: cd <path>, or the script's refusal reason ``` Report cleanup as done only after verifying the worktree and branch are gone. Name the merge proof or the explicitly approved exception.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.