recovering-from-bad-git-state

Techniques for diagnosing and recovering from corrupted git state, orphaned worktrees, and inconsistent branch references.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill serves as a Git State Recovery Specialist, providing advanced diagnostic and repair techniques for corrupted Git repositories. It enables developers to resolve complex version control issues such as orphaned worktrees, inconsistent branch references, and detached HEAD states, ensuring a stable development environment and preventing workflow disruptions.

Use Cases

  • Fixing 'already used by worktree' errors when a worktree directory was manually deleted without using git commands.
  • Recovering from corrupted HEAD references where Git fails to recognize the current branch or points to non-existent revisions.
  • Pruning stale or orphaned worktree metadata to clean up repository state and restore normal operations.
  • Resolving branch lock conflicts and phantom worktree claims that prevent branch deletion or switching.
  • Implementing automated repository state validation hooks within custom developer tools or CI/CD pipelines to prevent state corruption.
namerecovering-from-bad-git-state
descriptionTechniques for diagnosing and recovering from corrupted git state, orphaned worktrees, and inconsistent branch references.

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
  • ecosystem-patterns: Composable git operations section
  • mise-task-managing: Git workflow automation patterns