Initial commit
This commit is contained in:
Zhongwei Li
625
skills/git-worktrees/references/best_practices.md
Normal file
625
skills/git-worktrees/references/best_practices.md
Normal file
@@ -0,0 +1,625 @@
|
||||
# Git Worktrees Best Practices
|
||||
|
||||
Proven patterns and recommendations for using worktrees effectively with Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Naming Conventions](#naming-conventions)
|
||||
2. [Directory Organization](#directory-organization)
|
||||
3. [When to Use Worktrees](#when-to-use-worktrees)
|
||||
4. [Lifecycle Management](#lifecycle-management)
|
||||
5. [Performance Optimization](#performance-optimization)
|
||||
6. [Team Collaboration](#team-collaboration)
|
||||
7. [Claude Code Integration](#claude-code-integration)
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Branch Names
|
||||
|
||||
**Use descriptive, hierarchical names:**
|
||||
|
||||
```
|
||||
<type>-<short-description>
|
||||
|
||||
Types:
|
||||
- feature-* New features
|
||||
- refactor-* Code refactoring
|
||||
- hotfix-* Urgent bug fixes
|
||||
- experiment-* Experimental changes
|
||||
- review-* Code reviews
|
||||
- test-* Testing branches
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
✅ Good:
|
||||
- feature-user-authentication
|
||||
- refactor-api-layer
|
||||
- hotfix-login-redirect
|
||||
- experiment-new-db-schema
|
||||
- review-pr-123
|
||||
|
||||
❌ Bad:
|
||||
- test
|
||||
- wt1
|
||||
- fixes
|
||||
- my-branch
|
||||
- abc
|
||||
```
|
||||
|
||||
**Why it matters:**
|
||||
- Easy to identify purpose months later
|
||||
- Clear for team members
|
||||
- Searchable and filterable
|
||||
- Self-documenting
|
||||
|
||||
---
|
||||
|
||||
### Directory Names
|
||||
|
||||
**Match branch names with prefix:**
|
||||
|
||||
```bash
|
||||
# Pattern: <repo-name>-<branch-name>
|
||||
|
||||
Example repository: myapp
|
||||
|
||||
Worktrees:
|
||||
- myapp-feature-api
|
||||
- myapp-refactor-auth
|
||||
- myapp-hotfix-login
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Immediately recognize which repo
|
||||
- See all worktrees with `ls ../`
|
||||
- Avoid confusion with multiple projects
|
||||
|
||||
**Alternative patterns:**
|
||||
```bash
|
||||
# By date (for temporary worktrees)
|
||||
myapp-2025-01-15-hotfix
|
||||
|
||||
# By ticket number
|
||||
myapp-JIRA-1234
|
||||
|
||||
# By developer (in shared environments)
|
||||
myapp-john-feature-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Directory Organization
|
||||
|
||||
### Recommended Structure
|
||||
|
||||
```
|
||||
~/projects/
|
||||
└── myapp/ # Main worktree (main branch)
|
||||
├── myapp-feature-api/ # Feature worktree
|
||||
├── myapp-feature-ui/ # Feature worktree
|
||||
├── myapp-refactor-auth/ # Refactor worktree
|
||||
└── myapp-hotfix-login/ # Hotfix worktree
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- All related worktrees grouped together
|
||||
- Easy to find with `ls ../`
|
||||
- Clean navigation between worktrees
|
||||
|
||||
---
|
||||
|
||||
### Alternative: Dedicated Worktrees Directory
|
||||
|
||||
```
|
||||
~/projects/
|
||||
├── myapp/ # Main worktree
|
||||
└── worktrees/
|
||||
├── myapp-feature-api/
|
||||
├── myapp-feature-ui/
|
||||
└── myapp-refactor-auth/
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Working with many worktrees
|
||||
- Want clear separation
|
||||
- Sharing machine with others
|
||||
|
||||
---
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
```
|
||||
❌ Nested worktrees:
|
||||
~/projects/
|
||||
└── myapp/
|
||||
└── feature-api/ # Don't nest inside repo
|
||||
|
||||
❌ Unrelated locations:
|
||||
~/projects/myapp/ # Main
|
||||
~/Documents/api-feature/ # Confusing!
|
||||
/tmp/worktree-123/ # Gets deleted
|
||||
|
||||
❌ Generic names:
|
||||
~/projects/myapp/
|
||||
├── wt1/
|
||||
├── temp/
|
||||
└── test/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Worktrees
|
||||
|
||||
### ✅ Use Worktrees For:
|
||||
|
||||
**1. Parallel AI Development**
|
||||
- Multiple Claude Code sessions on different features
|
||||
- Long-running Claude tasks while you continue work
|
||||
- Experimenting with different AI approaches
|
||||
|
||||
**2. Context Switching**
|
||||
- Hotfix needed while working on feature
|
||||
- Code review without interrupting current work
|
||||
- Testing changes in isolation
|
||||
|
||||
**3. Comparison & Testing**
|
||||
- Compare two implementations side-by-side
|
||||
- Test different approaches
|
||||
- A/B testing code changes
|
||||
|
||||
**4. Long-Running Tasks**
|
||||
- Major refactors
|
||||
- Database migrations
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
### ❌ DON'T Use Worktrees For:
|
||||
|
||||
**1. Quick Branch Switches**
|
||||
```bash
|
||||
# Just use checkout for quick switches
|
||||
git checkout other-branch
|
||||
# Not: git worktree add ../temp other-branch
|
||||
```
|
||||
|
||||
**2. Very Short-Lived Work** (< 1 hour)
|
||||
```bash
|
||||
# Use stash instead
|
||||
git stash push -m "Quick fix"
|
||||
git checkout main
|
||||
# ... do fix ...
|
||||
git checkout original-branch
|
||||
git stash pop
|
||||
```
|
||||
|
||||
**3. Simple Merges**
|
||||
```bash
|
||||
# Direct merge is simpler
|
||||
git merge feature-branch
|
||||
# Not: git worktree add ../temp feature-branch
|
||||
```
|
||||
|
||||
**4. Single-Tasking Workflow**
|
||||
- If you work on one thing at a time, branches are fine
|
||||
- Worktrees add overhead without benefit
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle Management
|
||||
|
||||
### Creation Checklist
|
||||
|
||||
**Before creating:**
|
||||
- [ ] Is the branch name descriptive?
|
||||
- [ ] Is this task long enough to warrant a worktree?
|
||||
- [ ] Will I need to switch contexts during this work?
|
||||
- [ ] Do I have disk space? (worktrees duplicate files)
|
||||
|
||||
**During creation:**
|
||||
- [ ] Use the create script: `scripts/create_worktree.sh`
|
||||
- [ ] Note the path for later
|
||||
- [ ] Add to tracking system if managing many
|
||||
|
||||
---
|
||||
|
||||
### Active Maintenance
|
||||
|
||||
**Daily:**
|
||||
- Check status: `scripts/list_worktrees.sh`
|
||||
- Commit progress in each worktree
|
||||
- Sync with main if needed: `scripts/sync_worktree.sh`
|
||||
|
||||
**Weekly:**
|
||||
- Clean up merged worktrees: `scripts/cleanup_worktrees.sh`
|
||||
- Review active worktrees
|
||||
- Archive or delete abandoned experiments
|
||||
|
||||
**Monthly:**
|
||||
- Audit all worktrees
|
||||
- Remove stale worktrees
|
||||
- Update documentation/notes
|
||||
|
||||
---
|
||||
|
||||
### Cleanup Workflow
|
||||
|
||||
**When to clean up:**
|
||||
- ✅ Branch merged to main
|
||||
- ✅ Task completed
|
||||
- ✅ Experiment concluded
|
||||
- ✅ Review finished
|
||||
- ⚠️ Abandoned (but check for uncommitted work!)
|
||||
|
||||
**How to clean up safely:**
|
||||
```bash
|
||||
# 1. Check status
|
||||
cd ../myapp-feature-api
|
||||
git status
|
||||
|
||||
# 2. Check if merged
|
||||
cd <main-repo>
|
||||
git branch --merged main | grep feature-api
|
||||
|
||||
# 3. If merged, safe to remove
|
||||
scripts/cleanup_worktrees.sh
|
||||
# Select the worktree
|
||||
|
||||
# 4. Verify removal
|
||||
scripts/list_worktrees.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Disk Space Management
|
||||
|
||||
**Monitor usage:**
|
||||
```bash
|
||||
# Check worktree sizes
|
||||
du -sh ../myapp-*
|
||||
|
||||
# Check total usage
|
||||
du -sh ../
|
||||
```
|
||||
|
||||
**Optimization strategies:**
|
||||
|
||||
**1. Use Sparse Checkout** (for large repos):
|
||||
```bash
|
||||
cd worktree
|
||||
git sparse-checkout init
|
||||
git sparse-checkout set src/ tests/
|
||||
```
|
||||
|
||||
**2. Clean Build Artifacts:**
|
||||
```bash
|
||||
# Add to .gitignore
|
||||
node_modules/
|
||||
target/
|
||||
build/
|
||||
*.pyc
|
||||
```
|
||||
|
||||
**3. Limit Concurrent Worktrees:**
|
||||
- Keep 3-5 active worktrees maximum
|
||||
- Clean up old ones regularly
|
||||
|
||||
---
|
||||
|
||||
### Git Performance
|
||||
|
||||
**Shared objects are efficient:**
|
||||
- Git history is shared (not duplicated)
|
||||
- Only working files are duplicated
|
||||
- Refs and config are shared
|
||||
|
||||
**Keep worktrees healthy:**
|
||||
```bash
|
||||
# Prune stale references regularly
|
||||
git worktree prune
|
||||
|
||||
# Garbage collect periodically
|
||||
git gc --aggressive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Team Collaboration
|
||||
|
||||
### Communication
|
||||
|
||||
**Document active worktrees:**
|
||||
```markdown
|
||||
# In your team wiki or README
|
||||
|
||||
## Active Worktrees
|
||||
|
||||
| Developer | Worktree | Branch | Purpose | Started |
|
||||
|-----------|----------|--------|---------|---------|
|
||||
| Alice | feature-api | feature-api | New API endpoints | 2025-01-10 |
|
||||
| Bob | refactor-db | refactor-db | Database refactor | 2025-01-08 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Sharing Workflow (Not Worktrees!)
|
||||
|
||||
**What to share:**
|
||||
```bash
|
||||
# Push your branch
|
||||
cd ../myapp-feature-api
|
||||
git push origin feature-api
|
||||
|
||||
# Teammate creates their own worktree
|
||||
git worktree add ../myapp-feature-api feature-api
|
||||
```
|
||||
|
||||
**Don't try to:**
|
||||
- Share worktree directories (they're local)
|
||||
- Commit worktree paths to git
|
||||
- Sync worktree locations across machines
|
||||
|
||||
---
|
||||
|
||||
### Team Conventions
|
||||
|
||||
**Establish team standards:**
|
||||
|
||||
```yaml
|
||||
# .github/WORKTREE_GUIDE.md
|
||||
|
||||
Naming Convention:
|
||||
format: <type>-<description>
|
||||
types: feature, refactor, hotfix, experiment
|
||||
|
||||
Directory Structure:
|
||||
location: Sibling to main repo
|
||||
format: <repo-name>-<branch-name>
|
||||
|
||||
Cleanup Policy:
|
||||
frequency: Weekly
|
||||
criteria: Merged branches, abandoned > 30 days
|
||||
|
||||
Scripts:
|
||||
create: scripts/create_worktree.sh
|
||||
list: scripts/list_worktrees.sh
|
||||
cleanup: scripts/cleanup_worktrees.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Integration
|
||||
|
||||
### Always Run /init
|
||||
|
||||
**Critical step when opening a new worktree in Claude Code:**
|
||||
|
||||
```
|
||||
1. Create worktree
|
||||
2. Open Claude Code in worktree directory
|
||||
3. Run: /init
|
||||
4. Give Claude the task
|
||||
```
|
||||
|
||||
**Why `/init` matters:**
|
||||
- Orients Claude to codebase structure
|
||||
- Establishes proper context
|
||||
- Enables correct file navigation
|
||||
- Prevents confusion about file locations
|
||||
|
||||
---
|
||||
|
||||
### Optimal Claude Code Workflow
|
||||
|
||||
**Pattern 1: Parallel Features**
|
||||
|
||||
```bash
|
||||
# Terminal 1: Create first feature worktree
|
||||
scripts/create_worktree.sh
|
||||
# Name: feature-api
|
||||
|
||||
# Terminal 2: Create second feature worktree
|
||||
scripts/create_worktree.sh
|
||||
# Name: feature-ui
|
||||
|
||||
# Claude Session 1: Open feature-api worktree
|
||||
cd ../myapp-feature-api
|
||||
code .
|
||||
# In Claude: /init
|
||||
# Task: "Build REST API for user management"
|
||||
|
||||
# Claude Session 2: Open feature-ui worktree
|
||||
cd ../myapp-feature-ui
|
||||
code .
|
||||
# In Claude: /init
|
||||
# Task: "Create React UI for user management"
|
||||
|
||||
# Monitor both
|
||||
scripts/list_worktrees.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Pattern 2: Review + Development**
|
||||
|
||||
```bash
|
||||
# Claude working on feature
|
||||
cd ../myapp-feature-xyz
|
||||
# Claude is actively coding
|
||||
|
||||
# You need to review a PR
|
||||
scripts/create_worktree.sh
|
||||
# Name: review-pr-123
|
||||
|
||||
# Open separate editor for review
|
||||
cd ../myapp-review-pr-123
|
||||
code .
|
||||
|
||||
# No context switching needed!
|
||||
# Claude continues in feature worktree
|
||||
# You review in review worktree
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Managing Multiple Claude Sessions
|
||||
|
||||
**Track active sessions:**
|
||||
```
|
||||
Feature API → ../myapp-feature-api → Port 3001
|
||||
Feature UI → ../myapp-feature-ui → Port 3002
|
||||
Refactor Auth → ../myapp-refactor-auth → Port 3003
|
||||
```
|
||||
|
||||
**Best practices:**
|
||||
- Limit to 3-5 concurrent Claude sessions
|
||||
- Use descriptive terminal/window titles
|
||||
- Keep a log of what each Claude is working on
|
||||
- Monitor progress regularly
|
||||
|
||||
---
|
||||
|
||||
### When Claude Gets "Lost"
|
||||
|
||||
**Symptoms:**
|
||||
- Can't find files
|
||||
- References wrong paths
|
||||
- Seems confused about structure
|
||||
|
||||
**Solution:**
|
||||
```
|
||||
1. Run: /init
|
||||
2. If that doesn't help, restart Claude session
|
||||
3. Verify you're in correct worktree: pwd
|
||||
4. Check git branch: git branch --show-current
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls & Solutions
|
||||
|
||||
### Pitfall 1: Too Many Worktrees
|
||||
|
||||
**Problem:** Managing 10+ worktrees becomes overwhelming
|
||||
|
||||
**Solution:**
|
||||
- Limit to 3-5 active worktrees
|
||||
- Clean up weekly
|
||||
- Use projects/issues for tracking longer-term work
|
||||
|
||||
---
|
||||
|
||||
### Pitfall 2: Forgetting to Sync
|
||||
|
||||
**Problem:** Worktree gets far behind main, causing conflicts
|
||||
|
||||
**Solution:**
|
||||
- Set reminder to sync daily
|
||||
- Use script: `scripts/sync_worktree.sh`
|
||||
- Keep feature branches short-lived
|
||||
|
||||
---
|
||||
|
||||
### Pitfall 3: Abandoning Worktrees
|
||||
|
||||
**Problem:** Old worktrees with uncommitted work left behind
|
||||
|
||||
**Solution:**
|
||||
- Weekly cleanup ritual
|
||||
- Use `scripts/list_worktrees.sh` to audit
|
||||
- Document important worktrees
|
||||
- Set calendar reminder
|
||||
|
||||
---
|
||||
|
||||
### Pitfall 4: Wrong Branch Checked Out
|
||||
|
||||
**Problem:** Same branch in multiple worktrees (git won't allow)
|
||||
|
||||
**Solution:**
|
||||
- Each worktree needs unique branch
|
||||
- Use branch naming to avoid confusion
|
||||
- Check before creating: `git branch`
|
||||
|
||||
---
|
||||
|
||||
### Pitfall 5: Disk Space Issues
|
||||
|
||||
**Problem:** Running out of disk space with many worktrees
|
||||
|
||||
**Solution:**
|
||||
- Use sparse checkout
|
||||
- Clean build artifacts regularly
|
||||
- Limit concurrent worktrees
|
||||
- Monitor with `du -sh ../myapp-*`
|
||||
|
||||
---
|
||||
|
||||
## Checklists
|
||||
|
||||
### Before Creating Worktree
|
||||
|
||||
- [ ] Is the task substantial enough?
|
||||
- [ ] Do I have a clear branch name?
|
||||
- [ ] Do I have sufficient disk space?
|
||||
- [ ] Is this better than just using `git checkout`?
|
||||
|
||||
---
|
||||
|
||||
### After Creating Worktree
|
||||
|
||||
- [ ] Opened in editor/IDE
|
||||
- [ ] Ran `/init` in Claude Code
|
||||
- [ ] Noted purpose/task
|
||||
- [ ] Set up environment (npm install, etc.)
|
||||
|
||||
---
|
||||
|
||||
### Before Removing Worktree
|
||||
|
||||
- [ ] Checked for uncommitted changes
|
||||
- [ ] Verified branch is merged (or don't need it)
|
||||
- [ ] Pushed any important commits
|
||||
- [ ] Informed team if collaborative work
|
||||
|
||||
---
|
||||
|
||||
### Weekly Maintenance
|
||||
|
||||
- [ ] Run `scripts/list_worktrees.sh`
|
||||
- [ ] Run `scripts/cleanup_worktrees.sh`
|
||||
- [ ] Check disk usage
|
||||
- [ ] Update documentation
|
||||
|
||||
---
|
||||
|
||||
## Summary of Best Practices
|
||||
|
||||
**Do:**
|
||||
- ✅ Use descriptive branch/directory names
|
||||
- ✅ Create worktrees as siblings to main repo
|
||||
- ✅ Run `/init` when opening Claude in new worktree
|
||||
- ✅ Clean up regularly (weekly)
|
||||
- ✅ Limit to 3-5 concurrent worktrees
|
||||
- ✅ Sync with main frequently
|
||||
- ✅ Use provided scripts for common tasks
|
||||
|
||||
**Don't:**
|
||||
- ❌ Nest worktrees inside repository
|
||||
- ❌ Create worktrees for quick tasks
|
||||
- ❌ Forget to run `/init` in Claude
|
||||
- ❌ Let worktrees accumulate indefinitely
|
||||
- ❌ Use generic names (test, temp, wt1)
|
||||
- ❌ Share worktree directories across machines
|
||||
|
||||
---
|
||||
|
||||
**Key Principle:**
|
||||
> Worktrees are a power tool. Use them intentionally for parallel development, not as a replacement for basic branching.
|
||||
519
skills/git-worktrees/references/slash_command_template.md
Normal file
519
skills/git-worktrees/references/slash_command_template.md
Normal file
@@ -0,0 +1,519 @@
|
||||
# Custom /worktree Slash Command Template
|
||||
|
||||
Create a custom `/worktree` command for Claude Code to streamline worktree creation.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This template allows you to create a slash command that:
|
||||
1. Creates a new Git worktree
|
||||
2. Provides setup instructions
|
||||
3. Offers to continue the conversation in the new worktree
|
||||
|
||||
**Usage after setup:**
|
||||
```
|
||||
/worktree feature-new-api
|
||||
```
|
||||
|
||||
Claude will create the worktree and guide you through the next steps.
|
||||
|
||||
---
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### Step 1: Create Command File
|
||||
|
||||
Create a new file in your Claude Code commands directory:
|
||||
|
||||
```bash
|
||||
# For project-specific command
|
||||
mkdir -p .claude/commands
|
||||
touch .claude/commands/worktree.md
|
||||
|
||||
# For global command (all projects)
|
||||
mkdir -p ~/.claude/commands
|
||||
touch ~/.claude/commands/worktree.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Add Command Content
|
||||
|
||||
Copy this template into `worktree.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Create a new Git worktree for parallel development with Claude Code
|
||||
---
|
||||
|
||||
# Create Git Worktree
|
||||
|
||||
{{#if (not args.0)}}
|
||||
**Usage:** `/worktree <branch-name> [base-branch]`
|
||||
|
||||
**Examples:**
|
||||
- `/worktree feature-api` - Create worktree from main
|
||||
- `/worktree feature-ui develop` - Create worktree from develop
|
||||
- `/worktree hotfix-urgent` - Create hotfix worktree
|
||||
|
||||
**What this does:**
|
||||
1. Creates a new Git worktree
|
||||
2. Sets up the directory structure
|
||||
3. Provides setup instructions
|
||||
|
||||
{{else}}
|
||||
|
||||
## Creating Worktree: {{args.0}}
|
||||
|
||||
Let me create a new Git worktree for parallel development.
|
||||
|
||||
**Branch name:** `{{args.0}}`
|
||||
{{#if args.1}}
|
||||
**Base branch:** `{{args.1}}`
|
||||
{{else}}
|
||||
**Base branch:** `main` (default)
|
||||
{{/if}}
|
||||
|
||||
### Step 1: Create the Worktree
|
||||
|
||||
Run this command in your terminal:
|
||||
|
||||
\`\`\`bash
|
||||
scripts/create_worktree.sh
|
||||
\`\`\`
|
||||
|
||||
When prompted:
|
||||
- Feature name: **{{args.0}}**
|
||||
{{#if args.1}}
|
||||
- Base branch: **{{args.1}}**
|
||||
{{else}}
|
||||
- Base branch: **main** (or press Enter for default)
|
||||
{{/if}}
|
||||
|
||||
The script will create the worktree in a sibling directory.
|
||||
|
||||
### Step 2: Open in New Claude Code Session
|
||||
|
||||
After the script completes:
|
||||
|
||||
1. Note the worktree path (shown by the script)
|
||||
2. Open a new Claude Code window
|
||||
3. Navigate to the worktree directory
|
||||
4. **Important:** Run `/init` to orient Claude
|
||||
|
||||
### Step 3: Start Development
|
||||
|
||||
Once in the new worktree with Claude initialized, I can help you:
|
||||
- Implement the feature
|
||||
- Write tests
|
||||
- Create documentation
|
||||
- Review code
|
||||
|
||||
### Alternative: Manual Creation
|
||||
|
||||
If you prefer manual setup:
|
||||
|
||||
\`\`\`bash
|
||||
# Get repository root
|
||||
REPO_ROOT=$(git rev-parse --show-toplevel)
|
||||
REPO_NAME=$(basename "$REPO_ROOT")
|
||||
|
||||
# Create worktree
|
||||
{{#if args.1}}
|
||||
git worktree add ../$REPO_NAME-{{args.0}} -b {{args.0}} {{args.1}}
|
||||
{{else}}
|
||||
git worktree add ../$REPO_NAME-{{args.0}} -b {{args.0}} main
|
||||
{{/if}}
|
||||
|
||||
# Open in editor
|
||||
cd ../$REPO_NAME-{{args.0}}
|
||||
code .
|
||||
\`\`\`
|
||||
|
||||
### Managing Worktrees
|
||||
|
||||
**List all worktrees:**
|
||||
\`\`\`bash
|
||||
scripts/list_worktrees.sh
|
||||
\`\`\`
|
||||
|
||||
**Sync with main:**
|
||||
\`\`\`bash
|
||||
scripts/sync_worktree.sh
|
||||
\`\`\`
|
||||
|
||||
**Clean up when done:**
|
||||
\`\`\`bash
|
||||
scripts/cleanup_worktrees.sh
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
**Would you like me to help with anything else before you switch to the new worktree?**
|
||||
|
||||
{{/if}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Test the Command
|
||||
|
||||
```bash
|
||||
# In Claude Code, type:
|
||||
/worktree feature-new-api
|
||||
|
||||
# Or with custom base branch:
|
||||
/worktree feature-ui develop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Template (With Automatic Creation)
|
||||
|
||||
For users who want Claude to automatically create the worktree (not just show instructions):
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Create and set up a new Git worktree for parallel development
|
||||
---
|
||||
|
||||
# Create Git Worktree: {{args.0}}
|
||||
|
||||
{{#if (not args.0)}}
|
||||
**Error:** Branch name required
|
||||
|
||||
**Usage:** `/worktree <branch-name> [base-branch]`
|
||||
|
||||
**Examples:**
|
||||
- `/worktree feature-api`
|
||||
- `/worktree feature-ui develop`
|
||||
{{else}}
|
||||
|
||||
I'll create a new Git worktree for `{{args.0}}`.
|
||||
|
||||
## Creating Worktree
|
||||
|
||||
\`\`\`bash
|
||||
#!/bin/bash
|
||||
|
||||
# Configuration
|
||||
BRANCH_NAME="{{args.0}}"
|
||||
{{#if args.1}}
|
||||
BASE_BRANCH="{{args.1}}"
|
||||
{{else}}
|
||||
BASE_BRANCH="main"
|
||||
{{/if}}
|
||||
|
||||
# Get repository info
|
||||
REPO_ROOT=$(git rev-parse --show-toplevel)
|
||||
REPO_NAME=$(basename "$REPO_ROOT")
|
||||
WORKTREE_DIR="$(dirname "$REPO_ROOT")/${REPO_NAME}-${BRANCH_NAME}"
|
||||
|
||||
# Validate
|
||||
if [ ! -d "$REPO_ROOT/.git" ]; then
|
||||
echo "Error: Not in a git repository"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check if branch exists
|
||||
if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
|
||||
echo "⚠ Branch $BRANCH_NAME already exists"
|
||||
echo "Using existing branch..."
|
||||
git worktree add "$WORKTREE_DIR" "$BRANCH_NAME"
|
||||
else
|
||||
echo "✓ Creating new branch from $BASE_BRANCH..."
|
||||
git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" "$BASE_BRANCH"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✓ Worktree created successfully!"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo "1. Open new Claude Code window"
|
||||
echo "2. Navigate to: $WORKTREE_DIR"
|
||||
echo "3. Run: /init"
|
||||
echo "4. Start development!"
|
||||
\`\`\`
|
||||
|
||||
Run the script above to create the worktree.
|
||||
|
||||
## What's Next?
|
||||
|
||||
After creating the worktree:
|
||||
|
||||
1. **Open in new window:** \`code {{WORKTREE_PATH}}\`
|
||||
2. **Run /init:** To orient Claude in the new environment
|
||||
3. **Start coding:** I'll be ready to help with {{args.0}}!
|
||||
|
||||
## Useful Commands
|
||||
|
||||
**View all worktrees:**
|
||||
\`\`\`bash
|
||||
git worktree list
|
||||
\`\`\`
|
||||
|
||||
**When done, merge back:**
|
||||
\`\`\`bash
|
||||
git checkout main
|
||||
git merge {{args.0}}
|
||||
\`\`\`
|
||||
|
||||
**Remove worktree:**
|
||||
\`\`\`bash
|
||||
git worktree remove ../{{REPO_NAME}}-{{args.0}}
|
||||
git branch -d {{args.0}}
|
||||
\`\`\`
|
||||
|
||||
{{/if}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Simple Feature
|
||||
|
||||
```
|
||||
User: /worktree feature-authentication
|
||||
```
|
||||
|
||||
**Claude's response:**
|
||||
- Shows worktree creation instructions
|
||||
- Explains next steps
|
||||
- Offers to continue in new worktree
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Custom Base Branch
|
||||
|
||||
```
|
||||
User: /worktree feature-dashboard develop
|
||||
```
|
||||
|
||||
**Claude's response:**
|
||||
- Creates worktree from `develop` instead of `main`
|
||||
- Adjusts instructions accordingly
|
||||
|
||||
---
|
||||
|
||||
### Example 3: List Current Worktrees
|
||||
|
||||
```
|
||||
User: /worktree
|
||||
```
|
||||
|
||||
**Claude's response:**
|
||||
- Shows usage instructions
|
||||
- Lists example commands
|
||||
- Explains what the command does
|
||||
|
||||
---
|
||||
|
||||
## Customization Options
|
||||
|
||||
### Add Project-Specific Logic
|
||||
|
||||
Modify the template to include project-specific setup:
|
||||
|
||||
```markdown
|
||||
### Step 4: Project Setup
|
||||
|
||||
After creating the worktree, run:
|
||||
|
||||
\`\`\`bash
|
||||
cd {{WORKTREE_PATH}}
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Run database migrations
|
||||
npm run migrate
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add Team Conventions
|
||||
|
||||
Include your team's specific workflow:
|
||||
|
||||
```markdown
|
||||
### Team Workflow
|
||||
|
||||
1. Create worktree with `/worktree <feature-name>`
|
||||
2. Update Jira ticket status to "In Progress"
|
||||
3. Create draft PR: `gh pr create --draft`
|
||||
4. Develop feature
|
||||
5. Request review when ready
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add Validation
|
||||
|
||||
Enforce naming conventions:
|
||||
|
||||
```markdown
|
||||
{{#if (not (match args.0 "^(feature|hotfix|refactor|experiment)-"))}}
|
||||
**Error:** Branch name must start with feature-, hotfix-, refactor-, or experiment-
|
||||
|
||||
**Valid examples:**
|
||||
- feature-user-auth
|
||||
- hotfix-login-bug
|
||||
- refactor-api-layer
|
||||
- experiment-new-db
|
||||
{{/if}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
**Problem:** `/worktree` command doesn't appear
|
||||
|
||||
**Solution:**
|
||||
1. Check file location: `.claude/commands/worktree.md`
|
||||
2. Restart Claude Code
|
||||
3. Verify file has correct frontmatter (YAML header with `description`)
|
||||
|
||||
---
|
||||
|
||||
### Script Path Issues
|
||||
|
||||
**Problem:** Scripts not found
|
||||
|
||||
**Solution:**
|
||||
- Use absolute paths: `<skill-path>/scripts/create_worktree.sh`
|
||||
- Or add scripts to PATH
|
||||
- Or check scripts are in correct location
|
||||
|
||||
---
|
||||
|
||||
### Template Variables Not Working
|
||||
|
||||
**Problem:** `{{args.0}}` showing as literal text
|
||||
|
||||
**Solution:**
|
||||
- Ensure proper template syntax
|
||||
- Check Claude Code version (templates require recent version)
|
||||
- Verify YAML frontmatter is correct
|
||||
|
||||
---
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a fully working example you can copy directly:
|
||||
|
||||
**File:** `.claude/commands/worktree.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Create a Git worktree for parallel Claude Code development
|
||||
---
|
||||
|
||||
# Git Worktree Manager
|
||||
|
||||
{{#if args.0}}
|
||||
|
||||
## Creating Worktree: {{args.0}}
|
||||
|
||||
I'll help you set up a new Git worktree for parallel development.
|
||||
|
||||
### Quick Setup
|
||||
|
||||
Run this command:
|
||||
|
||||
\`\`\`bash
|
||||
scripts/create_worktree.sh
|
||||
\`\`\`
|
||||
|
||||
When prompted, enter: **{{args.0}}**
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. ✓ Script will create the worktree
|
||||
2. Open new Claude Code window
|
||||
3. Navigate to the new worktree directory
|
||||
4. Run \`/init\` to orient me
|
||||
5. Start development on {{args.0}}!
|
||||
|
||||
### Manual Alternative
|
||||
|
||||
\`\`\`bash
|
||||
# Create worktree
|
||||
git worktree add ../$(basename $(git rev-parse --show-toplevel))-{{args.0}} -b {{args.0}}
|
||||
|
||||
# Open it
|
||||
cd ../$(basename $(git rev-parse --show-toplevel))-{{args.0}}
|
||||
code .
|
||||
\`\`\`
|
||||
|
||||
**Ready to switch?** See you in the new worktree!
|
||||
|
||||
{{else}}
|
||||
|
||||
## Git Worktree Command
|
||||
|
||||
Create a new worktree for parallel development.
|
||||
|
||||
**Usage:**
|
||||
\`\`\`
|
||||
/worktree <branch-name>
|
||||
\`\`\`
|
||||
|
||||
**Examples:**
|
||||
\`\`\`
|
||||
/worktree feature-api
|
||||
/worktree refactor-auth
|
||||
/worktree hotfix-urgent
|
||||
\`\`\`
|
||||
|
||||
**What it does:**
|
||||
- Creates a new Git worktree in a sibling directory
|
||||
- Sets up the branch
|
||||
- Provides setup instructions
|
||||
|
||||
**Manage worktrees:**
|
||||
- List all: \`scripts/list_worktrees.sh\`
|
||||
- Sync with main: \`scripts/sync_worktree.sh\`
|
||||
- Clean up: \`scripts/cleanup_worktrees.sh\`
|
||||
|
||||
{{/if}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Custom Command
|
||||
|
||||
**Faster workflow:**
|
||||
- Type `/worktree feature-name` instead of manual commands
|
||||
- Consistent setup every time
|
||||
- Team standardization
|
||||
|
||||
**Better documentation:**
|
||||
- Built-in help
|
||||
- Examples always available
|
||||
- Team-specific instructions
|
||||
|
||||
**Claude integration:**
|
||||
- Seamless handoff to new worktree
|
||||
- Context preservation
|
||||
- Guided workflow
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
1. Create `worktree.md` in `.claude/commands/`
|
||||
2. Copy template
|
||||
3. Customize for your team
|
||||
4. Use `/worktree <branch-name>` in Claude Code
|
||||
5. Enjoy streamlined parallel development!
|
||||
|
||||
**Next level:** Share the command template with your team for consistent workflows.
|
||||
513
skills/git-worktrees/references/worktree_commands.md
Normal file
513
skills/git-worktrees/references/worktree_commands.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# Git Worktree Command Reference
|
||||
|
||||
Complete reference for `git worktree` commands.
|
||||
|
||||
---
|
||||
|
||||
## Basic Commands
|
||||
|
||||
### Create a New Worktree
|
||||
|
||||
```bash
|
||||
# Create worktree with new branch
|
||||
git worktree add <path> -b <new-branch>
|
||||
|
||||
# Create worktree from existing branch
|
||||
git worktree add <path> <existing-branch>
|
||||
|
||||
# Create worktree from specific commit
|
||||
git worktree add <path> <commit-hash>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# New feature branch
|
||||
git worktree add ../myapp-feature-api -b feature-api
|
||||
|
||||
# Use existing branch
|
||||
git worktree add ../myapp-hotfix hotfix-login
|
||||
|
||||
# From specific commit
|
||||
git worktree add ../myapp-review abc123def
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### List All Worktrees
|
||||
|
||||
```bash
|
||||
# Simple list
|
||||
git worktree list
|
||||
|
||||
# Porcelain format (machine-readable)
|
||||
git worktree list --porcelain
|
||||
|
||||
# With verbose output
|
||||
git worktree list -v
|
||||
```
|
||||
|
||||
**Output format:**
|
||||
```
|
||||
/home/user/myapp abc123 [main]
|
||||
/home/user/myapp-feature-api def456 [feature-api]
|
||||
/home/user/myapp-hotfix 789ghi [hotfix-login]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Remove a Worktree
|
||||
|
||||
```bash
|
||||
# Remove worktree (must be clean)
|
||||
git worktree remove <path>
|
||||
|
||||
# Force remove (even with uncommitted changes)
|
||||
git worktree remove <path> --force
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Clean removal
|
||||
git worktree remove ../myapp-feature-api
|
||||
|
||||
# Force removal
|
||||
git worktree remove ../myapp-feature-api --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Move a Worktree
|
||||
|
||||
```bash
|
||||
# Move worktree to new location
|
||||
git worktree move <old-path> <new-path>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
git worktree move ../myapp-feature-api ~/projects/myapp-feature-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Prune Stale References
|
||||
|
||||
```bash
|
||||
# Clean up references to removed worktrees
|
||||
git worktree prune
|
||||
|
||||
# Dry run (show what would be pruned)
|
||||
git worktree prune --dry-run
|
||||
|
||||
# Verbose output
|
||||
git worktree prune --verbose
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Lock/Unlock Worktrees
|
||||
|
||||
Prevent a worktree from being automatically pruned or removed.
|
||||
|
||||
```bash
|
||||
# Lock a worktree
|
||||
git worktree lock <path>
|
||||
|
||||
# Lock with reason
|
||||
git worktree lock <path> --reason "Long-running task"
|
||||
|
||||
# Unlock a worktree
|
||||
git worktree unlock <path>
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Worktrees on removable drives
|
||||
- Network-mounted worktrees
|
||||
- Long-running background tasks
|
||||
|
||||
---
|
||||
|
||||
### Create Detached HEAD Worktrees
|
||||
|
||||
Useful for reviewing specific commits without creating a branch.
|
||||
|
||||
```bash
|
||||
# Checkout specific commit
|
||||
git worktree add <path> --detach <commit>
|
||||
|
||||
# Short form
|
||||
git worktree add <path> --detach HEAD~5
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Review a specific commit
|
||||
git worktree add ../review-commit --detach abc123def
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Sparse Checkout in Worktrees
|
||||
|
||||
Only check out specific files/directories in a worktree (useful for large repos).
|
||||
|
||||
```bash
|
||||
# Create worktree with sparse-checkout
|
||||
git worktree add <path> <branch>
|
||||
cd <path>
|
||||
git sparse-checkout init
|
||||
git sparse-checkout set <directory1> <directory2>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Only checkout src/ and tests/
|
||||
git worktree add ../myapp-feature-api feature-api
|
||||
cd ../myapp-feature-api
|
||||
git sparse-checkout init
|
||||
git sparse-checkout set src/ tests/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Repair Commands
|
||||
|
||||
### Repair Worktree
|
||||
|
||||
If worktree becomes corrupted or administrative files are damaged.
|
||||
|
||||
```bash
|
||||
# Repair a worktree
|
||||
git worktree repair
|
||||
|
||||
# Repair specific worktree
|
||||
git worktree repair <path>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Set Worktree Defaults
|
||||
|
||||
```bash
|
||||
# Default path for worktrees (relative to repo)
|
||||
git config worktree.guessRemote true
|
||||
|
||||
# Automatically set up remote tracking
|
||||
git config push.default current
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: Parallel Feature Development
|
||||
|
||||
```bash
|
||||
# 1. Create worktree for feature A
|
||||
git worktree add ../repo-feature-a -b feature-a
|
||||
|
||||
# 2. Create worktree for feature B
|
||||
git worktree add ../repo-feature-b -b feature-b
|
||||
|
||||
# 3. Work on both simultaneously
|
||||
# (open each in separate editor/Claude session)
|
||||
|
||||
# 4. When done, merge both
|
||||
git checkout main
|
||||
git merge feature-a
|
||||
git merge feature-b
|
||||
|
||||
# 5. Clean up
|
||||
git worktree remove ../repo-feature-a
|
||||
git worktree remove ../repo-feature-b
|
||||
git branch -d feature-a feature-b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Workflow 2: Hotfix During Feature Development
|
||||
|
||||
```bash
|
||||
# You're working in a feature worktree
|
||||
cd ../repo-feature-xyz
|
||||
|
||||
# Need to create hotfix
|
||||
cd <main-repo>
|
||||
git worktree add ../repo-hotfix -b hotfix-urgent
|
||||
|
||||
# Fix the bug
|
||||
cd ../repo-hotfix
|
||||
# ... make fixes ...
|
||||
git add .
|
||||
git commit -m "Fix urgent bug"
|
||||
|
||||
# Merge hotfix
|
||||
git checkout main
|
||||
git merge hotfix-urgent
|
||||
git push
|
||||
|
||||
# Continue feature work
|
||||
cd ../repo-feature-xyz
|
||||
# ... continue ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Workflow 3: Code Review Without Switching
|
||||
|
||||
```bash
|
||||
# Create worktree for review
|
||||
git worktree add ../repo-review pr-branch-name
|
||||
|
||||
# Review in separate window
|
||||
cd ../repo-review
|
||||
# ... review code ...
|
||||
|
||||
# Clean up after review
|
||||
cd <main-repo>
|
||||
git worktree remove ../repo-review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Commands
|
||||
|
||||
### Check Worktree Status
|
||||
|
||||
```bash
|
||||
# List all worktrees with details
|
||||
git worktree list -v
|
||||
|
||||
# Check if directory is a worktree
|
||||
cd <directory>
|
||||
git rev-parse --git-dir
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Find Orphaned Worktrees
|
||||
|
||||
```bash
|
||||
# List worktrees that no longer exist
|
||||
git worktree list --porcelain | grep "^worktree" | awk '{print $2}' | while read dir; do
|
||||
if [ ! -d "$dir" ]; then
|
||||
echo "Orphaned: $dir"
|
||||
fi
|
||||
done
|
||||
|
||||
# Clean them up
|
||||
git worktree prune
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Reset Worktree to Clean State
|
||||
|
||||
```bash
|
||||
# Discard all changes
|
||||
cd <worktree>
|
||||
git reset --hard HEAD
|
||||
git clean -fd
|
||||
|
||||
# Reset to specific branch state
|
||||
git fetch origin
|
||||
git reset --hard origin/<branch>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Git Commands
|
||||
|
||||
### Fetch/Pull in Worktrees
|
||||
|
||||
```bash
|
||||
# Fetch applies to all worktrees (shared .git)
|
||||
git fetch origin
|
||||
|
||||
# Pull in specific worktree
|
||||
cd <worktree>
|
||||
git pull origin <branch>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stash in Worktrees
|
||||
|
||||
```bash
|
||||
# Stash is per-worktree
|
||||
cd <worktree>
|
||||
git stash push -m "My stash"
|
||||
|
||||
# List stashes (shared across worktrees)
|
||||
git stash list
|
||||
|
||||
# Apply stash in different worktree
|
||||
cd <other-worktree>
|
||||
git stash apply stash@{0}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Rebase in Worktrees
|
||||
|
||||
```bash
|
||||
# Each worktree can have independent rebase operations
|
||||
cd <worktree>
|
||||
git rebase main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Limit Number of Worktrees
|
||||
|
||||
- **Recommended:** 3-5 active worktrees
|
||||
- **Maximum:** Depends on disk space and RAM
|
||||
- **Why:** Each worktree duplicates working files
|
||||
|
||||
### Use Sparse Checkout
|
||||
|
||||
For large repositories:
|
||||
|
||||
```bash
|
||||
git sparse-checkout set <dir1> <dir2>
|
||||
```
|
||||
|
||||
Reduces disk usage by only checking out necessary files.
|
||||
|
||||
---
|
||||
|
||||
### Share Object Database
|
||||
|
||||
Worktrees automatically share:
|
||||
- `.git/objects/` (commits, trees, blobs)
|
||||
- `.git/refs/` (branches, tags)
|
||||
- `.git/config` (configuration)
|
||||
|
||||
**No duplication of:**
|
||||
- Git history
|
||||
- Commit objects
|
||||
- Branch information
|
||||
|
||||
**Duplicated:**
|
||||
- Working directory files
|
||||
- Index (staging area)
|
||||
- Worktree-specific config
|
||||
|
||||
---
|
||||
|
||||
## Safety and Best Practices
|
||||
|
||||
### Before Removing Worktrees
|
||||
|
||||
```bash
|
||||
# Check for uncommitted changes
|
||||
cd <worktree>
|
||||
git status
|
||||
|
||||
# Check if branch is merged
|
||||
git branch --merged main | grep <branch-name>
|
||||
|
||||
# Backup if needed
|
||||
git stash push -m "Backup before removal"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handling Merge Conflicts
|
||||
|
||||
```bash
|
||||
# During merge in worktree
|
||||
cd <worktree>
|
||||
git merge main
|
||||
|
||||
# If conflicts occur
|
||||
git status # See conflicting files
|
||||
# Edit files to resolve
|
||||
git add <resolved-files>
|
||||
git commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Table
|
||||
|
||||
| Command | Purpose | Example |
|
||||
|---------|---------|---------|
|
||||
| `git worktree add <path> -b <branch>` | Create with new branch | `git worktree add ../wt -b feat` |
|
||||
| `git worktree add <path> <branch>` | Create from existing | `git worktree add ../wt main` |
|
||||
| `git worktree list` | Show all worktrees | - |
|
||||
| `git worktree remove <path>` | Remove worktree | `git worktree remove ../wt` |
|
||||
| `git worktree remove <path> --force` | Force remove | `git worktree remove ../wt -f` |
|
||||
| `git worktree prune` | Clean stale refs | - |
|
||||
| `git worktree move <old> <new>` | Move worktree | `git worktree move ../wt ~/wt` |
|
||||
| `git worktree lock <path>` | Prevent pruning | `git worktree lock ../wt` |
|
||||
| `git worktree unlock <path>` | Allow pruning | `git worktree unlock ../wt` |
|
||||
| `git worktree repair` | Fix corrupted worktree | - |
|
||||
|
||||
---
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "fatal: '<path>' already exists"
|
||||
|
||||
**Cause:** Directory exists
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
rm -rf <path>
|
||||
# or use a different path
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "fatal: invalid reference: <branch>"
|
||||
|
||||
**Cause:** Branch name has invalid characters
|
||||
|
||||
**Solution:** Use only alphanumeric and hyphens:
|
||||
```bash
|
||||
# Bad: feature/my_feature
|
||||
# Good: feature-my-feature
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "fatal: '<path>' is not a working tree"
|
||||
|
||||
**Cause:** Trying to operate on non-worktree directory
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
git worktree list # Find correct path
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "fatal: '<branch>' is already checked out"
|
||||
|
||||
**Cause:** Branch in use by another worktree
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use a different branch name
|
||||
git worktree add ../wt -b new-branch-name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
**Official Documentation:**
|
||||
- https://git-scm.com/docs/git-worktree
|
||||
|
||||
**Pro Git Book:**
|
||||
- Chapter on worktrees: https://git-scm.com/book/en/v2
|
||||
|
||||
**Git Worktree Tutorial:**
|
||||
- https://git-scm.com/docs/git-worktree#_examples
|
||||
Reference in New Issue
Block a user