Theory

Updated

October 30, 2026

Theory: The Add/Commit Cycle is the Product

A repository is useful the moment you can take bytes on disk, choose a subset, and name a snapshot. Everything else (branch, rebase, push) is names and copies of that operation.

Invariants

git init creates .git/ and a symbolic HEAD. The first commit creates refs/heads/main.
git add copies working-tree bytes into the index (and writes blobs). It does not create a commit.
git commit writes a tree from the index, then a commit, then slides the current branch name.
git status is three comparisons: working vs index, index vs HEAD, untracked vs index.
Undo of uncommitted work is restore. Undo of the last unpublished commit is --amend. Undo of published history is revert (later).

  edit  →  add  →  commit
   WD       index    HEAD / main

  status reports which of the three disagree

Why the index exists

Without an index, every commit would be “whatever is on disk.” The index is how you commit two of five edited files, or one hunk of a file (add -p). That is also why .gitignore exists: untracked paths never enter the index unless you force them.

What can break

git add . of .env and secrets (ignore first).
git commit -a on a new file (it only auto-stages tracked paths).
git init in $HOME and then every subdirectory looking like a repo.
Amending after someone else fetched that hash.

How to read this chapter

Init, add/commit, status/log/diff, and undo are the loop. The hands-on page is that loop on desk-api. Ignore, interactive add, rm/mv, and “what not to commit” are the same loop with sharper edges.