How Much Belongs in One Commit

Nobody tells beginners how big a commit should be, so everyone works it out by overshooting in both directions: one commit a week for a while, then a commit per saved file after someone says commits should be small.

The useful rule is not about size. One commit is one complete idea — something you can describe in a single sentence without the word "and".

Too big

A whole day's work in one commit is the more common mistake, and it costs you three things at once.

You cannot undo one part of it. Chapter 4 can remove a commit cleanly, but if that commit contains a good change and a bad one, removing it takes both. You cannot review it, which matters the moment somebody else is reading your work in Chapter 8. And you cannot describe it honestly — which is why the message ends up saying "update".

Too small

The opposite is a commit every time you save a file. The history becomes a list of keystrokes, and the three commits that actually mattered are buried among forty that did not.

The reader you are writing for is a person scanning git log --oneline and trying to see the shape of the work. Forty entries called "wip" tell them nothing.

The sentence test

Before committing, write the message in your head. If it needs the word "and", you are probably holding two commits.

This is where staging pays for itself. Say you added the sightings list and, while you were there, fixed the header spacing. Two ideas, two messages, two commits:

git add sightings.js
git commit -m "Add the recent sightings list"
git add style.css
git commit -m "Tighten the spacing under the header"

Between those two commands, git status shows style.css still sitting in the working directory, exactly as you left it. Nothing was rushed and nothing was undone.

Commit when it works

One more guideline, and it is the one that turns the history into something you can actually travel back to: commit at a point where the project works.

For Sandpiper, "works" means the page opens and looks roughly right. A commit that does not work is a trap for whoever visits it later — including you, hunting for the change that broke something, and finding a state that was broken for an unrelated reason.

This does not mean waiting until a feature is finished. A feature can take a week, and a week without commits is a week with no safety net. It means finding the small steps that each leave the project in one piece.

A rhythm

Several commits an hour is normal while the work is going well. If two hours have passed with nothing committed, that is usually a signal rather than a virtue — you have probably started three things at once and none of them is finished.

A practical response: stop, run git status, and see whether one of the three is complete enough to commit on its own. Almost always one is, and the other two get easier the moment it is out of the way.