using-git-worktrees

Creates isolated git worktree workspaces with native tool detection and baseline test verification.

Updated Jul 30, 2026
One-click install
npx skills add https://github.com/johsquaree/claude-basic-docs --skill using-git-worktrees-johsquaree
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/johsquaree/claude-basic-docs/tree/main/.claude/skills/using-git-worktrees
Command: npx skills add https://github.com/johsquaree/claude-basic-docs --skill using-git-worktrees-johsquaree

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Feature work done directly in your main checkout risks polluting your current branch and mixing unrelated changes. This Skill ensures every implementation task starts in an isolated workspace, detecting existing isolation first and falling back to manual git worktrees only when no native tool exists. ## Core Features & Use Cases - Isolation Detection: Checks whether you are already inside a linked worktree or a submodule before creating anything, avoiding duplicate or phantom worktrees. - Native Tool Preference: Uses platform-native worktree tools (like EnterWorktree or /worktree commands) when available, falling back to git worktree add only when necessary. - Safe Directory Handling: Selects .worktrees/ or worktrees/ directories, verifies they are git-ignored, and commits the ignore rule before creating the worktree. - Use Case: Before implementing a new feature, the Skill sets up an isolated worktree, installs dependencies (npm, cargo, pip, go), runs baseline tests, and reports a clean starting state. ## Quick Start Ask the assistant to set up an isolated worktree for your next feature and verify the project tests pass before starting implementation.

Frequently Asked Questions about using-git-worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an isolated git worktree for feature work?

Run `git worktree add <path> -b <branch-name>` to create a linked worktree on a new branch. The Skill first checks for native worktree tools and existing isolation, then verifies the target directory is git-ignored before creating anything.

How do I check if I am already inside a git worktree?

Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`; if they differ, you are in a linked worktree. Also run `git rev-parse --show-superproject-working-tree` to rule out being inside a submodule, which shows the same signal.

Should I use git worktree add or a native worktree tool?

Prefer a native tool such as EnterWorktree or a /worktree command when one is available, since it manages placement, branching, and cleanup. Manual `git worktree add` is only a fallback and can create state the harness cannot track.

Why must the worktree directory be in .gitignore?

An unignored worktree directory risks committing the entire nested worktree contents into the repository. The Skill runs `git check-ignore` and adds the directory to .gitignore with a commit before creating the worktree.

What happens if git worktree add fails with a permission error?

A permission error usually means sandbox restrictions blocked worktree creation. The Skill reports the sandbox denial and proceeds with setup and baseline tests in the current directory instead of failing outright.