git fsck: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git fsck checks your repository for corruption and reports dangling or unreachable objects.

fsck is the integrity checker. It also surfaces dangling commits you might recover after a destructive operation.

What it does

git fsck (file-system check) verifies the connectivity and validity of objects in the database, reporting missing, corrupt, dangling, and unreachable objects.

Common usage

Terminal

git fsck
git fsck --full
git fsck --lost-found             # write dangling objects to disk
git fsck --unreachable

Options

Flag	What it does
--full	Check all object packs and alternates
--lost-found	Write dangling blobs/commits to .git/lost-found
--unreachable	Print objects not reachable from any ref
--no-dangling	Suppress dangling-object reports

Common errors in CI

error: object file … is empty or "fatal: loose object … is corrupt" indicates real repository corruption - usually a truncated write or disk issue on the runner. The reliable CI fix is a fresh clone; fsck plus dangling-object recovery is for local rescue, not pipelines.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git fsck: Usage, Options & Common CI Errors?