Git from First Principles

Git is a database of snapshots, addressed by the hash of their content, plus a few movable labels that point into it. Almost every command either adds objects to that database, moves a label, or copies objects between two databases. Hold on to that sentence: the rest of this guide unpacks it.

How to use this guide

Fluency means three things. You can predict what a command will do before you run it. You can recover from any mistake without panic. And you can design a workflow that a team, or an AI agent, can follow safely.

The learning path

1. Parts 1–4: the model. Why version control exists, how Git stores data, what branches really are, and where your changes live. Read slowly and run every snippet.
2. Parts 5–9: daily use and collaboration. Each command is explained as an operation on the model, not as a recipe.
3. Parts 10–11: AI work. What changes when you version models, datasets, prompts, experiments and code written by agents.
4. Parts 12–14: power tools, internals, recovery. Debugging history, building a commit by hand, and getting out of every common mess.
5. Part 15: practice. Exercises in order, a fluency checklist, and a glossary.

Your lab

Make a throwaway repository and break it freely. Nothing you do here can touch your real projects.

mkdir -p ~/git-lab && cd ~/git-lab
git init demo && cd demo
git config --global init.defaultBranch main   # once per machine

Set two aliases now; you will use them in every part.

git config --global alias.st "status -sb"
git config --global alias.lg "log --oneline --graph --decorate --all"

The four questions to ask of any command

This guide explains every command by answering the same four questions. Ask them yourself whenever you meet a new command or flag.

1. What does it read? The working files, the staging area, commits, or a remote.
2. What does it write? New objects, a moved reference, the staging area, your working files, or a remote.
3. Is it local or networked? Only clone, fetch, pull, push and ls-remote talk to other machines.
4. How do I undo it? If you cannot answer this before running it, stop and find out.

Where to look things up

• git help <command> opens the official manual page. The same pages live at git-scm.com/docs.
• Pro Git by Scott Chacon and Ben Straub is free at git-scm.com/book. Chapter 10, “Git Internals”, pairs with Part 13 here.
• git <command> -h prints a short flag summary in the terminal.

When a search result gives you a recipe, translate it with the four questions before running it. A recipe you can explain is knowledge; one you can’t is a risk.