using-git-worktrees

Name: using-git-worktrees
Author: totvs

108stars50forks

How to install using-git-worktrees?

totvs/engpro-advpl-tlpp-skills/using-git-worktrees

$npx -y skills add totvs/engpro-advpl-tlpp-skills --skill using-git-worktrees

Installs into the current project.

Summary

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

Files · 1

View on GitHub

SKILL.md

1	# Using Git Worktrees
2
3	## Overview
4
5	Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
6
7	Core principle: Systematic directory selection + safety verification = reliable isolation.
8
9	Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
10
11	## Directory Selection Process
12
13	Follow this priority order:
14
15	### 1. Check Existing Directories
16
17	```bash
18	# Check in priority order
19	ls -d .worktrees 2>/dev/null # Preferred (hidden)
20	ls -d worktrees 2>/dev/null # Alternative
21	```
22
23	If found: Use that directory. If both exist, `.worktrees` wins.
24
25	### 2. Check CLAUDE.md
26
27	```bash
28	grep -i "worktree.*director" CLAUDE.md 2>/dev/null
29	```
30
31	If preference specified: Use it without asking.
32
33	### 3. Ask User
34
35	If no directory exists and no CLAUDE.md preference:
36
37	```
38	No worktree directory found. Where should I create worktrees?
39
40	1. .worktrees/ (project-local, hidden)
41	2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
42
43	Which would you prefer?
44	```
45
46	## Safety Verification
47
48	### For Project-Local Directories (.worktrees or worktrees)
49
50	MUST verify directory is ignored before creating worktree:
51
52	```bash
53	# Check if directory is ignored (respects local, global, and system gitignore)
54	git check-ignore -q .worktrees 2>/dev/null \|\| git check-ignore -q worktrees 2>/dev/null
55	```
56
57	If NOT ignored:
58
59	Per Jesse's rule "Fix broken things immediately":
60	1. Add appropriate line to .gitignore
61	2. Commit the change
62	3. Proceed with worktree creation
63
64	Why critical: Prevents accidentally committing worktree contents to repository.
65
66	### For Global Directory (~/.config/superpowers/worktrees)
67
68	No .gitignore verification needed - outside project entirely.
69
70	## Creation Steps
71
72	### 1. Detect Project Name
73
74	```bash
75	project=$(basename "$(git rev-parse --show-toplevel)")
76	```
77
78	### 2. Create Worktree
79
80	```bash
81	# Determine full path
82	case $LOCATION in
83	.worktrees\|worktrees)
84	path="$LOCATION/$BRANCH_NAME"
85	;;
86	~/.config/superpowers/worktrees/*)
87	path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
88	;;
89	esac
90
91	# Create worktree with new branch
92	git worktree add "$path" -b "$BRANCH_NAME"
93	cd "$path"
94	```
95
96	### 3. Run Project Setup
97
98	Auto-detect and run appropriate setup:
99
100	```bash
101	# Node.js
102	if [ -f package.json ]; then npm install; fi
103
104	# Rust
105	if [ -f Cargo.toml ]; then cargo build; fi
106
107	# Python
108	if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
109	if [ -f pyproject.toml ]; then poetry install; fi
110
111	# Go
112	if [ -f go.mod ]; then go mod download; fi
113	```
114
115	### 4. Verify Clean Baseline
116
117	Run tests to ensure worktree starts clean:
118
119	```bash
120	# Examples - use project-appropriate command
121	npm test
122	cargo test
123	pytest
124	go test ./...
125	```
126
127	If tests fail: Report failures, ask whether to proceed or investigate.
128
129	If tests pass: Report ready.
130
131	### 5. Report Location
132
133	```
134	Worktree ready at <full-path>
135	Tests passing (<N> tests, 0 failures)
136	Ready to implement <feature-name>
137	```
138
139	## Quick Reference
140
141	\| Situation \| Action \|
142	\|-----------\|--------\|
143	\| `.worktrees/` exists \| Use it (verify ignored) \|
144	\| `worktrees/` exists \| Use it (verify ignored) \|
145	\| Both exist \| Use `.worktrees/` \|
146	\| Neither exists \| Check CLAUDE.md → Ask user \|
147	\| Directory not ignored \| Add to .gitignore + commit \|
148	\| Tests fail during baseline \| Report failures + ask \|
149	\| No package.json/Cargo.toml \| Skip dependency install \|
150
151	## Common Mistakes
152
153	### Skipping ignore verification
154
155	- Problem: Worktree contents get tracked, pollute git status
156	- Fix: Always use `git check-ignore` before creating project-local worktree
157
158	### Assuming directory location
159
160	- Problem: Creates inconsistency, violates project conventions
161	- Fix: Follow priority: existing > CLAUDE.md > ask
162
163	### Proceeding with failing tests
164
165	- Problem: Can't distinguish new bugs from pre-existing issues
166	- Fix: Report failures, get explicit permission to proceed
167
168	### Hardcoding setup commands
169
170	- Problem: Breaks on projects using different tools
171	- Fix: Auto-detect from project files (package.json, etc.)
172
173	## Example Workflow
174
175	```
176	You: I'm using the using-git-worktrees skill to set up an isolated workspace.
177
178	[Check .worktrees/ - exists]
179	[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
180	[Create worktree: git worktree add .worktrees/auth -b feature/auth]
181	[Run npm install]
182	[Run npm test - 47 passing]
183
184	Worktree ready at /Users/jesse/myproject/.worktrees/auth
185	Tests passing (47 tests, 0 failures)
186	Ready to implement auth feature
187	```
188
189	## Red Flags
190
191	Never:
192	- Create worktree without verifying it's ignored (project-local)
193	- Skip baseline test verification
194	- Proceed with failing tests without asking
195	- Assum

People who liked this also viewed

6 picks

Type

using-git-worktrees

108stars50forks

View on GitHub

How to install using-git-worktrees?

totvs/engpro-advpl-tlpp-skills/using-git-worktrees

$npx -y skills add totvs/engpro-advpl-tlpp-skills --skill using-git-worktrees

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Using Git Worktrees
2
3	## Overview
4
5	Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
6
7	Core principle: Systematic directory selection + safety verification = reliable isolation.
8
9	Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
10
11	## Directory Selection Process
12
13	Follow this priority order:
14
15	### 1. Check Existing Directories
16
17	```bash
18	# Check in priority order
19	ls -d .worktrees 2>/dev/null # Preferred (hidden)
20	ls -d worktrees 2>/dev/null # Alternative
21	```
22
23	If found: Use that directory. If both exist, `.worktrees` wins.
24
25	### 2. Check CLAUDE.md
26
27	```bash
28	grep -i "worktree.*director" CLAUDE.md 2>/dev/null
29	```
30
31	If preference specified: Use it without asking.
32
33	### 3. Ask User
34
35	If no directory exists and no CLAUDE.md preference:
36
37	```
38	No worktree directory found. Where should I create worktrees?
39
40	1. .worktrees/ (project-local, hidden)
41	2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
42
43	Which would you prefer?
44	```
45
46	## Safety Verification
47
48	### For Project-Local Directories (.worktrees or worktrees)
49
50	MUST verify directory is ignored before creating worktree:
51
52	```bash
53	# Check if directory is ignored (respects local, global, and system gitignore)
54	git check-ignore -q .worktrees 2>/dev/null \|\| git check-ignore -q worktrees 2>/dev/null
55	```
56
57	If NOT ignored:
58
59	Per Jesse's rule "Fix broken things immediately":
60	1. Add appropriate line to .gitignore
61	2. Commit the change
62	3. Proceed with worktree creation
63
64	Why critical: Prevents accidentally committing worktree contents to repository.
65
66	### For Global Directory (~/.config/superpowers/worktrees)
67
68	No .gitignore verification needed - outside project entirely.
69
70	## Creation Steps
71
72	### 1. Detect Project Name
73
74	```bash
75	project=$(basename "$(git rev-parse --show-toplevel)")
76	```
77
78	### 2. Create Worktree
79
80	```bash
81	# Determine full path
82	case $LOCATION in
83	.worktrees\|worktrees)
84	path="$LOCATION/$BRANCH_NAME"
85	;;
86	~/.config/superpowers/worktrees/*)
87	path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
88	;;
89	esac
90
91	# Create worktree with new branch
92	git worktree add "$path" -b "$BRANCH_NAME"
93	cd "$path"
94	```
95
96	### 3. Run Project Setup
97
98	Auto-detect and run appropriate setup:
99
100	```bash
101	# Node.js
102	if [ -f package.json ]; then npm install; fi
103
104	# Rust
105	if [ -f Cargo.toml ]; then cargo build; fi
106
107	# Python
108	if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
109	if [ -f pyproject.toml ]; then poetry install; fi
110
111	# Go
112	if [ -f go.mod ]; then go mod download; fi
113	```
114
115	### 4. Verify Clean Baseline
116
117	Run tests to ensure worktree starts clean:
118
119	```bash
120	# Examples - use project-appropriate command
121	npm test
122	cargo test
123	pytest
124	go test ./...
125	```
126
127	If tests fail: Report failures, ask whether to proceed or investigate.
128
129	If tests pass: Report ready.
130
131	### 5. Report Location
132
133	```
134	Worktree ready at <full-path>
135	Tests passing (<N> tests, 0 failures)
136	Ready to implement <feature-name>
137	```
138
139	## Quick Reference
140
141	\| Situation \| Action \|
142	\|-----------\|--------\|
143	\| `.worktrees/` exists \| Use it (verify ignored) \|
144	\| `worktrees/` exists \| Use it (verify ignored) \|
145	\| Both exist \| Use `.worktrees/` \|
146	\| Neither exists \| Check CLAUDE.md → Ask user \|
147	\| Directory not ignored \| Add to .gitignore + commit \|
148	\| Tests fail during baseline \| Report failures + ask \|
149	\| No package.json/Cargo.toml \| Skip dependency install \|
150
151	## Common Mistakes
152
153	### Skipping ignore verification
154
155	- Problem: Worktree contents get tracked, pollute git status
156	- Fix: Always use `git check-ignore` before creating project-local worktree
157
158	### Assuming directory location
159
160	- Problem: Creates inconsistency, violates project conventions
161	- Fix: Follow priority: existing > CLAUDE.md > ask
162
163	### Proceeding with failing tests
164
165	- Problem: Can't distinguish new bugs from pre-existing issues
166	- Fix: Report failures, get explicit permission to proceed
167
168	### Hardcoding setup commands
169
170	- Problem: Breaks on projects using different tools
171	- Fix: Auto-detect from project files (package.json, etc.)
172
173	## Example Workflow
174
175	```
176	You: I'm using the using-git-worktrees skill to set up an isolated workspace.
177
178	[Check .worktrees/ - exists]
179	[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
180	[Create worktree: git worktree add .worktrees/auth -b feature/auth]
181	[Run npm install]
182	[Run npm test - 47 passing]
183
184	Worktree ready at /Users/jesse/myproject/.worktrees/auth
185	Tests passing (47 tests, 0 failures)
186	Ready to implement auth feature
187	```
188
189	## Red Flags
190
191	Never:
192	- Create worktree without verifying it's ignored (project-local)
193	- Skip baseline test verification
194	- Proceed with failing tests without asking
195	- Assum

People who liked this also viewed

6 picks

Type