git-worktree

Create isolated git worktrees for parallel feature development.

Updated Jul 11, 2022
One-click install
npx skills add https://github.com/kvnxiao/.dotfiles --skill git-worktree-kvnxiao
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: git-worktree
Source: https://github.com/kvnxiao/.dotfiles/tree/main/claude/skills/git-worktree
Command: npx skills add https://github.com/kvnxiao/.dotfiles --skill git-worktree-kvnxiao

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires git, and includes scripts (resource) components.

What problem does it solve?

This skill helps developers isolate experimental work by creating independent git worktrees, so changes to new features don’t affect the main working directory.

Core Features & Use Cases

  • Create worktrees: spawn dedicated worktrees under ~/.claude-worktrees/<repo>/<branch> for parallel development.
  • Automatic base handling: derives the default branch from origin HEAD when BASE_BRANCH is not provided.
  • Include file synchronization: copies listed files from the source repo to the new worktree using .worktreeinclude.
  • Management commands: remove a worktree and clean up empty parent directories to keep the structure tidy.

Quick Start

BRANCH_NAME="feature/my-feature" ./scripts/create-worktree.sh BRANCH_NAME="eng-123/fix-bug" TICKET_URL="https://linear.app/team/issue/ENG-123/fix-bug" ./scripts/create-worktree.sh BRANCH_NAME="feature/x" BASE_BRANCH="develop" ./scripts/create-worktree.sh

Frequently Asked Questions about git-worktree

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

FAQPage Schema
How do I create isolated git worktrees for parallel feature development?

Creating isolated git worktrees spawns dedicated working directories under ~/.claude-worktrees/<repo>/<branch>, allowing parallel branch development without affecting your main checkout. You run create-worktree.sh with a BRANCH_NAME environment variable to output the new worktree path.

What is the best way to manage multiple git branches without context switching in one directory?

Git worktrees provide isolated working directories for each branch, eliminating disruptive context switching. This skill creates worktrees under a dedicated structure and outputs BRANCH_NAME, WORKTREE_PATH, and DEFAULT_BRANCH as plain text for immediate use in your workflow.

How do I set a custom base branch when creating a git worktree?

To set a custom base branch when creating a git worktree, provide the BASE_BRANCH environment variable when running the creation script. If BASE_BRANCH is not provided, the skill automatically derives the default base branch from the repository's origin HEAD.

Can I synchronize specific configuration files from my main repo into a new worktree?

Yes, you can synchronize specific files by listing them in a .worktreeinclude file. When the worktree is created, the skill copies these listed files from the source repository into the new worktree directory to maintain your local configuration.

How do I safely remove a git worktree and clean up empty parent directories?

The skill includes management commands to safely remove a git worktree and automatically clean up any empty parent directories left behind. This keeps your ~/.claude-worktrees structure tidy after finishing or abandoning feature work.

Do I need to install any extra dependencies to use git worktrees for isolated branch work?

You only need the standard git command-line tool installed, as the skill relies on built-in git worktree commands and simple shell scripts. No additional dependencies or complex environment setup beyond git are required to isolate your feature work.