advanced45 minby DevFox

Inside the Git Object Model

Open .git with plumbing commands: blobs, trees, commits and tags, how a hash is computed, refs as files, revision syntax as graph arithmetic, and building a commit by hand.

You already drive Git well. You rebase, you cherry-pick, you dig yourself out with the reflog. But somewhere under all of that sits a black box: a .git directory you were told not to poke at, doing work you take on faith.

That box is smaller than it looks — four object types, one hash function, and files containing text. By the end of this lesson you will read a repository's objects by hand, reproduce a Git hash with shasum, and build a commit without running git commit.

Porcelain and plumbing

Git splits its own commands in two. Porcelain commands are the ones you use daily — git status, git log, git merge — built for humans, with colour, hints, and defaults that improve each release. Plumbing sits underneath — git hash-object, git cat-file, git rev-parse — built for scripts, with terse output Git treats as a contract.

That contract is the point. Porcelain output changes between releases; plumbing does not, which is why every Git GUI and shell prompt reads plumbing rather than scraping porcelain.

Four kinds of object, and nothing else

Everything Git remembers lives in .git/objects, a content-addressable store: an object's address is computed from its own bytes. Picture a warehouse where the shelf number is derived from what is in the box — bring the same thing in twice and it lands on the same shelf. Deduplication is not a feature; it falls out of the addressing.

There are exactly four types, and each one points only downward.

Annotated tag
Points at another object, and adds a tag name, a tagger and a message. A lightweight tag is not an object at all — it is only a ref.
Commit
One tree hash, zero or more parent hashes, an author, a committer, and a message.
It stores no diff. Every diff you have ever read was computed on the spot from two trees.
Tree
A directory listing: a mode, type, hash and name per entry, pointing at blobs and other trees.
Blob
File contents. Only the bytes — no filename, no path, no permissions, no timestamp.

A tag points at a commit, a commit at a tree, a tree at blobs and other trees. Nothing points back up.

Reading objects with your own hands

Write a blob into the store, with no file and no staging:

-w writes it; without it Git only computes the hash. Now interrogate the store:

Any unambiguous prefix works. Now walk a real tree — HEAD^{tree} is "the tree HEAD's commit points at":

Mode, type, hash, name. The modes are a small fixed set, not general Unix permissions — only what Git can restore:

100644 — a regular file
100755 — a regular file, executable bit set
120000 — a symlink; the blob content is the target path
040000 — a subdirectory, so a tree
160000 — a gitlink: a submodule, stored as a commit hash from another repository entirely

Pretty-print 148a8c1c for the src listing. Trees pointing at trees and blobs, all the way down.

Inside a commit object

A commit is text as well:

One tree line, one parent line per parent (none on a root commit, two or more on a merge), author, committer, blank line, message. Diffs, "files changed", rename detection — all computed on demand by comparing this tree to its parent's.

The author wrote the change; the committer put this exact object into the store. They match until you rewrite history. Amend, then look again:

Same author timestamp, new committer timestamp. That is why a rebased branch keeps its authorship dates while its commits are new objects.

Where the hash actually comes from

The hash is not of the file. It is of a header plus the content: the type, a space, the content's byte length, a NUL byte, then the content. The string hello object model\n is 19 bytes, so:

Byte for byte, the hash Git gave you earlier (sha1sum works too). Nothing is hidden: no filename, no timestamp, no repository identity. Identical content anywhere on earth gets the same name, which makes fetch and push a matter of comparing names, not files.

Since 2017 SHA-1 has had practical collision attacks, so Git ships sha1dc, a hardened SHA-1 that detects the byte patterns those attacks need and refuses to hash them. There is also a full SHA-256 format:

The caveat is real: SHA-256 repositories cannot interoperate with SHA-1 ones. You cannot push between them and most hosts reject them — finished work the ecosystem has not caught up to.

A branch is forty-one bytes

A ref is a file containing a hash. That is the mechanism.

HEAD is different: a symbolic ref, a file holding another ref's name. That indirection is all of "which branch am I on".

Run git switch --detach <commit> and HEAD holds a raw hash instead. That is detached HEAD, demystified. (Prefer switch here over checkout: it does one thing, move HEAD.) git pack-refs --all sweeps refs into .git/packed-refs, so an empty .git/refs/heads is normal.

Revision syntax is arithmetic on the graph

Once commits are nodes with parent pointers, revision syntax stops being trivia. Take this history, whose merge has two parents:

^n selects which parent; ~n walks how far back, always following the first parent.

Syntax	Means
`HEAD^1`	first parent — `fc32ac8`, "Main work"
`HEAD^2`	second parent — `a45ec8c`, "Feature"
`HEAD~1`	one step back, first parent — `fc32ac8`
`HEAD~2`	two steps back — `9cb35ca`, "Base"
`@`	shorthand for `HEAD`
`HEAD@{2}`	where HEAD was two moves ago (reflog)
`HEAD^{tree}`	the tree of HEAD's commit
`v1.0^{commit}`	the commit an annotated tag points at
`:/fix login`	newest commit whose message matches

Ranges are set operations. A..B is "reachable from B but not from A". A...B is the symmetric difference: either, not both. ^A B is that first range longhand — ^ excludes, so you can span several tips.

The index, and a commit built by hand

The staging area is not a metaphor. It is .git/index, a binary file listing every tracked path with a mode, blob hash, and stage number:

That trailing 0 is the stage number; it stays 0 until a conflict, when Git parks stages 1, 2, and 3 side by side for base, ours, and theirs. git write-tree freezes the index into a tree, git read-tree loads one back. Now build a commit with no porcelain:

A real commit, on a real branch, and git commit was never invoked. Those lines hashed content into a blob, folded the index into a tree, wrapped tree and parent into a commit, and rewrote a 41-byte file. That is all git commit does.

Packfiles, and what keeps an object alive

New objects are written loose — one zlib-compressed file per object under .git/objects/ab/cdef.... Fine for a hundred objects, ruinous for a million, so git gc rewrites them into a packfile under .git/objects/pack, storing similar objects as deltas.

Size, packed size, offset; delta entries add a chain depth and a base hash.

An object survives because something reaches it: refs point at commits, commits at trees and parents, trees at blobs. Anything unreachable from a ref, the index, or a reflog entry is garbage that git gc prunes.

This is the machinery under the reflog safety net you already trust. "Lose" a commit to a bad reset and the object sits there unreferenced but intact, with a reflog entry keeping git gc away — 90 days by default, 30 for unreachable objects. Recovery is pointing a ref back at it.

A cheat sheet to keep

Where to go next

You now have a full map of Git's storage: four object types in a content-addressable store, refs as files holding hashes, a real index file, and packfiles as pure optimisation on top. Every porcelain command combines those pieces, and cat-file and rev-parse let you watch it happen.

Next comes finding regressions with git bisect, which puts this model to work: bisect is a binary search over the commit graph, and seeing it that way rather than as a magic bug-finder is what lets you automate it.

Before you move on, spend twenty minutes in a scratch repository. Hash a string by hand and match it. Walk a tree down to a blob. Build a commit with commit-tree and put a branch on it. The model sticks only once you have driven it.