91 lines
3.2 KiB
Markdown
91 lines
3.2 KiB
Markdown
---
|
|
name: using-git-worktrees
|
|
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
|
|
---
|
|
|
|
# Using Git Worktrees
|
|
|
|
Ensure work happens in an isolated workspace when appropriate. Prefer platform-native worktree tools. Fall back to manual `git worktree` only when no native tool is available.
|
|
|
|
Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
|
|
|
|
## Workflow
|
|
|
|
### 1. Detect Existing Isolation
|
|
|
|
Before creating anything, check whether you are already in a linked worktree:
|
|
|
|
```bash
|
|
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
|
|
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
|
|
BRANCH=$(git branch --show-current)
|
|
git rev-parse --show-superproject-working-tree 2>/dev/null
|
|
```
|
|
|
|
If `GIT_DIR != GIT_COMMON` and `show-superproject-working-tree` is empty, you are already in a linked worktree. Do not create another one. Report the path and branch, then continue to project setup.
|
|
|
|
If `GIT_DIR == GIT_COMMON` or this is a submodule, treat it as a normal repo checkout.
|
|
|
|
### 2. Get Consent
|
|
|
|
If the user has not already declared a worktree preference, ask:
|
|
|
|
> Would you like me to set up an isolated worktree? It protects your current branch from changes.
|
|
|
|
If the user declines, work in place and continue to project setup.
|
|
|
|
### 3. Create Isolated Workspace
|
|
|
|
Use mechanisms in this order:
|
|
|
|
1. Native worktree tool if the platform provides one, such as `EnterWorktree`, `WorktreeCreate`, `/worktree`, or a `--worktree` flag.
|
|
2. Manual `git worktree add` only if no native tool exists.
|
|
|
|
Manual directory priority:
|
|
|
|
1. Explicit user/instruction preference.
|
|
2. Existing project-local `.worktrees/`.
|
|
3. Existing project-local `worktrees/`.
|
|
4. Default to `.worktrees/` at the project root.
|
|
|
|
Before creating a project-local worktree, verify the chosen directory is ignored:
|
|
|
|
```bash
|
|
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
|
|
```
|
|
|
|
If not ignored, add it to `.gitignore`, commit that change, then proceed.
|
|
|
|
```bash
|
|
git worktree add "$path" -b "$BRANCH_NAME"
|
|
cd "$path"
|
|
```
|
|
|
|
If `git worktree add` is blocked by sandbox permissions, tell the user and work in the current directory instead.
|
|
|
|
### 4. Project Setup
|
|
|
|
Auto-detect setup where appropriate:
|
|
|
|
```bash
|
|
if [ -f package.json ]; then npm install; fi
|
|
if [ -f Cargo.toml ]; then cargo build; fi
|
|
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
|
|
if [ -f pyproject.toml ]; then poetry install; fi
|
|
if [ -f go.mod ]; then go mod download; fi
|
|
```
|
|
|
|
### 5. Baseline Verification
|
|
|
|
Run project-appropriate tests before implementation when practical: `npm test`, `cargo test`, `pytest`, `go test ./...`, or equivalent.
|
|
|
|
If tests fail, report failures and ask whether to proceed or investigate. If tests pass, report readiness.
|
|
|
|
## Never
|
|
|
|
- Create a worktree when already in a linked worktree.
|
|
- Use `git worktree add` when a native worktree tool exists.
|
|
- Skip submodule detection.
|
|
- Create a project-local worktree without ignore verification.
|
|
- Proceed from failing baseline tests without telling the user.
|