Git & GitHub · 9 min · 110 XP

Commits that tell a story

Make commits small enough to review and clear enough to read in a year.

A commit is a snapshot of your project plus a note explaining it. Git keeps every snapshot, so the history becomes a story of how the code got here. When something breaks six months from now, that story is what you read to find out why a line exists. A good commit does one thing and says why.

Changes reach a commit in two steps. git add moves them into the staging area, and git commit records whatever is staged. The pause between the two steps is useful: if you fixed a bug and renamed a variable in the same file, git add -p lets you stage the fix alone, commit it, and commit the rename separately.

Stage part of a file, check it, then commit
git status              # what changed, and what is staged
git add -p src/cart.js  # pick the hunks that belong to this commit
git diff --staged       # read exactly what you are about to commit
git commit

The message has two parts. The subject line is short (about 50 characters) and written as a command: Fix rounding in cart total, not Fixed stuff. After a blank line, the body explains why the change was needed. The diff already shows what changed; nothing else records why.

A message someone can use later
Fix rounding in cart total

Prices were summed as floats, so 2 x 9.99 + 24.50 came out as
44.480000000000004 and failed the equality check at checkout.
Sum in cents and convert once at the end.

Forgot a file or made a typo in the last commit? git commit --amend replaces it. Only do this before you push: amending creates a new commit with a new ID, so anyone who already pulled the old one ends up with a history that no longer matches yours.

Scenario: you run git status
$ git status
On branch main
Changes to be committed:
        modified:   src/cart.js

Changes not staged for commit:
        modified:   src/cart.js
        modified:   README.md
Scenario: your log, just before pushing
$ git log --oneline
c4d5e6f (HEAD -> main) Add discount code field
a1b2c3d (origin/main) Fix rounding in cart total
9e8d7c6 Show free-shipping banner

Try it on your machine: in your practice repository, make two unrelated changes to one file. Stage just one with git add -p, commit it with a subject and a body that says why, then commit the other. git log should read as two clear entries.

Loading your workspace…