using-git-worktrees

Name: using-git-worktrees
Author: alexei-led

5installs5forks

How to install using-git-worktrees?

alexei-led/cc-thingz/using-git-worktrees

$npx -y skills add alexei-led/cc-thingz --skill using-git-worktrees

Installs into the current project.

Summary

Use one sibling worktree root per project: <project>.worktrees/<branch-slug>. Keep the main worktree clean on the integration branch by default. Trivial solo one-liners may stay in the main worktree when a worktree would add pointless ceremony.

Files · 1

View on GitHub

SKILL.md

1	# Git Worktrees
2
3	Use one sibling worktree root per project: `<project>.worktrees/<branch-slug>`. Keep the main worktree clean on the integration branch by default. Trivial solo one-liners may stay in the main worktree when a worktree would add pointless ceremony.
4
5	Treat a worktree as a disposable branch folder. Remove it and its branch after the PR merges.
6
7	## Scope
8
9	Use this skill when:
10
11	- starting a feature, fix, or experiment that should not disturb current work
12	- working on multiple branches at once
13	- trying competing approaches
14	- the current worktree has uncommitted changes and the user wants to start something else
15
16	Do not use this skill for:
17
18	- simple branch switching with no parallel work
19	- bulk branch or stale worktree cleanup — use `cleanup-git`
20	- git hook, Gitleaks, `.gitignore`, or config setup — use `configuring-git-hygiene`
21
22	## Create Workflow
23
24	Check state before any `git worktree add`:
25
26	```bash
27	git status --short
28	git branch --show-current
29	git worktree list
30	```
31
32	If the current worktree is dirty, ask whether to commit, stash, or proceed anyway. Do not stash silently.
33
34	Use the helper when available:
35
36	```bash
37	scripts/setup-worktree.sh <branch> [--base <ref>]
38	```
39
40	The helper creates `<project>.worktrees/<branch-slug>` from the main worktree root, handles existing local/remote branches, refuses path conflicts, and refuses dirty state unless `--allow-dirty` is passed after user approval.
41
42	Manual fallback lives in [workflow.md](references/workflow.md).
43
44	## Naming
45
46	- Root: sibling `<project>.worktrees/` directory.
47	- Directory: branch slug only; replace `/` with `-`.
48	- Examples: `fix-cron`, `feature-auth`, `bugfix-issue-123`.
49
50	## Cleanup Workflow
51
52	For one named worktree after PR merge:
53
54	```bash
55	scripts/cleanup-worktree.sh [branch]
56	```
57
58	The helper refuses unless `gh` confirms the PR is `MERGED`. Pass `--force` only after the user confirms the merge without `gh` or confirms the branch should be abandoned.
59
60	For bulk cleanup, stale worktrees, gone upstreams, or merged local branches, use `cleanup-git`.
61
62	Do not run `git pull` as part of cleanup. Pull the integration branch only after confirming the main worktree is checked out and clean.
63
64	## Failure Handling
65
66	- Worktree path exists: pick a different branch/slug; never overwrite.
67	- Branch already exists remotely: check it out without `-b` or use the helper.
68	- Dirty current worktree: ask to commit, stash, or continue with explicit approval.
69	- `git worktree remove` fails because the worktree is dirty: confirm before `--force`.
70	- `git branch -d` fails after squash/rebase PR merge: confirm the PR is `MERGED`, then use `-D`.
71	- Invoked from inside the worktree being removed: change to the main worktree before removing it.
72
73	## Output
74
75	```text
76	WORKTREE READY
77	==============
78	Action: CREATE \| CLEANUP
79	Branch: <branch>
80	Path: <project>.worktrees/<slug>
81	Status: DONE \| BLOCKED
82
83	Next:
84	- cd <path> and open the editor there, or
85	- pull the integration branch yourself after confirmed cleanup
86	```
87
88	For cleanup, report `DONE` only when the PR is confirmed `MERGED` or `--force` was used deliberately. Otherwise report `BLOCKED` with the script's reason.
89
90	## References
91
92	- [workflow.md](references/workflow.md) — manual fallback and edge cases
93	- [scripts/](scripts/) — `setup-worktree.sh` and `cleanup-worktree.sh`

People who liked this also viewed

6 picks

Type

using-git-worktrees

5installs5forks

View on GitHub

How to install using-git-worktrees?

alexei-led/cc-thingz/using-git-worktrees

$npx -y skills add alexei-led/cc-thingz --skill using-git-worktrees

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Git Worktrees
2
3	Use one sibling worktree root per project: `<project>.worktrees/<branch-slug>`. Keep the main worktree clean on the integration branch by default. Trivial solo one-liners may stay in the main worktree when a worktree would add pointless ceremony.
4
5	Treat a worktree as a disposable branch folder. Remove it and its branch after the PR merges.
6
7	## Scope
8
9	Use this skill when:
10
11	- starting a feature, fix, or experiment that should not disturb current work
12	- working on multiple branches at once
13	- trying competing approaches
14	- the current worktree has uncommitted changes and the user wants to start something else
15
16	Do not use this skill for:
17
18	- simple branch switching with no parallel work
19	- bulk branch or stale worktree cleanup — use `cleanup-git`
20	- git hook, Gitleaks, `.gitignore`, or config setup — use `configuring-git-hygiene`
21
22	## Create Workflow
23
24	Check state before any `git worktree add`:
25
26	```bash
27	git status --short
28	git branch --show-current
29	git worktree list
30	```
31
32	If the current worktree is dirty, ask whether to commit, stash, or proceed anyway. Do not stash silently.
33
34	Use the helper when available:
35
36	```bash
37	scripts/setup-worktree.sh <branch> [--base <ref>]
38	```
39
40	The helper creates `<project>.worktrees/<branch-slug>` from the main worktree root, handles existing local/remote branches, refuses path conflicts, and refuses dirty state unless `--allow-dirty` is passed after user approval.
41
42	Manual fallback lives in [workflow.md](references/workflow.md).
43
44	## Naming
45
46	- Root: sibling `<project>.worktrees/` directory.
47	- Directory: branch slug only; replace `/` with `-`.
48	- Examples: `fix-cron`, `feature-auth`, `bugfix-issue-123`.
49
50	## Cleanup Workflow
51
52	For one named worktree after PR merge:
53
54	```bash
55	scripts/cleanup-worktree.sh [branch]
56	```
57
58	The helper refuses unless `gh` confirms the PR is `MERGED`. Pass `--force` only after the user confirms the merge without `gh` or confirms the branch should be abandoned.
59
60	For bulk cleanup, stale worktrees, gone upstreams, or merged local branches, use `cleanup-git`.
61
62	Do not run `git pull` as part of cleanup. Pull the integration branch only after confirming the main worktree is checked out and clean.
63
64	## Failure Handling
65
66	- Worktree path exists: pick a different branch/slug; never overwrite.
67	- Branch already exists remotely: check it out without `-b` or use the helper.
68	- Dirty current worktree: ask to commit, stash, or continue with explicit approval.
69	- `git worktree remove` fails because the worktree is dirty: confirm before `--force`.
70	- `git branch -d` fails after squash/rebase PR merge: confirm the PR is `MERGED`, then use `-D`.
71	- Invoked from inside the worktree being removed: change to the main worktree before removing it.
72
73	## Output
74
75	```text
76	WORKTREE READY
77	==============
78	Action: CREATE \| CLEANUP
79	Branch: <branch>
80	Path: <project>.worktrees/<slug>
81	Status: DONE \| BLOCKED
82
83	Next:
84	- cd <path> and open the editor there, or
85	- pull the integration branch yourself after confirmed cleanup
86	```
87
88	For cleanup, report `DONE` only when the PR is confirmed `MERGED` or `--force` was used deliberately. Otherwise report `BLOCKED` with the script's reason.
89
90	## References
91
92	- [workflow.md](references/workflow.md) — manual fallback and edge cases
93	- [scripts/](scripts/) — `setup-worktree.sh` and `cleanup-worktree.sh`

People who liked this also viewed

6 picks

Type