Everything we have seen in this module took one thing for granted: that the object database was healthy. The reflog found the hash, git branch created the pointer, git show read the commit. The objects were where they were supposed to be and their content was correct.

This lesson deals with when it is not.

It is the most frightening message in the whole course, and there are two things to start with.

The first is that it is almost never genuine corruption. Most alarming messages have mundane causes: a full disk, an interrupted process, an antivirus that locked a file. Before "repairing" anything, you have to rule those out.

The second is what makes this lesson habitable: in a distributed system, every clone is an almost complete backup. Bruno's repository has the same objects as yours. So does the server. That is, almost always, the fastest recovery route, and often the right answer is simply to clone again rather than trying to fix anything.

We are going to see how to tell real corruption from something else, how to read git fsck without panicking, how to repair the frequent cases in order from least to most serious, and — most importantly — when to stop trying.

1. When to suspect corruption and when it is something else
2. The real causes of corruption
3. git fsck as a diagnostic tool
4. Repairs, from least to most serious
5. The safety net of the distributed model
6. Rebuilding a repository while keeping your work
7. Prevention: maintenance and proper backups
8. When to stop repairing and clone again

First of all, the elimination table. Many errors that look like corruption are not.

Before touching anything in .git:

If you see Use% 100%, that is the problem. Free up space before going on; any repair is going to write objects and will fail all the same.

If instead of a local ext4/apfs/ntfs you see nfs, cifs, fuse.sshfs or a path inside Dropbox, OneDrive, iCloud or Google Drive, you already have the explanation, and it is section 2.

Git is remarkably robust. Objects are immutable, they are written once, and each one carries its own checksum: an object's name is the hash of its content, so any alteration is detected on reading it (lesson 01-04). Corruption, when it happens, almost always comes from outside.

Do not put a Git repository inside a cloud-synchronised folder.

It is the classic cause, and the reasoning is simple: Git writes many small files in a specific order (object, then index, then reference). A synchroniser uploads them according to its own criteria and speed. If you work from two machines, the synchroniser can combine a .git/index from one with the references from the other, or create files of the sort main (conflicted copy 2026-07-28).lock.

The result is a repository in a state Git could never have produced.

And the ironic part: there is no need for it at all. Git is already a distributed synchronisation system. To have the project on two machines, the answer is a remote, not Dropbox.

If you genuinely need a repository to live there, the only safe way is for it to be a bare repository (--bare) used as a remote, which is never written to from two places at once. Even so, git bundle (section 7) is a better idea.

If Carla works on Windows 11 and suffers intermittent errors:

And in Git for Windows, a setting that reduces problems with antivirus software and with slow filesystems:

git fsck (file system check) walks the object database, verifies that each object's content matches its hash, and checks that all the references between objects resolve.

Useful options:

This is the table that avoids unnecessary panic.

The golden rule for reading fsck:

If that returns nothing, your repository is healthy. Full stop. Everything you saw was noise.

Three apparently alarming lines, zero problems. They are the remains of last week's reset --hard and of a git add that never got committed. An active repository always has this.

Here there is real work to do. A broken reference and an unreadable object, with the tree that needs it identified. That is section 4.

That message, for a hash you know existed, is confirmation that the object has disappeared.

or

You have lost nothing. And the reason is conceptually important:

The index is a derived cache. It contains no unique information: it is a snapshot of what should go into the next commit, entirely reconstructible from HEAD and the working directory.

That is why the repair is one of the most rewarding in Git:

The only thing lost is what was staged with git add: after the rebuild, all your modifications appear as unstaged. The changes themselves are intact, because they live in the files on disk, not in the index.

An important nuance: use git reset (--mixed), never git reset --hard. The first rebuilds the index and leaves the working directory alone; the second would sweep away all your modifications (lesson 09-02).

If you also had a merge conflict half done, the information from the index stages (:1:, :2:, :3: from lesson 03-05) is indeed lost, and the merge has to be redone:

Already seen in lesson 09-01, here in its complete version. Locks are .lock files that Git creates before writing and deletes when it finishes:

The procedure:

A special case that deserves care: .git/config.lock. If Git died while writing the configuration, the .git/config file may have been left truncated. Check it before deleting the lock:

If it is broken, the local configuration is the easiest thing in the whole repository to redo by hand.

What it is. The file refs/heads/GT-241 contains a hash that does not correspond to any existing object. Remember that a branch is 41 bytes of text (lesson 03-01):

Confirmed: the reference points at nothing.

Repair A: the branch's reflog. It is the best option, because it preserves history:

Try the entries from the top down until you find a valid one:

You have lost the last commit, but you get the branch back. Far better than nothing.

Repair B: packed-refs. References also live consolidated in a file (lesson 08-06):

Sometimes the packed version is valid even though the loose one is broken. If you delete the loose one, Git uses the packed one:

Repair C: the remote.

Repair D: if the branch does not matter, delete it.

And the bulk clean-up, when there are many broken references:

This is the serious case.

First step, the exact diagnosis:

Zero bytes: an interrupted write. It is the typical pattern of a full disk or a power cut.

The repair that almost always works: bring it from another clone.

This is the central idea of the lesson and section 5 develops it. Git objects are identical everywhere: the same content produces the same hash and the same compressed file. If Bruno has that commit, his object serves exactly the same purpose.

If the other clone has it packed rather than loose, it has to be extracted:

If the resulting hash matches the one that was missing, the repair is exact. And it cannot fail to match: the hash is calculated from the content, so if a different one comes out, the content was not the same (lesson 01-04).

For an object of type tree or commit, the same procedure with -t tree / -t commit and the exact content that cat-file -p gives in the healthy clone.

If the object was a damaged packfile:

A broken packfile is worse, because it contains thousands of objects and the delta chains depend on one another (lesson 08-06). You can try to extract what is salvageable:

But let us be clear: with a damaged packfile, the right answer is almost always to re-clone (section 8). Extracting objects from a broken pack is an exercise in archaeology that rarely pays off when there is a healthy clone one git clone away.

HEAD is a one-line text file (lesson 03-01):

What it should contain:

What may have happened:

If no valid branch remains, the HEAD reflog is still plain, readable text even when Git does not work:

It is the easiest file to repair, because its content is trivial to redo:

If it is truncated, edit it (here you may, with a text editor: config is plain text by design and Git does not verify it with hashes) or rebuild the essentials:

Here is the idea that makes this lesson manageable, and that closes the circle opened in module 1.

In a centralised system, the server is a single point of failure: if it becomes corrupted, the project has become corrupted. In Git, each clone contains the entire history. Ana, Bruno, Carla, Diego and the server have five complete copies of the object database.

Practical consequence: when your repository becomes corrupted, the right question is not "how do I repair it?" but "what do I have that nobody else has?".

GT-241 has no upstream: it exists only on this machine. It is the only thing that needs saving.

With those four answers you already know exactly what the repair is worth. If the answer is "nothing, it is all published", re-cloning takes two minutes and is the perfect solution.

And if the problem is with the server, the direction is reversed: any clone in the team can rebuild it.

--mirror copies all the references as they are: branches, tags, notes. It is the correct way to duplicate a bare repository.

The complete procedure, for when you have decided to re-clone but have local material to save.

Even if you are going to re-clone. It costs ten seconds and it is the only thing that stops a mistake during the rescue being final.

git bundle packs commits into a single file that works as a remote. It is the right tool for this, and it works even if the repository is partially damaged (as long as the objects involved are healthy).

If you also have uncommitted changes, take those out separately:

If git bundle fails because the repository is too badly damaged, the brute-force route also works:

You lose the local branches' history, but you keep the content, which is usually what mattered.

The local branches are back, with all their commits.

If there are no errors and all your work is there:

Do not delete the copy until you have verified. It is the only rule that matters in this section.

Picking up from lesson 08-06:

As well as improving performance, it keeps the object database tidy and reduces the number of loose files exposed to interrupted writes.

And a periodic check, which in a normal repository takes seconds:

And a configuration that makes Git verify objects as it receives them, catching corruption at the time instead of months later:

It costs a little time on each fetch and in exchange it prevents a malformed object entering your repository. On the server, receive.fsckObjects is downright mandatory.

A bundle is a single file containing whatever you ask for, which works as a remote. It is portable, verifiable and does not depend on any service.

And incremental copies, if the repository is large:

A weekly backup script:

Why a bundle is better than copying .git with cp:

1. Never a repository in a cloud-synchronised folder. The number one cause. Use a remote.

2. Never .git on a network volume if you can avoid it. Clone locally and push.

3. Exclude your project folders from the antivirus on Windows.

4. Keep an eye on disk space. A df -h now and then.

5. git maintenance start in your working repositories.

6. transfer.fsckObjects true to detect corruption as it comes in.

7. Publish your branches. A published branch is on two machines. It is the best backup and the cheapest.

8. A weekly git bundle of what only you have.

9. Do not kill Git processes with kill -9, especially during gc or repack.

10. Do not edit .git files by hand (apart from config, which is text by design). Use git update-ref, git symbolic-ref, git config.

The most important decision in the lesson, and the one that saves the most time.

Re-cloning is the right answer when:

• The repository is completely published (nothing local unpushed). Then re-cloning costs nothing at all.
• There is a damaged packfile. Extracting objects from a broken pack rarely pays off.
• git fsck returns more than a handful of errors.
• The corruption comes back after you repair it: there is an underlying cause (disk, cloud, antivirus) you have not resolved.
• You have spent more than thirty minutes trying to repair it. The cost of a git clone is minutes; that of an afternoon of archaeology is not.

It is worth attempting the repair when:

• The problem is the index, a lock, HEAD or config. It is minutes and nothing is lost.
• It is one broken reference and the reflog or packed-refs resolves it.
• One object is missing and you know where to get it.
• You have important unpublished local work and need to extract it before re-cloning (section 6).

In tree form:

And the sentence that sums up the lesson:

A damaged Git repository is not a data problem: it is a logistics problem. The data is almost always somewhere else. Your job consists of identifying what is exclusively yours, saving it, and bringing the rest from wherever it is healthy.

Mistake 1: being alarmed by git fsck's dangling entries. They are completely normal in any active repository. Filter with grep -v "^dangling" and see whether anything is left.

Mistake 2: writing off as corruption what is a full disk. df -h is the first command. Repairing with the disk at 100 % cannot work.

Mistake 3: keeping the repository in Dropbox, OneDrive or iCloud. It is the number one cause of real corruption, and there is no need for it at all: Git already synchronises.

Mistake 4: git reset --hard to repair a corrupt index. rm .git/index && git reset rebuilds it without touching your files; with --hard you would lose them all.

Mistake 5: editing .git files with a text editor. Apart from config, use the commands: git update-ref, git symbolic-ref, git config.

Mistake 6: repairing without having made a copy. cp -a costs ten seconds and stops a mistake during the rescue being final.

Mistake 7: spending hours repairing a repository that is entirely published. Check first what you have that nobody else has. If the answer is "nothing", re-clone.

Mistake 8: using cp -a .git as the "official" backup. It will do in an emergency, but it can copy a half-finished state. git bundle is consistent and verifiable.

Mistake 9: deleting the broken repository before verifying the new one. Verify with git fsck and check that all your work is there; then delete.

Tip 1: learn the fsck filter. git fsck --full --no-progress 2>&1 | grep -vE "^(dangling|notice)". If it returns nothing, you are healthy.

Tip 2: a weekly git bundle create ... --all. One file, verifiable, restorable with git clone.

Tip 3: transfer.fsckObjects true in the global configuration. It detects corruption as it comes in, not months later.

Tip 4: publish your branches. It is the cheapest backup and the one that saves the day most often.

Tip 5: the index is a cache. Losing it does not matter; remembering that avoids a lot of unnecessary panic.

Tip 6: set yourself a time limit. Thirty minutes of repairing and, if it is still broken, re-clone. The clone takes two.

1. Create a repository with ten commits, a branch with three commits of its own and an uncommitted git add.
2. Produce dangling objects: a reset --hard HEAD~3, a commit --amend and a branch -D.
3. Run git fsck --full and count how many lines it returns.
4. Apply the filter from tip 1 and check that nothing is left. Explain why the repository is healthy despite the earlier lines.
5. Identify, among the dangling ones, which corresponds to the uncommitted git add and recover it with git cat-file -p.

On a test repository (never on a real one):

1. Corrupt the index: printf 'rubbish' > .git/index. Run git status and note the error. Repair it and explain why nothing is lost.
2. Break a reference: echo "0000000000000000000000000000000000000000" > .git/refs/heads/GT-241. Run git fsck and repair it with the reflog.
3. Break HEAD: echo "ref: refs/heads/nonexistent" > .git/HEAD. Diagnose and repair with git symbolic-ref.
4. Empty a loose object: locate one with find .git/objects -type f and truncate it with : > <file>. Run git fsck --full and observe the error.
5. Repair point 4 from a healthy clone that you will have made before breaking anything.
6. After each repair, run a filtered git fsck --full and confirm that it is clean.

1. Set up a local remote with git init --bare and clone it.
2. In the clone, publish two commits on main and create two unpublished local branches with three commits each. Add a stash and some uncommitted change.
3. Do the inventory from section 5: which branches have no upstream, which commits are not on the remote.
4. Create a bundle with all the local material and verify it.
5. Delete the whole clone (simulating irreparable corruption) and clone again.
6. Bring the two branches back from the bundle and check that the six commits are there.
7. Explain what has been lost and what has not, and how you would have avoided it by publishing the branches.

Solution 1:

Nine worrying-looking lines.

Zero errors. The repository is perfectly healthy.

The reason: dangling means "this object exists and is readable, but no reference reaches it". It is exactly the expected result of a reset, an --amend and a branch -D: the commits are still there (which is why they are recoverable, lesson 09-04) but they no longer hang off any branch. It is the opposite of a problem: it is the proof that the safety net works.

Real errors start with error:, missing or broken link, and there are none here.

Solution 2:

Nothing lost. The modification was still in the file on disk; the index was only the snapshot of what was going into the next commit, and it is rebuilt from HEAD plus the working directory. It is a cache.

Repaired, complete with its commit. The reflog kept the correct hash because the reflog file is independent of the reference file.

Git does not fail, but it believes it is on a branch that does not exist: git log shows nothing and a commit would create a new branch.

Git refuses to operate: it cannot read an object it needs.

The hash matches, so the repair is demonstrably exact. It cannot be otherwise: an object's name is the hash of its content (lesson 01-04), so if the same hash comes out, the content is identical byte for byte. It is this property that makes repairing a Git repository from another clone safe and verifiable.

Solution 3:

Six commits, two branches, a stash and two changes exist solely on this machine. That is exactly what the repair is worth.

Only the published material.

The six commits and the two branches, with their original hashes.

What has been lost:

• The stash stack as such. The content has been reapplied from the patch, but the stash@{0} entry does not exist. (A bundle with --all would have included refs/stash.)
• The whole reflog, which is local and does not travel (lesson 09-04). The new clone has three entries.
• The old tracking branches and the repository's local configuration.

What has not been lost: not a single commit, not a single change.

How it would have been avoided: by publishing the branches.

With both branches published, the inventory in step 3 would have come out empty, and this whole lesson would have been reduced to rm -rf work && git clone. Two seconds of push against twenty minutes of rescue.

Corruption of a Git repository is far more frightening than it is costly.

• Most alarming messages are not corruption: an orphaned lock, a full disk, a permissions or ownership problem. Rule that out first with df -h and ls -ld .git.
• The real causes almost always come from outside Git: a repository in a cloud-synced folder (the number one), a full disk, a power cut, a network volume, an antivirus. Git objects are immutable and carry their own verification; Git rarely breaks by itself.
• git fsck is read by filtering out the noise. Dangling objects are completely normal — they are the remains of every reset, rebase and --amend — and their presence is proof that the safety net from lesson 09-04 works. The serious stuff starts with error:, missing or broken link.
• The repairs, from least to most serious: the index is a derived cache and is rebuilt with rm .git/index && git reset without losing anything; locks are deleted after checking processes; a broken reference is repaired with the reflog, packed-refs or the remote; HEAD with git symbolic-ref; an unreadable object by bringing it from another clone, with the guarantee that if the hash matches, the repair is exact.
• The distributed model is the safety net. Every clone in the team is an almost complete copy. The right question when faced with a damaged repository is not "how do I repair it?" but "what do I have that nobody else has?", and it is answered with git for-each-ref and git log --branches --not --remotes.
• The rescue is done with git bundle: pack the local material into a file, re-clone, and bring it back with git fetch <bundle>. And always with a prior cp -a and a subsequent verification before deleting anything.
• Prevention: no repositories in the cloud or on network volumes, git maintenance start, transfer.fsckObjects true, a periodic git bundle and — what pays off most — publishing your branches.
• And the criterion: if everything is published, re-clone. It takes two minutes and it is the right answer. Save the repairing for the index, the locks, HEAD and the references, or for extracting local work before re-cloning.

With this, the module has covered the four problems announced at the close of module 8: the unfortunate reset --hard, the tangle with the remote, the deleted branch and the repository that refuses to work.

What remains is the cross-cutting part. Because very often the problem is neither that Git is broken nor that you have lost something, but that Git is doing something you do not understand: a file that is ignored when it should not be, a configuration coming from somewhere you did not know existed, a push that fails for opaque reasons, a change of behaviour nobody remembers introducing. For that there is a toolbox of its own — traces, plumbing, check-ignore, check-attr, ls-files — and, above all, a method.

Continue in lesson 09-06: Advanced Debugging Techniques.