Staging Changes and Writing Good Commits
Choose exactly what goes into each commit, read the two kinds of diff, and write messages your future self will thank you for.
In this lesson you will
- Stage some changes and leave others
- Read git status -s and both kinds of diff
- Unstage a change safely
- Write a short, clear commit message
About 28 minutes
Two changes, one tidy history
Nia has been busy. She added carrots to the planting plan and a Tuesday volunteer to the watering rota. These are two unrelated changes, and she would like two separate commits, so that a year from now the history says exactly what happened and when. If she saved everything in one go, the log would read “Update stuff”, which helps nobody. The staging area from the last lesson is what makes tidy commits possible.
Choosing what goes in
The session below starts with two changed files. Nia stages only the plan with git add plan.txt, then asks Git to show her the difference between the three places. Look at the two-letter codes printed by git status -s. The left letter describes the staging area, and the right letter describes the working folder. M means modified. So M plan.txt is “modified and staged”, while M rota.txt is “modified but not staged”.
$ mkdir garden
$ cd garden
$ git init
Initialized empty Git repository in /home/nia/garden/.git/
$ echo "Beans: row 1" > plan.txt
$ echo "Mon: Nia" > rota.txt
$ git add plan.txt rota.txt
$ git commit -m "Add plan and rota"
[main (root-commit) a43202a] Add plan and rota
2 files changed, 2 insertions(+)
create mode 100644 plan.txt
create mode 100644 rota.txt
$ echo "Carrots: row 2" >> plan.txt
$ echo "Tue: Dev" >> rota.txt
$ git status -s
M plan.txt
M rota.txt
$ git add plan.txt
$ git status -s
M plan.txt
M rota.txt
$ git diff
diff --git a/rota.txt b/rota.txt
index 024937f..93c4aae 100644
--- a/rota.txt
+++ b/rota.txt
@@ -1 +1,2 @@
Mon: Nia
+Tue: Dev
$ git diff --staged
diff --git a/plan.txt b/plan.txt
index d0f2908..a8ab217 100644
--- a/plan.txt
+++ b/plan.txt
@@ -1 +1,2 @@
Beans: row 1
+Carrots: row 2
Now compare the two diff commands. Plain git diff shows changes that are not yet staged, so it shows only the rota. The command git diff --staged shows what is staged, which is what the next commit will contain, so it shows only the carrots. A line starting with a plus sign was added, and a line starting with a minus sign was removed. Reading git diff --staged just before you commit is the best habit in this course, because it shows you exactly what you are about to save.
Committing one idea at a time
With the plan staged, Nia commits it, then stages and commits the rota. She also practises a safety step: she stages a Wednesday change by mistake, then takes it back out with git restore --staged. This does not touch the file. It only removes the change from the waiting room. Git introduced the restore command in version 2.23, and older guides use git reset for the same job. Both work.
$ git commit -m "Add carrots to the plan"
[main d4b81ec] Add carrots to the plan
1 file changed, 1 insertion(+)
$ git add rota.txt
$ git commit -m "Add Tuesday to the rota"
[main 7a6789e] Add Tuesday to the rota
1 file changed, 1 insertion(+)
$ echo "Wed: Asha" >> rota.txt
$ git add rota.txt
$ git status -s
M rota.txt
$ git restore --staged rota.txt
$ git status -s
M rota.txt
$ git add rota.txt
$ git commit -m "Add Wednesday to the rota"
[main 8b5275f] Add Wednesday to the rota
1 file changed, 1 insertion(+)
$ git log --oneline
8b5275f Add Wednesday to the rota
7a6789e Add Tuesday to the rota
d4b81ec Add carrots to the plan
a43202a Add plan and rota
The log now reads like a diary: four commits, each with a message that says what changed. Notice that each commit holds a single idea. That makes history easy to read, and it makes mistakes easy to undo, because you can reverse one idea without losing another.
Writing a good message
A commit message is a note to your future self and to your team. A widely used convention keeps it simple:
- Keep the first line short, about 50 characters, so it fits in one line of the log.
- Start with a capital letter and write a command: Add carrots, not Added carrots. A handy test is to finish the sentence “If applied, this commit will …”.
- Leave off the full stop at the end of the first line.
- Say something specific. Update stuff and wip tell the reader nothing.
- If the reason is not obvious, add a blank line and a few sentences of explanation below the first line.
To make this concrete, here is a small checker that applies those rules to eight sample messages. It is deliberately crude. For example, it would wrongly flag a good message that starts with a word such as Embed, because the word ends in the letters “ed”. A real team would use its own judgement, but the exercise shows how mechanical most of the rules are.
VAGUE = {"stuff", "update", "updates", "changes", "fix", "wip", "misc", "things", "work"}
def check(msg):
problems = []
words = msg.split()
first = words[0].lower()
if len(msg) > 50: problems.append("over 50 characters")
if msg.endswith("."): problems.append("ends with a full stop")
if not msg[0].isupper(): problems.append("no capital letter")
if first in VAGUE or len(words) < 2: problems.append("too vague")
if first.endswith("ed") or first.endswith("ing"): problems.append("not a command")
return problems
messages = [
"Add carrots to the plan",
"stuff",
"Fixed the watering rota.",
"Add Wednesday to the rota",
"Updating the plan again and again with every little thing I thought of today",
"Remove the old beans row",
"wip",
"Update stuff",
]
good = 0
for m in messages:
problems = check(m)
good += not problems
print(("ok " if not problems else "FLAG ") + m[:34] + ("" if not problems else " -> " + ", ".join(problems)))
print("passing:", good, "of", len(messages))
ok Add carrots to the plan
FLAG stuff -> no capital letter, too vague
FLAG Fixed the watering rota. -> ends with a full stop, not a command
ok Add Wednesday to the rota
FLAG Updating the plan again and again -> over 50 characters, not a command
ok Remove the old beans row
FLAG wip -> no capital letter, too vague
FLAG Update stuff -> too vague
passing: 3 of 8
Out of 8 messages, 3 passed and 5 were flagged, each with its reasons. Teams agree on a style like this so that the history stays useful for years.
Leaving off -m and the message. Git then opens a text editor, and a beginner can get stuck inside it. If that happens, write your message on the first line, save, and close the editor. In the vim editor, press Escape, then type :wq and press Enter.
The files and messages here are made up. The 50 character guideline is a convention, not a rule that Git enforces, and projects differ, so always follow the style of the team you work with.
git diff --staged before each commit. Then read your log and ask whether a stranger could follow it.
Practice for this lesson
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
What does git diff show on its own?
- Changes that are staged
- The whole history
- Changes that are not yet staged
- Files on GitHub
Plain git diff showed only the unstaged rota change.
Which command shows what the next commit will contain?
- git log
- git init
- git branch
- git diff –staged
It showed only the carrots, which were the staged change.
What does M in the left column of git status -s mean?
- Modified but not staged
- Modified and staged
- Merged
- Missing
The left letter describes the staging area.
Which message follows the common convention?
- Added carrots to the plan.
- stuff
- Add carrots to the plan
- wip
It is short, capitalised, a command, and has no full stop.
What does git restore –staged rota.txt do?
- Removes it from the staging area without changing the file
- Deletes the file
- Commits the file
- Uploads the file
The status went back to modified but not staged.
Summary
- The staging area lets one commit hold one idea.
- git diff shows unstaged changes; git diff –staged shows what the commit will contain.
- git restore –staged takes a change back out of the staging area.
- Good messages are short, specific commands without a full stop.
Questions
Is there a shortcut to stage everything?
Yes. git add . stages every change in the current folder, and git commit -a stages changes to files Git already tracks. They are quick, but they can sweep in files you did not mean to save, so check git status first.
Do I have to follow the 50 character rule?
No. Git does not enforce it. It is a convention that keeps logs readable, and teams often set their own style.
Can I change a message after committing?
You can change the very latest commit with git commit --amend, as long as you have not shared it. Lesson 10 shows this.
