Lesson 17 beginner

Git Commit Messages

Write commit messages people can use: the subject and body format, the imperative mood, explaining why, Conventional Commits for changelogs and versioning, trailers like Co-authored-by and Signed-off-by, linking issues, and signing commits with SSH keys so they show as verified.

A commit message is a note to the person who reads the history later, often you, six months from now, in the middle of an incident. git log, git blame, git bisect, changelogs and release notes are only as useful as the messages behind them. Good messages cost one extra minute per commit and save hours.

Bad messages, good messages

Instead ofWrite
fixFix login timeout on slow mobile networks
changesMove session storage from memory to Redis
wip(squash it before merging, lesson 6)
Updated server.jsLog the listening port at startup
Fixed the bug Bruno foundReject empty note titles with HTTP 400

The good versions say what the commit does in a way that makes sense without opening the diff, and without knowing the conversation that led to it.

The shape of a message

Raise login timeout to 30 seconds

Mobile users on slow networks hit the 10 second limit during peak
hours, and the client then retried, doubling the load on the auth
service. 30 seconds covers the 99th percentile measured last week.

The value is now read from LOGIN_TIMEOUT so it can be tuned without
a release.

Fixes: ORB-142
  • Subject line: about 50 characters, at most 72. Capitalised, no full stop at the end. Many tools only show this line.
  • Blank line between subject and body. Git and every tool rely on it.
  • Body: wrapped at about 72 characters. Explain why the change was needed and anything surprising about how. The diff already shows what changed line by line.
  • Trailers at the end, such as issue references and co-authors.

git commit -m is fine for a commit whose subject says everything. For anything else, run git commit and write the message in your editor, or pass several -m options, one per paragraph.

Use the imperative mood

Write the subject as a command: “Add”, “Fix”, “Remove”, not “Added” or “Fixes”. A good test is to complete the sentence “If applied, this commit will…”:

  • If applied, this commit will raise login timeout to 30 seconds. Correct.
  • If applied, this commit will raised login timeout. Wrong.

It also matches the messages Git writes itself, like Merge branch 'feature/search' and Revert "Enable experimental cache".

Conventional Commits

Many teams use the Conventional Commits format, which adds a type, and optionally a scope, in front of the subject:

type(scope): summary
TypeUse for
featA new feature for users
fixA bug fix
docsDocumentation only
refactorCode change that neither fixes a bug nor adds a feature
perfA performance improvement
testAdding or fixing tests
build / ciBuild system, dependencies, pipelines
choreMaintenance that does not touch the product
feat(search): rank results by note date
fix(api): return 400 for empty note titles
ci: cache node_modules between pipeline jobs
feat(api)!: remove the deprecated v1 notes endpoint

The ! marks a breaking change, as does a BREAKING CHANGE: trailer in the body. Because the types are machine-readable, tools such as semantic-release or release-please can generate the changelog and decide the next version automatically: fix bumps the patch, feat the minor and a breaking change the major (lesson 10). A commit-msg hook or commitlint in CI enforces the format (lesson 13).

Trailers

Trailers are Key: value lines at the end of the message. Git and hosting services understand several of them:

TrailerMeaning
Co-authored-by: Name <email>Credit a pair or mob programming partner; GitHub shows both avatars
Signed-off-by: Name <email>Developer Certificate of Origin, required by projects like the Linux kernel; added by git commit -s
Fixes: #142 or Closes #142Close the issue when the commit reaches the default branch
Reviewed-by: Name <email>Record who reviewed the change
Refs: ORB-142Link a ticket without closing it

You can add trailers from the command line instead of typing them:

$ git commit -s -m "Fix empty title handling" --trailer "Co-authored-by: Bruno Lima <bruno@orbit.dev>"
$ git log -1 --format="%(trailers)"
Signed-off-by: Ana Souza <ana@orbit.dev>
Co-authored-by: Bruno Lima <bruno@orbit.dev>

Since Git 2.54, git rebase --trailer can add a trailer to every commit of a branch at once, for example a Reviewed-by line after review.

Fixing a message

  • Last commit, not pushed: git commit --amend.
  • Older commit, not pushed: git rebase -i with reword (lesson 6), or git history reword <commit> on Git 2.54 and later (lesson 9).
  • Already pushed and shared: leave it. A slightly awkward message is better than rewriting history under your teammates.

Signing commits

Anyone can set user.name to any name, so the author line proves nothing. A signed commit carries a cryptographic signature that GitHub and GitLab verify against the key on your account and show as Verified. Git can sign with the SSH key you already use to push:

$ git config set --global gpg.format ssh
$ git config set --global user.signingkey ~/.ssh/id_ed25519.pub
$ git config set --global commit.gpgsign true
$ git config set --global tag.gpgsign true

Then upload the same public key to your hosting account as a signing key (GitHub lists authentication and signing keys separately). To verify signatures locally, list trusted keys in an allowed signers file:

$ echo "ana@orbit.dev $(cat ~/.ssh/id_ed25519.pub)" >> ~/.config/git/allowed_signers
$ git config set --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
$ git log --show-signature -1
Good "git" signature for ana@orbit.dev with ED25519 key SHA256:...

Branch protection can then require signed commits on main. GPG keys and X.509 certificates (gpg.format x509, used with gitsign) also work; SSH is simply the easiest to set up.

Quick reference

TaskCommand
Commit with editor for subject and bodygit commit
Commit with subject and body from the CLIgit commit -m "Subject" -m "Body paragraph"
Add a Signed-off-by trailergit commit -s
Add any trailergit commit --trailer "Key: value"
Fix the last messagegit commit --amend
Reword an older commit (2.54)git history reword <commit>
Sign with SSHgpg.format ssh, user.signingkey, commit.gpgsign true
Check signaturesgit log --show-signature

Exercise

Which subject line follows the conventions in this lesson best?

  1. Return 400 for empty note titles
  2. fixed stuff in the API.
  3. Updated server.js and routes.js
  4. FIX: THE BUG FROM YESTERDAY
Show answer

Answer: A. It uses the imperative mood, says what the commit does without needing the diff, stays short and has no trailing period. The others are vague, describe files instead of behaviour, or need outside context.

Exercise

Using Conventional Commits, which message tells release tooling to publish a new major version?

  1. feat(search): rank results by date
  2. fix(api): handle empty titles
  3. chore: update dependencies
  4. feat(api)!: remove the v1 notes endpoint
Show answer

Answer: D. The ! after the type and scope marks a breaking change, which bumps the major version. feat bumps the minor version, fix the patch, and chore does not trigger a release.

Exercise

Your team wants commits on main to prove who created them. What should each developer set up?

  1. Set user.name and user.email correctly
  2. Commit signing, for example gpg.format ssh with user.signingkey and commit.gpgsign true, plus the key on their account
  3. Add a Signed-off-by trailer with git commit -s
  4. A commit-msg hook that checks the author email
Show answer

Answer: B. Name, email and trailers are plain text anyone can type. A cryptographic signature, verified against the key on the developer’s account, is what proves authorship and lets branch protection require it.

Key takeaways

  • Subject of about 50 characters in the imperative mood, a blank line, then a body explaining why.
  • Test the subject with “If applied, this commit will…”.
  • Conventional Commits (type(scope): summary, ! for breaking) enable automatic changelogs and versions.
  • Trailers such as Co-authored-by, Signed-off-by and Fixes add structured information; --trailer adds them for you.
  • Sign commits with your SSH key so hosting services show them as verified.

FAQ

How long should a commit message be?

As long as it needs to be. A typo fix needs one line. A change to how authentication works deserves a paragraph explaining the reason and the trade-offs. The subject stays short either way.

Do I have to use Conventional Commits?

No. It is a convention, useful when you want automated changelogs and version numbers. A team that does not need those can simply follow the subject and body rules. What matters is that the whole repository uses one style.

Should the message mention the ticket number?

Yes, in a trailer or the body, so the history links to the discussion. Do not rely on it alone: tickets get moved or deleted, so the message itself should still explain the change.

What is the difference between Signed-off-by and a signed commit?

Signed-off-by is a line of text saying you agree to the project’s contribution terms, the Developer Certificate of Origin. A signed commit carries a cryptographic signature proving which key created it. They are unrelated, despite the similar names.

Can I make Git show my message template every time?

Yes. Write a template file with reminder comments and set commit.template to its path. Git opens the editor with it, and lines starting with # are removed from the final message.

↑ ↓ navigate Enter open Esc close