A shortened git history (the shallow-file repair)

What it is

Git supports downloading a project without its full history — called a shallow checkout — and it records where history stops in a plain text file, .git/shallow, one commit id per line. Every command that walks history reads that file and stops there.

The file can also be written when it should not be. Running a partial download against a copy that already holds every commit still writes an entry, even though nothing is missing. What is left behind is a checkout that reports itself shallow for no reason and behaves as though half the project never happened.

Anything that asks git "is this checkout shallow?" believes the answer. A reader that decides its work is too expensive on a truncated history will take the slow road every time, or give up with a timeout on a project that was never actually truncated.

Where to find it

There is nothing to open and no screen to visit. The check runs by itself, once per start, in the background — after the app is up, never blocking it.

You will notice it only in two ways. You may get an inbox card headed A stale git history record was repaired, which names the project and how many entries were removed. Or you may simply find that something that used to be slow is fast again.

The file itself is at <your project>/.git/shallow. A project without that file is a project with nothing to repair — that is the normal case, and the check finishes in milliseconds.

How it behaves

On each start, each project Omniscio owns is asked one question: is there a shallow file, and does it hide anything?

• The file hides nothing. Every entry names a commit whose parents are all present. The file is debris, so it is deleted and history reads in full again.
• The file is empty. Nothing is hidden by definition, so it is deleted. Blanking the file is not enough — git still reports the project as shallow while a shallow file exists at all, even an empty one.
• The file hides something. At least one entry points at a commit whose parent is not on disk. This is a real shallow checkout. The file is left exactly as it was and nothing is written.

Four things it will never do. It never deletes project data — the only thing it removes is a text file that names commits, never a commit, a file or a branch. It never touches a real shallow checkout, because the proof is per-entry and anything with a missing commit behind it keeps its entry. It never downloads anything, because every check runs with fetching turned off. And it never runs on a rented build machine, where shallow checkouts are deliberate, or while something else is writing to the project.

You hear from it only when it actually repaired something. The card names the project, how many entries it removed, and says plainly that a second appearance means something is still writing these files — which is the useful part. One appearance is a cleanup. Two means a tool on your machine keeps making checkouts shallow, and that is worth looking at.

Related

• Git history missing — when a project's .git folder disappears entirely, which is a different and much more serious problem.
• Git storage compaction — the other way Omniscio tidies a project's git data, in that case to reclaim disk.