Skip to content

Object Integrity & Verification Plumbing ​

Git guarantees cryptographic integrity of every stored object. Every blob, tree, commit, and tag is content-addressed by its SHA-1 (or SHA-256 in SHA256 repos) hash. If the content changes, the hash changes. If the hash does not match the content, Git knows the object is corrupt.

This guide covers the verification plumbing commands that expose the integrity layer: git fsck, git verify-commit, git verify-tag, git verify-pack, and the git check-* family. These are the tools you run when a CI pipeline fails with a mysterious "fatal: bad object", when a clone reports checksum mismatches, or when you need to prove the repository has not been tampered with.

Integrity model ​

Git stores objects in .git/objects/ as [prefix-sha]/[rest-of-sha]. The object content is zlib-compressed and prepended with a header (blob <size>\0, tree <size>\0, etc.). The hash of the full (header + content) object is the object's name.

SHA-1(object-header + object-content) = object-name

This means:

  • Integrity is transitive. A commit hashes its tree. The tree hashes its blobs and subtrees. If any blob in the history changes, every commit that references it gets a new SHA.
  • No silent corruption. A single flipped bit in a packfile changes the decompressed content, which changes the computed hash, which Git detects on read.
  • Tampering is detectable. Replacing a file with a different one changes its blob hash, which changes the tree hash, which changes every commit hash in that ancestry. An attacker would need to recompute every SHA up to the root — infeasible for SHA-256 and collision-resistant even for SHA-1 in practice.

git fsck: File system check ​

git fsck scans every reachable object in the repository and validates its SHA-1 checksum, object type, and structural integrity.

Basic usage ​

bash
# Check all reachable objects
git fsck

# Check everything, including unreachable and dangling objects
git fsck --full

# Show only actual corruption (hide dangling and unreachable)
git fsck --full --strict

What fsck reports ​

MessageMeaningSeverity
dangling blob <sha>A blob not reachable from any branch/tagInformational
dangling commit <sha>A commit not in any branch (common after rebase)Informational
missing blob <sha>An object referenced but not in .git/objects/Critical
corrupt loose objectObject fails hash verificationCritical
sha1 mismatchStored hash does not match computed hashCritical

Exit codes ​

bash
git fsck --strict
echo $?
# 0 = no errors, non-zero = corruption found

Use this in CI to verify repo health before builds.

Checking specific object types ​

bash
# Only commits
git fsck --unreachable-commits

# Only reflog-reachable objects
git fsck --reflog

# Root trees (trees referenced by commits)
git fsck --root

# Connection to parent/child chains
git fsck --connectivity-only

Detecting duplicate objects ​

bash
git fsck --duplicates

Reports objects with the same content stored at different paths. Unusual but possible with alternates and reference clones.

git verify-commit and git verify-tag ​

These verify GPG signatures on commits and tags. They do not check object integrity (that is fsck's job) — they check authenticity.

bash
# Verify a signed commit
git verify-commit HEAD

# Verify a signed tag
git verify-tag v1.0.0

# Verify and show the signature details
git verify-commit --raw HEAD

In a CI pipeline ​

bash
# Reject unsigned commits in PRs
if ! git verify-commit HEAD 2>/dev/null; then
  echo "Commit is not signed or signature is invalid"
  exit 1
fi

Using with --require-signature ​

bash
git config --local commit.gpgSign true
git config --local tag.gpgSign true

# Reject unsigned pushes on the server side
# (receive.fsckObjects = true also helps)

git verify-pack: Packfile integrity ​

Packfiles are .pack files in .git/objects/pack/. They store multiple objects in a delta-compressed format. git verify-pack checks the pack's internal structure and validates every object.

bash
# Check all packfiles
git verify-pack .git/objects/pack/*.idx

# Verbose: show object list with types and sizes
git verify-pack -v .git/objects/pack/*.idx

# Show only errors
git verify-pack --stat-only .git/objects/pack/*.idx

Output format ​

<sha1> <type> <size> <offset> <depth> <base-sha1>
abc1234 commit 234 0 1 def5678

When a delta chain is corrupt, verify-pack reports:

error: Could not read <sha1>
error: packfile .git/objects/pack/pack-xxx.pack is corrupt

Cross-check with fsck ​

Run both for a complete picture:

bash
# Check pack structure
git verify-pack .git/objects/pack/*.idx

# Check that every object referenced in packs is reachable and valid
git fsck --full --strict

git check-attr, check-ignore, check-mailmap ​

These are not integrity checks per se, but they are the git check-* family that validates Git's own configuration against files.

git check-attr ​

Test how .gitattributes rules apply to a path:

bash
# Check what attributes apply to config.yaml
git check-attr --all config.yaml

# Check a specific attribute
git check-attr diff config.yaml

# Check multiple files
git check-attr --all -- config.yaml *.md

git check-ignore ​

Test whether a path would be ignored by .gitignore:

bash
# Check if a file is ignored
git check-ignore build/output.log
# Outputs the path if ignored, exits 1 if not

# Check multiple paths
git check-ignore -v build/output.log node_modules/package.json
# -v shows which .gitignore file caused the match

git check-mailmap ​

Test how a name/email would be translated by .mailmap:

bash
git check-mailmap "John Doe <john.doe@old-email.com>"
# Outputs the canonical mapping if one exists

CI integration patterns ​

Pre-build integrity check ​

bash
# Add to your CI pipeline before any build step
set -e
echo "=== Checking repository integrity ==="

# Quick check: are all referenced objects reachable?
git fsck --connectivity-only --no-dangling 2>&1 | grep -v "^notice:"

# Verify packfiles
if ls .git/objects/pack/*.idx 2>/dev/null; then
  git verify-pack --stat-only .git/objects/pack/*.idx
fi

echo "=== Integrity check passed ==="

Clone-time verification ​

bash
# Force Git to verify every object on fetch/clone
git -c transfer.fsckobjects=true clone https://example.com/repo.git
git -c fetch.fsckobjects=true fetch origin

# For server-side enforcement
git -c receive.fsckObjects=true push

Scheduled maintenance check ​

bash
#!/bin/bash
# Run from cron on CI runners with persistent repos

REPOS=("/var/lib/ci/repos/a" "/var/lib/ci/repos/b")

for repo in "${REPOS[@]}"; do
  cd "$repo"
  errors=$(git fsck --full --strict 2>&1 | grep -cE "corrupt|missing|error")
  if [ "$errors" -gt 0 ]; then
    echo "Corruption detected in $repo"
    # Alert, re-clone, or restore from backup
  fi
done

When things break ​

"fatal: bad object" during clone ​

bash
# Re-clone with verbosity to see where the corruption is
GIT_TRACE_PACKET=1 git clone https://example.com/repo.git

# Or try a shallow clone to isolate the bad pack
git clone --depth=1 https://example.com/repo.git

fsck reports "missing blob" ​

bash
# Check if the blob exists in a pack
git verify-pack .git/objects/pack/*.idx 2>&1 | grep <sha>

# Try a fresh fetch to get missing objects
git fetch origin --refetch  # Git 3.0+
# Or for older Git:
git fetch origin +refs/heads/*:refs/remotes/origin/*

# If still missing, the remote has the same corruption
# Restore from backup or use reflog+filter-repo to salvage what you can

fsck reports "corrupt loose object" ​

bash
# Find the object
git fsck --full 2>&1 | grep corrupt

# Delete the bad loose object and re-fetch
rm .git/objects/ab/cdef1234...
git fetch origin --refetch

# If the pack also has it, repack first to get it as loose
git repack -ad

Performance characteristics ​

CommandTime complexityWhen to use
git fsckO(objects)After unusual filesystem events, before backups
git fsck --connectivity-onlyO(commits)Fast daily check — skips blob content validation
git verify-packO(packed-objects)After pack operations, before archiving packs
git verify-commitO(1) per commitCI gate for signed commits

For a repo with 100k commits and 500k objects, git fsck --full --strict takes 30-90 seconds on modern hardware. git fsck --connectivity-only takes 2-5 seconds.

Quick reference ​

bash
# Full integrity scan
git fsck --full --strict

# Fast connectivity check
git fsck --connectivity-only --no-dangling

# Verify all packfiles
git verify-pack .git/objects/pack/*.idx

# Check a specific object's hash
git hash-object .git/objects/ab/cdef1234

# Verify a signed commit
git verify-commit HEAD

# Test gitignore rules
git check-ignore -v path/to/file

# Test gitattributes rules
git check-attr --all path/to/file

# Enable object verification on fetch/push
git -c transfer.fsckobjects=true fetch origin
git -c receive.fsckObjects=true push origin main

Git Master — Git Reference for Every Skill Level