Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

Loose object format

How Git stores one object per file: the type-size header, zlib compression, the two-level directory path from the object ID, and how to read a loose object by hand.

A loose object is the simplest way Git stores data: one file per object, under .git/objects. The file contains the object's header and content, compressed together with zlib. Every new blob, tree, commit and tag starts life this way; later git gc or a push moves them into packfiles.

The path comes from the object ID. The first two hexadecimal digits name a subdirectory and the rest is the file name, so the object 45b983beโ€ฆ lives at .git/objects/45/b983beโ€ฆ. Splitting on two digits keeps any single directory small, since there are at most 256 of them.

TEXT
.git/objects/45/b983be36b73c0788dc9cbcb76cbb80fc7bb057
             โ””โ”€ first 2 digits   โ””โ”€ remaining 38 digits
file content = zlib( "blob 3" NUL "hi\n" )

Try it

Bash Read a loose object without Git

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Write a loose object by hand and let Git read it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Layout

Header. <type> <size> with the type being blob, tree, commit or tag, a single space, the content length in decimal bytes, then one NUL byte. The size counts only the content, not the header.

Content. The raw object body. For a blob it is the file bytes; for trees, commits and tags see Tree objects, Commit objects and Tag objects.

Compression. The header and content are concatenated and compressed as a single zlib stream (RFC 1950), which by default starts with the bytes 78 01 (Git favors speed for loose objects, as the first example shows). core.looseCompression (falling back to core.compression) sets the level; 0 stores without compressing.

ID. The object ID is the hash of the uncompressed bytes, header included. It does not depend on the compression level, so the same object compresses differently on different machines but keeps its ID. See Object IDs and SHA-256.

Permissions and writing. Git writes to a temporary file in the object directory, then renames it into place. Loose objects are created read-only (mode 0444) because they never change. core.sharedRepository adjusts group access for shared repositories.

Usage notes

  • Not human readable: cat on the file prints binary noise. Use git cat-file -p <id>, which also reads packed objects.
  • Count and size them: git count-objects -v reports loose objects and their disk usage; git gc packs them. A very large number of loose files slows file systems, which is why gc.auto triggers packing at around 6,700 of them.
  • Existence check: git cat-file -e <id> exits 0 if the object exists, whether loose or packed.
  • Corruption: a truncated or damaged loose file produces inflate: data stream error or object file ... is empty. git fsck finds it; restore the object from another clone with git fetch, or copy the file back from a backup.
  • Unreachable loose objects (from amended commits, abandoned stashes, git add of a file you then changed) stay for the gc.pruneExpire period, two weeks by default, which is what makes the reflog and fsck --lost-found recovery work.
  • git hash-object -w writes one directly, and git unpack-objects explodes a pack into loose files; both are plumbing used mostly in tests and scripts.