using-git-worktrees

Creates isolated git worktrees with directory selection, ignore verification, and baseline test validation.

Updated May 19, 2026
One-click install
npx skills add https://github.com/davidsunglee/pi-flow --skill using-git-worktrees-davidsunglee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/davidsunglee/pi-flow/tree/main/packages/pi-flow-core/skills/using-git-worktrees
Command: npx skills add https://github.com/davidsunglee/pi-flow --skill using-git-worktrees-davidsunglee

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Starting feature work in your main checkout risks mixing uncommitted changes, breaking your current branch state, or forcing disruptive context switches. This Skill sets up an isolated git worktree so you can work on a separate branch without touching your primary workspace. ## Core Features & Use Cases - Systematic Directory Selection: Follows a priority order of existing .worktrees/ or worktrees/ directories, then project configuration, then an explicit user prompt, so worktree locations stay consistent with project conventions. - Safety Verification: Verifies project-local worktree directories are git-ignored before creation, and automatically fixes and commits the .gitignore entry if they are not, preventing accidental commits of worktree contents. - Automated Setup and Baseline Validation: Auto-detects the project type (Node.js, Rust, Python, Go) to install dependencies, then runs the project's test suite to confirm a clean baseline before work begins. - Use Case: You need to implement a new feature while your main checkout has work in progress. Invoke this Skill to create .worktrees/my-feature on a new branch, install dependencies, verify tests pass, and report the ready-to-use path. ## Quick Start Create an isolated git worktree for my new feature branch and verify the project tests pass before I start working.

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 a git worktree for a new feature branch?▼

Run git worktree add with a target path and the -b flag to create a new branch, for example git worktree add .worktrees/my-feature -b my-feature. This Skill automates path selection, branch creation, dependency installation, and baseline test verification.

Where should git worktrees be stored in a project?▼

Prefer a project-local .worktrees/ directory, falling back to worktrees/ if it already exists. If neither exists, check project configuration for a preference, otherwise choose between .worktrees/ or a global location like ~/.config/pi/worktrees/<project-name>/.

Why must the worktree directory be in .gitignore?▼

Project-local worktree directories must be git-ignored so their contents are never tracked or committed to the repository. Verify with git check-ignore before creating the worktree; if not ignored, add the entry to .gitignore and commit it first.

Can branch names with slashes be used for worktrees?▼

Avoid slashes in branch names for worktrees because git worktree add creates nested subdirectories matching the slashes, complicating cleanup and path handling. Use flat names like execute-plan-enhancements or a non-slash prefix like feat-foo.

What happens if baseline tests fail in a new worktree?▼

If the baseline test run fails, the failures are reported and you are asked whether to proceed or investigate. Work does not continue on a failing baseline without explicit permission, so new bugs are not confused with pre-existing issues.