Committing and good messages

Why this matters

A commit is the unit of history: what gets reviewed, reverted, blamed, cherry-picked and read. Good commits are small and say why. Bad commits are "fix" and "wip" and contain three unrelated things. The mechanics take a minute; the discipline is what makes you pleasant to work with.

The command

$ git commit -m "docs: describe the region and answer a data question (#28)"

[main dcc61f1] docs: describe the region and answer a data question (#28)
 2 files changed, 5 insertions(+), 1 deletion(-)

The output: the branch, the new commit's short hash, the message, and a summary of what was recorded. Only staged changes went in. git status is clean afterwards (unless you left things unstaged), and git log --oneline -1 shows the commit.

Without -m, Git opens your editor (lesson 3.3) with a template; write the message, save, close. Saving an empty message cancels the commit.

What a good message looks like

docs: add Windows steps to installation guide (#12)

• Subject line, about 50 characters, no trailing period. It appears in git log --oneline, in merge requests, in release notes.
• Imperative mood: "add", "fix", "remove", as if completing "this commit will…". Not "added", not "adding".
• A type prefix if the team uses one (the playground's CONTRIBUTING does): feat, fix, docs, chore, test, refactor. This is the Conventional Commits style.
• The issue number in parentheses or at the end, so GitLab and GitHub link it.

When the subject cannot explain why, add a body: a blank line, then prose. On the command line, a second -m starts the body:

$ git commit -m "feat: add Eagle Ridge trail (#21)" -m "Requested by the North region office. Distance measured on 2026-09-01."
$ git log -1

commit 79c86c54a1eacac536b48ab0a0ff614ea6908f1a
Author: Ana <ana@northwind-trails.example>
Date:   Mon Sep 7 09:30:00 2026 +0200

    feat: add Eagle Ridge trail (#21)
    
    Requested by the North region office. Distance measured on 2026-09-01.

The body is where you put context nobody can recover later: what was tried, why this way, which discussion decided it. The diff shows what; the message shows why.

Small commits

One commit per logical change: the typo fix and the new section are two commits, even if you made them in the same hour. Reasons you will feel quickly:

• Reviewers read a commit at a time; small ones get approved.
• git revert undoes one commit; you cannot revert half of one.
• git log -- file and git blame tell a clearer story.

If you edited more than one thing before committing, lesson 5.3 shows how to stage them separately.

The -a shortcut

git commit -a stages every modified or deleted tracked file and commits in one step. It never includes new (untracked) files:

$ git commit -am "docs: add maintainer note"

[main c541c80] docs: add maintainer note
 1 file changed, 2 insertions(+)

Convenient when you changed exactly the files you meant; risky when you did not. git status first, as always.

Fixing the last commit: --amend

Forgot a file, or typed a wrong message? Amend replaces the last commit with a corrected one:

$ git add docs/faq.md
$ git commit --amend --no-edit

--no-edit keeps the message; without it the editor opens so you can change it, or use -m:

$ git commit --amend -m "feat: add Coast Walk trail and FAQ entry (#29)"

Amend rewrites the commit (new hash), so it follows the rule of lesson 2.7: only before pushing. After a push, make a new commit instead.

In the tools

Common mistakes

• "Nothing to commit" after editing. Nothing was staged. git add first (lesson 5.3).
• A giant editor window appeared. You omitted -m. Write the message and close, or close without saving to abort, then retry with -m.
• Amending after pushing. Diverged branches and a rejected push. Add a new commit instead.
• Committing -a with a stray change in another file. Read git status before -a.
• Writing the message for yourself now instead of the reader later. "fix" means nothing in a month.