using-git-worktrees

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

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/CYRUS-pinto/pi-bot --skill using-git-worktrees-cyrus-pinto
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/CYRUS-pinto/pi-bot/tree/main/.agents/skills/using-git-worktrees
Command: npx skills add https://github.com/CYRUS-pinto/pi-bot --skill using-git-worktrees-cyrus-pinto

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Starting feature work directly in your main checkout risks polluting your current branch and mixing unrelated changes. This Skill ensures every implementation task begins in an isolated workspace, using your platform's native worktree tools when available and falling back to manual git worktrees otherwise. ## 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 workspaces. - Native Tool Preference with Git Fallback: Uses harness-provided worktree tools (e.g., EnterWorktree) first, and only runs git worktree add when no native tool exists, with sandbox permission-error fallback. - Safe Directory Selection: Picks .worktrees/ or worktrees/ based on existing conventions, verifies the directory is git-ignored, and commits a .gitignore fix if needed. - Use Case: Before implementing a new feature, the Skill sets up .worktrees/my-feature, installs dependencies (npm, cargo, pip, go), runs the test suite to confirm a clean baseline, and reports the workspace is ready. ## Quick Start Set up an isolated git worktree for my new feature branch and verify the project tests pass before I start implementing.

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 workspace with git worktrees?

Run `git worktree add <path> -b <branch-name>` to create a linked worktree on a new branch, then cd into it. Prefer placing it in a `.worktrees/` directory at the project root and verify that directory is listed in .gitignore first.

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 the resolved paths differ, you are in a linked worktree; also run `git rev-parse --show-superproject-working-tree` to rule out being inside a submodule.

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

Use a native tool such as EnterWorktree or a /worktree command whenever one is available, since it manages placement, branching, and cleanup. Only fall back to manual `git worktree add` when no native tool exists.

Why must the worktrees directory be in .gitignore?

An unignored worktree directory causes the entire nested worktree contents to be committed into the parent repository. Verify with `git check-ignore` and commit a .gitignore entry before creating the worktree.

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

A permission error usually means the sandbox blocked worktree creation. In that case, report the restriction and run dependency setup and baseline tests in the current directory instead.

Why run baseline tests before starting feature work?

Running the project test suite first confirms the workspace starts clean, so any later failures can be attributed to your changes rather than pre-existing breakage. If baseline tests fail, report them and ask whether to proceed.