The Working Tree, the Index, and the Repository

Turning a folder into a repository is one command, and it adds exactly one thing.

$ cd my-project$ git init# Initialized empty Git repository in /Users/you/my-project/.git/

That .git directory is the repository. Your files are not "in Git" — they are in the folder, exactly where they were, and .git sits alongside them holding every commit, every branch, and all the configuration.

.git/  HEAD          # which branch you are on, as one line of text  config        # this repository's settings  objects/      # every commit, every version of every file  refs/heads/   # one file per branch, each holding a commit hash  index         # the staging area — a single binary file

This is the model that makes every later command make sense. At any moment, one file has up to three different versions on your machine simultaneously.

Edit a file and the working tree differs from the index. Run git add and the index catches up. Run git commit and the repository catches up. All three are now identical, and git status says nothing to report.

Nearly every other version control system commits whatever is on disk. Git makes you name the changes first, and beginners reasonably experience this as an extra step for no reason. It buys one specific thing: the ability to commit some of your current work.

A real afternoon does not produce one clean change. You fix the bug you sat down to fix, rename a confusing variable you tripped over, and delete some dead code. Three unrelated things, in four files. Without staging you have one choice: one commit called "stuff".

# Commit the bug fix on its own$ git add src/auth/redirect.ts$ git commit -m "Fix the redirect when next is empty" # Then the rename, separately$ git add src/lib/users.ts src/lib/session.ts$ git commit -m "Rename usr to currentUser for readability" # And the deletion last$ git add src/legacy/$ git commit -m "Delete the unused legacy exporter"

Three commits that each do one thing, from one messy working tree. Six months later, when somebody bisects a bug to the rename commit, they can revert it without also reverting the bug fix. That is what the staging area is for.

Run it constantly. It is free, it changes nothing, and it tells you the state of all three trees in one screen. Experienced people run it more often than beginners, not less.

On branch mainYour branch is up to date with 'origin/main'. Changes to be committed:  (use "git restore --staged <file>..." to unstage)        modified:   src/auth/redirect.ts Changes not staged for commit:  (use "git add <file>..." to update what will be committed)  (use "git restore <file>..." to discard changes in working directory)        modified:   src/lib/users.ts Untracked files:  (use "git add <file>..." to include in what will be committed)        notes.md

Untracked is the category that catches people. A brand-new file is invisible to git commit -a and absent from every diff. The number of times a new file has been left out of a commit and broken the build for everybody else is not small.

# Same information, one line per file, once you know the letters$ git status --short# M  src/auth/redirect.ts     left column: staged#  M src/lib/users.ts         right column: modified, not staged# ?? notes.md                 untracked

Keep this sentence in mind throughout the chapter: git commit records the index, not your working tree.

So if you stage a file, then keep editing it, and then commit — the commit contains the version as it was when you staged it. Your newer edit is still sitting in the working tree, uncommitted. Git will tell you this, in the status output, in a section you have to actually read.

$ git add report.md          # index now matches disk# ... you keep typing ...$ git status --short# MM report.md#   left M:  a staged version, from the git add#   right M: newer edits on disk, not staged

The file carries two letters, one per column, because there are two different versions of it — and in the full git status it is listed under both headings. The fix is to git add again before committing. This is not a bug and it is not a trap — it is exactly the behaviour that makes staging useful — but it is the most common source of "I committed it and the change is not there".

Try it yourself. Make a throwaway repository and watch one file move through the three places. The comments show the expected output from the status and diff commands.

$ mkdir scratch && cd scratch$ git init$ echo "one" > notes.txt$ git status --short     # ?? notes.txt   untracked$ git add notes.txt$ git status --short     # A  notes.txt   staged as a new file$ echo "two" >> notes.txt$ git status --short     # AM notes.txt   staged, then changed again$ git diff --staged      # shows only the line "one"$ git add notes.txt$ git commit -m "Add notes"$ git status --short     # (nothing: all three places agree)