using-git-worktrees

Name: using-git-worktrees
Author: heymegabyte

18stars4forks

How to install using-git-worktrees?

heymegabyte/claude-skills/using-git-worktrees

$npx -y skills add heymegabyte/claude-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 - ensures an isolated workspace exists via native tools or git worktree fallback

Files · 1

View on GitHub

SKILL.md

1	# Using Git Worktrees
2
3	Ensure work runs in an isolated workspace. Detect existing isolation first, then prefer the harness's native worktree tool, then fall back to `git worktree`. Never fight the harness.
4
5	Pairs with `[[main-only-branch]]` — `main` always committed, worktrees for isolation. The harness ships native worktree tools (`EnterWorktree`/`ExitWorktree`); use them over raw git.
6
7	Announce: "Using the using-git-worktrees skill to set up an isolated workspace."
8
9	## Step 0 — detect existing isolation
10
11	```bash
12	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
13	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
14	BRANCH=$(git branch --show-current)
15	```
16
17	- `GIT_DIR != GIT_COMMON` is ALSO true in a submodule. Guard: `git rev-parse --show-superproject-working-tree` returns a path → you're in a submodule, treat as a normal repo.
18	- `GIT_DIR != GIT_COMMON` (not submodule) → already in a linked worktree. Skip to Step 2; do NOT nest another. Report the path + branch (note if detached HEAD — branch creation deferred to finish time).
19	- `GIT_DIR == GIT_COMMON` → normal checkout. If no worktree preference is declared in instructions, ask consent before creating one; honor a declared preference silently; if declined, work in place → Step 2.
20
21	## Step 1 — create the workspace
22
23	1. Native `EnterWorktree` tool (the default) — call it first, always. It owns placement, branch, and cleanup; passing `name` creates, passing `path` switches into an existing one. On exit, `ExitWorktree` with `action: "remove"` or `"keep"`. Never mix with raw `git worktree add` — that creates phantom state the native tool can't see.
24	2. Git fallback (only if no native tool):
25	- Directory priority: declared instruction preference > existing `.worktrees/` (wins over `worktrees/`) > default `.worktrees/`.
26	- Verify ignored before creating: `git check-ignore -q .worktrees`. If not ignored, add to `.gitignore` + commit first — else worktree contents get tracked.
27	- `git worktree add "$LOCATION/$BRANCH_NAME" -b "$BRANCH_NAME" && cd "$_"`.
28	- Permission/sandbox denial on add → tell the user, work in place, run setup + baseline there.
29
30	## Step 2 — setup + baseline
31
32	- Auto-detect and install: `package.json`→`npm install`, `Cargo.toml`→`cargo build`, `requirements.txt`→`pip install -r`, `pyproject.toml`→`poetry install`, `go.mod`→`go mod download`.
33	- Run the project test suite to confirm a clean baseline. Tests fail → report + ask before proceeding (can't tell new bugs from pre-existing). Tests pass → report ready: path, test count, feature.
34
35	## See
36
37	- `[[main-only-branch]]` — worktrees for isolation, main always committed
38	- `finishing-a-development-branch` — merge/PR/cleanup when work is done
39
40	<!-- budget: ~43 -->

People who liked this also viewed

6 picks

Type

using-git-worktrees

18stars4forks

View on GitHub

How to install using-git-worktrees?

heymegabyte/claude-skills/using-git-worktrees

$npx -y skills add heymegabyte/claude-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 - ensures an isolated workspace exists via native tools or git worktree fallback

Files · 1

View on GitHub

SKILL.md

1	# Using Git Worktrees
2
3	Ensure work runs in an isolated workspace. Detect existing isolation first, then prefer the harness's native worktree tool, then fall back to `git worktree`. Never fight the harness.
4
5	Pairs with `[[main-only-branch]]` — `main` always committed, worktrees for isolation. The harness ships native worktree tools (`EnterWorktree`/`ExitWorktree`); use them over raw git.
6
7	Announce: "Using the using-git-worktrees skill to set up an isolated workspace."
8
9	## Step 0 — detect existing isolation
10
11	```bash
12	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
13	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
14	BRANCH=$(git branch --show-current)
15	```
16
17	- `GIT_DIR != GIT_COMMON` is ALSO true in a submodule. Guard: `git rev-parse --show-superproject-working-tree` returns a path → you're in a submodule, treat as a normal repo.
18	- `GIT_DIR != GIT_COMMON` (not submodule) → already in a linked worktree. Skip to Step 2; do NOT nest another. Report the path + branch (note if detached HEAD — branch creation deferred to finish time).
19	- `GIT_DIR == GIT_COMMON` → normal checkout. If no worktree preference is declared in instructions, ask consent before creating one; honor a declared preference silently; if declined, work in place → Step 2.
20
21	## Step 1 — create the workspace
22
23	1. Native `EnterWorktree` tool (the default) — call it first, always. It owns placement, branch, and cleanup; passing `name` creates, passing `path` switches into an existing one. On exit, `ExitWorktree` with `action: "remove"` or `"keep"`. Never mix with raw `git worktree add` — that creates phantom state the native tool can't see.
24	2. Git fallback (only if no native tool):
25	- Directory priority: declared instruction preference > existing `.worktrees/` (wins over `worktrees/`) > default `.worktrees/`.
26	- Verify ignored before creating: `git check-ignore -q .worktrees`. If not ignored, add to `.gitignore` + commit first — else worktree contents get tracked.
27	- `git worktree add "$LOCATION/$BRANCH_NAME" -b "$BRANCH_NAME" && cd "$_"`.
28	- Permission/sandbox denial on add → tell the user, work in place, run setup + baseline there.
29
30	## Step 2 — setup + baseline
31
32	- Auto-detect and install: `package.json`→`npm install`, `Cargo.toml`→`cargo build`, `requirements.txt`→`pip install -r`, `pyproject.toml`→`poetry install`, `go.mod`→`go mod download`.
33	- Run the project test suite to confirm a clean baseline. Tests fail → report + ask before proceeding (can't tell new bugs from pre-existing). Tests pass → report ready: path, test count, feature.
34
35	## See
36
37	- `[[main-only-branch]]` — worktrees for isolation, main always committed
38	- `finishing-a-development-branch` — merge/PR/cleanup when work is done
39
40	<!-- budget: ~43 -->

People who liked this also viewed

6 picks

Type