Staging and Committing Well

Small, logical commits

The history you build is something you’ll read later, to find when something changed, to undo one change without losing others, or to understand why. That works best when each commit holds one logical change: a new feature, a fix, a rearrangement, but not all three at once ¹. If you’ve done several things since your last commit, commit them separately.

The staging area is what makes that possible: you choose exactly what goes into each commit.

Staging part of a file

git add -p (“patch”) walks through your changes one hunk (a block of changed lines) at a time and asks about each ¹:

me@linuxbox:~/garden$ git add -p
diff --git a/README.md b/README.md
@@ -1 +1,3 @@
 # Garden plan
+
+Four raised beds, south side.
(1/1) Stage this hunk [y,n,q,a,d,e,p,P,?]? y
diff --git a/beds.txt b/beds.txt
@@ -2,3 +2,4 @@ tomatoes
 beans
 carrots
 peas
+lettuce
(1/1) Stage this hunk [y,n,q,a,d,e,p,P,?]? n
me@linuxbox:~/garden$ git status -s
M  README.md
 M beds.txt

The answers you’ll use: y stage this hunk, n skip it, s split it into smaller hunks, e edit it by hand, q quit, and ? for the rest ¹. Now git commit saves only the README change; the lettuce waits for its own commit.

git add -p is also a good review: you read every change before it’s committed. Many people use it instead of git add all the time.

Writing the message

Pro Git’s guidelines, adapted from a widely used template ¹:

• A summary line of about 50 characters or fewer, capitalized, with no period.
• Written in the imperative: “Fix bug,” not “Fixed bug” or “Fixes bug.” That matches the messages git itself writes, like “Merge branch…” and “Revert…”.
• A blank line, then, if it’s needed, a body wrapped at about 72 characters, saying what changed and why. Bullet points are fine.

Describe the beds in the README

Four raised beds on the south side, so the plan says where each crop
goes before we dig. Sizes come from the lumber list.

- beds are 4 x 8 feet
- paths are 3 feet wide

For a message with a body, leave off -m: git commit opens your editor with the staged changes listed as comments at the bottom, a last chance to check. A good test of the summary: does it finish the sentence “If applied, this commit will…”?

Checking before you commit

Before committing, two quick checks ¹:

me@linuxbox:~/garden$ git diff --staged          # exactly what will be committed
me@linuxbox:~/garden$ git diff --staged --check   # trailing spaces and other whitespace errors

--check flags stray spaces at line ends and similar problems that make later diffs noisy; plain git diff --check checks your unstaged changes instead ¹.

Moving and deleting files

To delete a tracked file, git rm file removes it and stages the removal in one step. To rename or move one, git mv old new ¹:

me@linuxbox:~/garden$ git mv fence.txt fence-plan.txt
me@linuxbox:~/garden$ git status -s
R  fence.txt -> fence-plan.txt

Git doesn’t actually record renames; it notices them, because the new file’s contents match the old one’s. So deleting and adding by hand works too, but git mv is one step instead of three ¹.

Your turn

So

Commit one logical change at a time, using git add -p to stage exactly the hunks that belong together. Write a short, capitalized, imperative summary line, a blank line, and a body that explains why. Check with git diff --staged and git diff --check, and use git mv and git rm for renames and deletions.