Learn Git from first principles

Think of a family that takes a portrait every year. Laid side by side, the photos let you step back to any year you like. You want the same thing for code: save points you can return to.

So you keep your project in a folder called working. Each time you finish a self‑contained piece of work, you copy the whole folder to snapshot-0, then snapshot-1, and so on. Inside each copy you drop a small file called message that says what you did and when.

You shipped snapshot-99 as version 1.0 and have made ten more snapshots since. A bug report arrives. You copy snapshot-99 back into working and fix it. Now what do you call the result? snapshot-110 would be a lie: it does not come after 109.

Look at a tree. Every twig, however far out, leads back to the trunk by one simple rule: go to the thing you grew from. So you add one line to each message file, the name of its parent snapshot. History stops being a line and becomes a tree.

In a straight line, the highest number was the newest. In a tree, there is a newest snapshot at the end of every twig, and numbers can't tell you which twig is which.

You could list every snapshot that belongs to a line of work, but that is a lot of data and still doesn't tell you where the end is. The least you need is the tip. Everything else on the line can be found by walking parents. So you keep one file, branches, outside all snapshots, with one name and one snapshot per line.

There is one new chore: when you take a snapshot on a branch, you update that branch's line in the file to point at the new snapshot.

You notice you use names in two ways. "Release maintenance" should move as work continues. "Version 1.0" should mark one snapshot forever. Both are pointers to a snapshot, but one moves and one doesn't, and mixing them invites mistakes.

So the fixed ones get their own file, tags. Same format, different promise.

Zoe joins the project. You give her copies of all your snapshots, branches and tags, and she disappears on a week‑long trip without internet. You both keep working. When she returns, you each have a snapshot-114 and snapshot-115 with different contents, and you can't even tell who wrote what.

Two fixes. First, every message file now includes the author's name and email. Second, a snapshot is no longer named by a counter. It is named by a hash of its message file: a fixed‑length fingerprint computed from the content. The message holds the date, the description, the author and the parent, so two different snapshots will never produce the same name, and the same snapshot gets the same name on every computer.

Zoe spends a lot of time on planes and boats. She loves your system because every everyday action happens on her own disk: taking snapshots, reading history, creating branches, switching between them, comparing versions. The network is needed only at the moment she wants to exchange snapshots with you.

This falls straight out of the design. Everyone holds the whole history, and names come from content, so no central server has to hand out the next number.

Before her trip, you both started from the math branch. Zoe wrote a prime number generator; you wrote a magic number generator. Now you want one codebase with both.

You combine the two into working and take a snapshot. While writing its message file you notice something new: this snapshot has two parents, your latest and Zoe's latest. It adds nothing of its own beyond what it took to combine them. Once Zoe fetches it, your two histories are identical.

You coded late on a branch called drunk and made three snapshots full of mistakes and their corrections. You need a way to talk about them. If drunk names the tip, then drunk^ means its parent and drunk^^ its grandparent. The snapshot you started from is drunk^^^.

Snapshots are frozen, so you can't edit them. Instead you build new ones. Copy the final state into working, remove the new file, and snapshot that with drunk^^^ as its parent. Then copy the final state again and snapshot it with the first new one as parent. Last, move the name drunk to the newest snapshot.

You add a third folder between working and the snapshots: staging. After each snapshot, staging starts as a copy of it. Whenever you finish a change in working, you decide whether it belongs in the next snapshot. If yes, you repeat that change in staging. If not, you leave it in working for later. Snapshots are now made from staging, not from working.

There is one trap. Stage your README edit, keep working, then edit README again. Staging still holds the first edit. Snapshot now, and the second edit is missing. Try it below.

A message tells you what you meant to change, not which lines changed. So you write a small program that compares two folders line by line. Four comparisons come up all the time.

Most files don't change between snapshots, yet you store them again every time. Hashes fix this too. Make one folder, objects, and store each file there under the hash of its contents. That stored file is a blob. If an object with that name already exists, you already have it, and you skip it.

A folder becomes a small list: for each entry, the word blob or tree, a hash, and a name. That list is stored as an object too, a tree. Work from the deepest folder upward and you end with one root tree. Its hash goes into the message file, which is itself stored as an object: the snapshot. Since that hash now covers every file, two snapshots with the same name are guaranteed to hold the same files. You can delete the old snapshot folders and rebuild any of them from objects.

Text compresses very well, so you compress every object before writing it to disk. One detail is worth getting right: real Git computes the hash on the uncompressed content and then compresses with zlib (DEFLATE). That way an object's name depends only on what it contains, not on how it was squeezed.

Git goes one step further than the story. From time to time it packs many objects into a single packfile and stores similar versions of a file as differences from one another. Snapshots are still whole snapshots in concept; deltas are only a storage trick.

Look back at what you built. Deleting a branch removes one line from the branches file. A rewrite moves a name. Neither touches a single object. Committed work is still in objects; you only need its hash to put a name on it again.

Git helps you find that hash. It keeps a diary, the reflog, of every position each branch and HEAD has pointed to. On the workbench, delete a branch and click the faded snapshot: you'll get the same rescue Git gives you.