#Git Handbook

Git feels arbitrary because most people learn it as a list of commands. add, commit, push, and then one day something goes wrong and none of the memorised commands apply.

There is a model underneath, and it is small. Learn it and the commands stop being magic incantations — they become moves between four places.

#1 · The whole model in one diagram

flowchart LR
    W["Working<br/>directory"] -->|"git add"| S["Staging area<br/>(index)"]
    S -->|"git commit"| L["Local<br/>repository"]
    L -->|"git push"| R["Remote<br/>repository"]
    R -->|"git fetch"| L
    L -->|"git checkout / restore"| W
    S -->|"git restore --staged"| W
    L -->|"git reset"| S

    classDef local fill:#e4edf6,stroke:#1f4e79,stroke-width:2px
    class W,S,L local

Four places. Almost every command moves something between two of them. When a command confuses you, the question is always: which two areas does this touch, and in which direction?

The staging area is the part that trips people up, and it is the part that makes git better than the alternatives: you choose precisely what goes into a commit, rather than committing everything you happened to change.

#2 · What this handbook is not

It is not a command reference — git help and the man pages already exist and are better at that. This is the model, the state transitions, and the recovery paths, because those are what a reference cannot give you.

Every claim about git's behaviour here was executed against a real repository and the output is real. Where a diagram shows what a command does, that is what it actually did.

#3 · Reading order

flowchart TD
    A["How git actually works<br/>objects, refs, the DAG"] --> B["Everyday git<br/>the 12 commands you need"]
    B --> C["Branching & merging<br/>merge vs rebase"]
    C --> D["Undoing & recovery<br/>reset, revert, restore, reflog"]
    D --> E["GitHub & GitLab<br/>PRs, MRs, CI, protections"]
    E --> F["Cheat sheet<br/>one page"]

#4 · The three sentences that prevent most problems

1. A commit is a snapshot, not a diff. Git stores the whole tree each time, deduplicated by content hash. Diffs are computed when you ask for them, not stored.

2. A branch is a movable pointer to one commit — nothing more. It is a file containing 40 characters. Creating one is free; deleting one deletes no data.

3. Almost nothing is ever really deleted until gc runs. The reflog remembers where HEAD has been, usually for 90 days. If you think you destroyed work, you probably have not.

#5 · Companion handbooks

Start with how git actually works.