Git fsck checks the connectivity and validity of objects in a repository’s object database. It is useful when investigating missing objects, suspected storage corruption, or an unusual recovery state. A clean result, however, does not prove that the repository contains the release you intended to trust.
Integrity, reachability, and authenticity answer different questions. This guide keeps those questions separate and shows how to investigate findings without deleting the evidence that could explain or repair the problem.
Preserve the repository before changing it
If corruption or lost history is suspected, stop avoidable writes and preserve a copy of the relevant repository state using an approved backup procedure. Include the information needed to understand refs, reflogs, and any external object storage dependencies.
Do not immediately run aggressive pruning or cleanup because a diagnostic command mentions dangling objects. Objects that are no longer referenced by the current branch can still represent recoverable work.
Record the Git version, repository location, recent operations, and observed error. Keep private repository content and filenames within the incident’s authorized access boundary rather than attaching the whole repository to a public report.
Understand the objects under review
Git stores blobs, trees, commits, and tags, with references connecting history to named branches or other roots. Fsck examines whether the relevant object graph and objects satisfy its checks.
git fsck --fullThis is a diagnostic starting point, not a repair command. Current documented behavior includes full checking by default, but writing the option explicitly can make the intended review scope clear.
Capture output and exit status. A terminal line that looks alarming deserves interpretation in context; the absence of visible output also needs to be considered alongside command completion and the selected options.
Know which roots define reachability
When no explicit objects are supplied, the documented default considers the index, references, and reflogs as roots. Changing those inputs changes which objects are considered reachable.
A commit retained only by a reflog can be relevant to recovery even if it is not on a current branch. Using --no-reflogs changes that reachability view; it does not establish that the newly reported objects are worthless.
For an investigation, record the exact command options. Comparing two outputs without noting different roots can make a normal scope difference look like newly introduced corruption.
Do not equate dangling with damaged
A dangling object is present but not directly used in the relevant object relationships. Normal history editing, temporary commits, and interrupted workflows can leave such objects behind.
An unreachable object is not reachable from the selected roots. That classification describes the graph, not the object’s business value. It may be recoverable work, obsolete data, or part of an investigation.
Review the object identity and relevant history before taking action. If recovery is appropriate, work from a preserved copy and deliberately protect the recovered object with a suitable reference rather than relying indefinitely on incidental retention.
Distinguish missing objects from unreachable objects
A missing referenced object is a different problem from an existing object that is not reachable. Missing data can prevent history traversal or file reconstruction even when the branch reference still exists.
Identify the object and the part of history that needs it. Determine whether another trusted clone, backup, or approved remote has the required object. Do not fetch arbitrary data from an unverified source merely to make an error disappear.
After a controlled recovery, rerun the integrity check and verify the affected files or history. Restoring one missing object may reveal another issue farther along the graph.
Review alternate stores and partial environments
Repositories can rely on alternate object stores, packed objects, or specialized clone arrangements. A copied repository directory may fail if the external objects it relied on were not preserved or are no longer accessible.
Full checking includes documented alternate object locations. That makes those locations part of the evidence and availability boundary, not an implementation detail to ignore during backup or migration.
For partial or otherwise specialized clones, consult the supported behavior before interpreting object availability. Do not assume every repository is a self-contained ordinary clone with all historical file content stored locally.
Use connectivity-only checks honestly
--connectivity-only can reduce work by checking graph connectivity without reading blob contents. It verifies that referenced blobs exist, but it does not detect blob-content corruption and omits other semantic checks described in the documentation.
That option can be useful for a narrowly stated question. It is not interchangeable with a fuller integrity review, and a successful result should be labeled with the reduced scope.
Choose the check based on the incident, not solely on speed. If the concern is damaged file content, avoiding blob reads would remove exactly the evidence needed to investigate it.
Treat strict findings with historical context
Additional checking options can surface structural issues in older history or legacy repository practices. Review the documented meaning of a finding and the repository’s compatibility requirements before rewriting history.
Do not use a broad ignore rule merely to produce a clean-looking report. If an exception is justified, scope and document it, and separate accepted legacy findings from new failures.
A migration should preserve traceability. Changing historical objects can change commit identities and affect signed releases, downstream clones, and links to prior review evidence.
Keep integrity separate from authenticity
Fsck can establish facts about objects and connectivity. It cannot decide that a branch came from the approved maintainer, that a release was reviewed, or that the source is free from vulnerabilities.
Verify intended refs, approved remote identity, signatures or attestations where required, and the release process separately. A well-formed malicious commit is still well formed.
Likewise, an object ID is meaningful only within an appropriate trust and provenance workflow. Do not replace release verification with a statement that the local object database passed a diagnostic command.
Finish with recovery and application checks
When a repair is necessary, preserve the before-state, document the trusted recovery source, and repeat the relevant integrity checks afterward. Confirm that expected branches, tags, and files resolve correctly.
Then run the appropriate build or test workflow in an authorized environment. Repository integrity and application behavior remain distinct; a repaired object database may contain a perfectly intact software bug.
Keep cleanup separate from diagnosis and recovery. Prune only after recoverable work and evidence retention requirements are resolved, using the repository’s reviewed maintenance policy.
Frequently asked questions
Are dangling commits always safe to delete?
No. They can contain work that is no longer named by a branch but is still valuable for recovery or investigation.
Does connectivity-only inspect file contents?
No. It deliberately avoids reading blobs, so its successful result does not establish blob-content integrity.
Does a clean fsck verify a release signature?
No. Signature and provenance checks are separate from object database integrity checks.
Consult the official git-fsck documentation for the exact options, roots, and diagnostic meanings supported by your Git version.
For a complementary workflow, read Git Reflog Recovery: Preserve Before You Reset.
