Initial commit

2025-11-29 18:48:58 +08:00
commit df092d8cd2
127 changed files with 62057 additions and 0 deletions
--- a/skills/git-worktrees/references/worktree_commands.md
+++ b/skills/git-worktrees/references/worktree_commands.md
@@ -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