using-git-worktrees

Creates isolated git worktree workspaces with baseline test verification before feature implementation.

Updated Sep 16, 2022
One-click install
npx skills add https://github.com/ryuya-matsunawa/dotfiles --skill using-git-worktrees-ryuya-matsunawa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/ryuya-matsunawa/dotfiles/tree/main/agents/.agents/skills/using-git-worktrees
Command: npx skills add https://github.com/ryuya-matsunawa/dotfiles --skill using-git-worktrees-ryuya-matsunawa

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, with dependencies installed and a clean test baseline verified before any code changes. ## Core Features & Use Cases - Isolation Detection: Detects whether you are already inside a linked worktree or a git submodule before creating anything, preventing nested worktrees. - Native Tool Preference with Git Fallback: Uses platform-native worktree tools (e.g., EnterWorktree) when available, falling back to manual git worktree add only when no native tool exists. - Safe Directory Conventions: Selects worktree directories by priority (explicit preference > existing .worktrees/ or worktrees/ > default), and verifies the directory is git-ignored before creation. - Use Case: Before implementing a new feature, the Skill sets up .worktrees/my-feature, runs npm install or the equivalent for your stack, executes the test suite, and reports a clean baseline so you can distinguish new bugs from pre-existing failures. ## 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 worktree?▼

Run `git worktree add <path> -b <branch-name>` to create a linked worktree on a new branch, then cd into it. Verify the target directory is git-ignored first if it lives inside the project, such as `.worktrees/`.

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 in a submodule, which shows the same difference.

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

Prefer a native platform tool such as EnterWorktree or a /worktree command when one is available, since it handles placement, branching, and cleanup automatically. Use manual `git worktree add` only as a fallback when no native tool exists.

Why should the worktree directory be added to gitignore?▼

A project-local worktree directory like `.worktrees/` that is not ignored will have its contents tracked by git, polluting git status and risking accidental commits. Verify with `git check-ignore` and commit the gitignore update 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. The fallback is to inform the user, then run project setup and baseline tests in the current directory instead of creating a worktree.

Why run tests before starting feature work in a worktree?▼

Running the test suite establishes a clean baseline so you can distinguish new bugs from pre-existing failures. If tests fail, report the failures and get explicit permission before proceeding with implementation.