$ ~/registry/skill/obra-collaboration-using-git-worktrees

SKILL

Using Git Worktrees

Name: Using Git Worktrees
Author: obra

Create isolated Git worktrees safely with smart directory selection.

Stars

★ 40

Source

GitHub

Updated

2026-07-05

// securityCaution

Prompt only, no code
Open source

Summary

This is an open-source, prompt-only documentation skill with no required secrets and no declared remote endpoints, so overall risk is low. The main caution is that its instructions may lead to local execution of git, package-manager, and test commands, and may modify .gitignore, create worktrees, and commit changes.

CredentialsLow risk

The material explicitly states that no keys or environment variables are required, and the README does not request tokens, API keys, or account credentials. No obvious credential collection, storage, or misuse path is present.

Network egressLow risk

No remote endpoints are declared, and the skill itself is prompt-only documentation. While the documented npm/pip/go install commands may access normal package registries if actually executed, the material does not indicate exfiltration of user data to third-party or unknown hosts.

Code executionCaution

The README explicitly instructs local shell/git commands such as ls, grep, git worktree add, npm install, cargo build, and pytest. If followed, these would start local processes, install dependencies, and run tests, but they are standard development actions guided by documentation, with no signs of hidden or excessive execution.

Data accessCaution

The documentation reads repository and local files (such as .gitignore and CLAUDE.md) and may write to .gitignore, create worktree directories, change directories, and commit changes. The access scope is mainly limited to the current project and ~/.clank-worktrees under the user's home directory, with no evident request for data access beyond its stated purpose.

Supply chainCaution

The source is an open-source GitHub repository, which is a positive sign because it is auditable. However, it has 0 stars, unknown maintenance status, and no declared license, so community validation and maintenance signals are weak and supply-chain trust should be treated conservatively.

Recommendations

Use it only in trusted repositories, and manually review the suggested shell/git/install commands first.
Before steps that modify .gitignore, create worktrees, or commit changes, verify the target paths and intended diffs.
Run npm/pip/poetry/go/cargo installation steps in a least-privilege environment and prefer pinned dependency sources.
Prefer testing this skill in a temporary branch or isolated development environment first.

Audited by: gpt-5.4 · 2026-06-17

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "Using Git Worktrees" skill from askskill:
1. Download https://raw.githubusercontent.com/obra/clank/main/skills/collaboration/using-git-worktrees/SKILL.md
2. Save it as ~/.claude/skills/using-git-worktrees/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Create an isolated workspace for a new feature

Prompt

Create a new git worktree for the current repository to develop feature/login. Use a clear directory name and first check for branch or directory conflicts.

Expected

Provides safety checks and creates an isolated worktree directory for the new branch.

Set up a temporary worktree for a hotfix

Prompt

Create a temporary git worktree for hotfix/payment-fix from main, place it in an appropriate directory, and verify the repository state before creating it.

Expected

Creates a separate hotfix workspace and confirms the setup is safe and conflict-free.

Standardize worktree directory naming

Prompt

Suggest a standardized git worktree directory path for feature/report-export based on the branch name, and explain why this naming is easier to manage.

Expected

Suggests a clear directory naming scheme and explains its benefits for multi-branch development.

// docs

Using Git Worktrees

Overview

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

Core principle: Systematic directory selection + safety verification = reliable isolation.

Announce at start: "I'm using the Using Git Worktrees skill to set up an isolated workspace."

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If found: Use that directory. If both exist, .worktrees wins.

2. Check CLAUDE.md

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

3. Ask User

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.clank-worktrees/<project-name>/ (global location)

Which would you prefer?

Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify .gitignore before creating worktree:

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If NOT in .gitignore:

Per Jesse's rule "Fix broken things immediately":

Add appropriate line to .gitignore
Commit the change
Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository.

For Global Directory (~/.clank-worktrees)

No .gitignore verification needed - outside project entirely.

Creation Steps

1. Detect Project Name

project=$(basename "$(git rev-parse --show-toplevel)")

2. Create Worktree

# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.clank-worktrees/*)
    path="~/.clank-worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. Run Project Setup

Auto-detect and run appropriate setup:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

5. Report Location

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Situation	Action
`.worktrees/` exists	Use it (verify .gitignore)
`worktrees/` exists	Use it (verify .gitignore)
Both exist	Use `.worktrees/`
Neither exists	Check CLAUDE.md → Ask user
Directory not in .gitignore	Add it immediately + commit
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install