How to fix fatal: HEAD is broken in Git

Run Git's filesystem check to identify any corrupted objects or broken references:

git fsck --full

This will report any dangling commits, broken links, or corrupted objects. Look for messages starting with "error:" or "fatal:". If fsck completes without errors, the corruption may be in the index or worktree configuration rather than the object database.

Stale index files are a common cause, especially in older Git versions. Refresh it manually:

git update-index --refresh

Then try your git describe command again. This forces Git to re-scan the working directory and update its internal state cache.

If you're using submodules, verify their integrity:

git submodule status
git submodule update --init --recursive

Broken submodules are one of the primary reasons git describe --broken was introduced. If submodules show errors, reinitialize them or repair their .git references.

If using linked worktrees and the main repository has moved, repair the connections:

git worktree repair

This reestablishes links between the main worktree and any linked worktrees that may have become disconnected.

Files marked with --assume-unchanged can interfere with state detection. List and clear them:

# List files with assume-unchanged flag
git ls-files -v | grep "^h"

# Clear the flag for specific files
git update-index --no-assume-unchanged path/to/file

Repeat for all affected files, then retry git describe.

If fsck revealed corrupted objects, attempt recovery:

# Create backup first
cp -r .git .git.backup

# Try automatic repair
git reflog expire --expire=now --all
git gc --prune=now --aggressive

For more severe corruption, you may need to clone fresh from a remote and reapply local changes. Always backup before attempting deep repairs.