Appearance
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-nameThis 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 --strictWhat fsck reports
| Message | Meaning | Severity |
|---|---|---|
dangling blob <sha> | A blob not reachable from any branch/tag | Informational |
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 object | Object fails hash verification | Critical |
sha1 mismatch | Stored hash does not match computed hash | Critical |
Exit codes
bash
git fsck --strict
echo $?
# 0 = no errors, non-zero = corruption foundUse 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-onlyDetecting duplicate objects
bash
git fsck --duplicatesReports 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 HEADIn 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
fiUsing 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/*.idxOutput format
<sha1> <type> <size> <offset> <depth> <base-sha1>
abc1234 commit 234 0 1 def5678When a delta chain is corrupt, verify-pack reports:
error: Could not read <sha1>
error: packfile .git/objects/pack/pack-xxx.pack is corruptCross-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 --strictgit 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 *.mdgit 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 matchgit 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 existsCI 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 pushScheduled 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
doneWhen 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.gitfsck 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 canfsck 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 -adPerformance characteristics
| Command | Time complexity | When to use |
|---|---|---|
git fsck | O(objects) | After unusual filesystem events, before backups |
git fsck --connectivity-only | O(commits) | Fast daily check — skips blob content validation |
git verify-pack | O(packed-objects) | After pack operations, before archiving packs |
git verify-commit | O(1) per commit | CI 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