home / skills / julianobarbosa / claude-code-skills / using-git-worktrees-skill

using-git-worktrees-skill skill

safe

This skill helps you safely create isolated git worktrees for feature work, selecting directories automatically and verifying safety before committing.

npx playbooks add skill julianobarbosa/claude-code-skills --skill using-git-worktrees-skill

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.3 KB

---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans. Creates isolated git worktrees with smart directory selection and safety verification.
allowed-tools: Read, Bash, Grep, Glob
---

# Git Worktrees

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously.

**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."

## Quick Start

```bash
# Create worktree with new branch
git worktree add .worktrees/feature-auth -b feature/auth

# Create worktree from existing branch
git worktree add .worktrees/bugfix bugfix/issue-123

# List worktrees
git worktree list

# Remove worktree
git worktree remove .worktrees/feature-auth
```

## Directory Selection

1. Check existing: `.worktrees/` or `worktrees/`
2. Check CLAUDE.md for preference
3. Ask user if neither exists

## Safety Requirements

**Before creating project-local worktree:**

```bash
# Verify directory is in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
```

If NOT in .gitignore: Add it immediately and commit.

## References

- [WORKFLOW.md](WORKFLOW.md) - Detailed workflow steps
- [scripts/](scripts/) - Helper scripts

Overview

This skill creates isolated Git worktrees for feature or bugfix work so you can develop without affecting your current workspace. It chooses a safe directory, verifies repository safety rules, and announces when it begins to set up the workspace. Use it before starting feature work or before running implementation plans that must not interfere with the main working tree.

How this skill works

On invocation the skill announces: "I'm using the using-git-worktrees skill to set up an isolated workspace." It inspects the repository for preferred worktree directories (.worktrees/ or worktrees/) and for .gitignore entries, verifies safety, and then runs git worktree add to create a worktree with a new or existing branch. It can list and remove worktrees and suggests committing any .gitignore changes automatically when required.

When to use it

Starting a new feature that must be isolated from the current working directory
Working on multiple branches in parallel without changing your main workspace
Preparing to run implementation plans or experiments that might modify tracked files
Creating a short-lived environment for a code review or demo
When you need a reproducible, project-local workspace tied to the same repository

Best practices

Prefer .worktrees/ or worktrees/ at repository root; follow existing project conventions
Ensure the chosen worktree directory is listed in .gitignore before creating it
Use descriptive branch names (e.g., feature/auth or bugfix/issue-123) when adding worktrees
Commit the .gitignore change immediately if the directory was not ignored
List and remove stale worktrees regularly with git worktree list and git worktree remove

Example use cases

Create a new worktree for a feature branch: git worktree add .worktrees/feature-auth -b feature/auth
Open a worktree for an existing bugfix branch: git worktree add .worktrees/bugfix bugfix/issue-123
Verify current worktrees before CI runs using git worktree list to avoid conflicts
Tear down a finished worktree to free space: git worktree remove .worktrees/feature-auth

FAQ

What does the skill announce when it starts?

It announces: "I'm using the using-git-worktrees skill to set up an isolated workspace."

What safety check does it perform before creating a local worktree?

It verifies the selected directory is present in .gitignore and, if not, adds and commits the ignore entry before creating the worktree.