recovering-from-bad-git-state（从错误的 git 状态中恢复）

Git State Recovery Specialist

Use this skill when encountering corrupted git state, orphaned worktrees, or inconsistent branch references that prevent normal git operations.

When to Use

Invoke proactively when you observe:

• git worktree list showing 00000000 commit hashes
• git branch --show-current contradicting actual HEAD state
• Worktree operations failing with "already used by worktree" errors
• HEAD pointing to non-existent branch refs
• Branch deletion failing due to phantom worktree claims
• git status showing "HEAD detached" unexpectedly

Core Diagnostic Sequence

1. State Validation

# Check HEAD integrity
cat .git/HEAD
# Should show: ref: refs/heads/<branch-name>

# Verify worktree consistency
git worktree list
# Look for: invalid commit hashes (00000000), missing paths

# Cross-check branch state
git branch --show-current
git symbolic-ref HEAD
# These should agree

2. Identify Corruption Type

Type A: Corrupted HEAD Reference

• Symptoms: HEAD points to non-existent branch, operations fail with "unknown revision"
• Cause: Incomplete checkout or branch deletion while HEAD pointed to it
• Recovery: Force reset HEAD to known good branch

Type B: Orphaned Worktree Metadata

• Symptoms: git worktree list shows worktree but directory doesn't exist
• Cause: Manual directory deletion without git worktree remove
• Recovery: Prune stale worktree references

Type C: Branch Lock Conflict

• Symptoms: "branch is already used by worktree" but git worktree list shows different branch
• Cause: Worktree checked out branch, then had HEAD forcibly changed
• Recovery: Align HEAD with actual branch or force checkout

Recovery Operations

Fix Corrupted HEAD

# Identify correct branch from remote
git branch -r | grep main  # or master, develop, etc.

# Force reset HEAD (bypasses git safety checks)
echo "ref: refs/heads/main" > .git/HEAD

# Verify fix
git status
git branch --show-current

Prune Orphaned Worktrees

# Standard prune (removes references to deleted directories)
git worktree prune -v

# If prune fails, manual cleanup
rm -rf .git/worktrees/<worktree-name>

# Verify cleanup
git worktree list

Resolve Branch Lock Conflicts

# Option 1: Align HEAD with intended branch
git reset --hard origin/main

# Option 2: Force delete phantom worktree claim
# First ensure you're on a different branch
git checkout main
# Then force delete the locked branch
git branch -D <locked-branch>
git push origin --delete <locked-branch>  # if pushed

Nuclear Option: Rebuild Branch Refs

# When refs are completely corrupted
git fetch --all --prune

# Recreate local branch from remote
git branch -D <branch-name>
git checkout -b <branch-name> origin/<branch-name>

# Verify state
git log --oneline -5

Prevention Patterns

Safe Worktree Operations

# Always use git worktree commands, never manual directory operations
git worktree add <path> <branch>    # Create
git worktree remove <path>          # Delete (not rm -rf)
git worktree prune                  # Clean stale refs

Validate State Before Operations

// Example: iMi worktree manager
fn validate_repo_state(&self, repo: &Repository) -> Result<()> {
    let head = repo.head()?;

    // Ensure HEAD points to valid commit
    if head.target().is_none() {
        return Err(anyhow::anyhow!(
            "Repository HEAD is corrupted. Run git-state-recovery."
        ));
    }

    // Verify worktree list consistency
    let worktrees = repo.worktrees()?;
    for wt in worktrees.iter().flatten() {
        let wt_path = repo.workdir()
            .unwrap()
            .parent()
            .unwrap()
            .join(wt);
        if !wt_path.exists() {
            eprintln!("Warning: Orphaned worktree detected: {}", wt);
        }
    }

    Ok(())
}

Integration with iMi

When building worktree management tools, add state validation hooks:

// Before any worktree operation
pub async fn create_worktree(&self, ...) -> Result<PathBuf> {
    // Validate repository state first
    self.validate_repo_state(&repo)?;

    // Proceed with operation
    self.git.create_worktree(...)?;

    // Verify post-operation state
    self.validate_worktree_created(&worktree_path)?;

    Ok(worktree_path)
}

Common Edge Cases

Case 1: Trunk Directory Checked Out to PR Branch

Symptom: imi pr <num> switches trunk to PR branch instead of creating separate worktree

Root Cause: gh pr checkout checks out in current directory as side effect

Fix: Fetch PR without checkout

# Get PR head ref
PR_REF=$(gh pr view <num> --json headRefName -q .headRefName)

# Fetch without checkout
git fetch origin $PR_REF:pr-<num>

# Create worktree from fetched ref
git worktree add ../pr-<num> pr-<num>

Case 2: Multiple Repos with Same Worktree Name

Symptom: Creating pr-123 in repo B fails because repo A has pr-123

Root Cause: Git worktree names are globally unique per repository

Fix: Use repo-prefixed worktree names

let worktree_name = format!("{}-pr-{}", repo_name, pr_number);

Testing Recovery Procedures

Before deploying worktree automation:

# Create test scenario
git init test-repo && cd test-repo
git commit --allow-empty -m "init"
git worktree add ../test-wt

# Corrupt state
rm -rf ../test-wt
# Don't run git worktree prune yet

# Verify corruption detection
git worktree list  # Should show test-wt but invalid path

# Test recovery
git worktree prune -v
git worktree list  # Should be clean

Escalation Path

If recovery procedures fail:

1. Backup corrupted repository: tar -czf repo-backup.tar.gz.git/
2. Clone fresh from remote: git clone <url> repo-fresh
3. Manually recreate worktrees from backup database/records
4. Document failure mode for future prevention

Related Skills

• ecosystem-patterns: Composable git operations section
• mise-task-managing: Git workflow automation patterns