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 of | Write |
|---|---|
fix | Fix login timeout on slow mobile networks |
changes | Move session storage from memory to Redis |
wip | (squash it before merging, lesson 6) |
Updated server.js | Log the listening port at startup |
Fixed the bug Bruno found | Reject 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
| Type | Use for |
|---|---|
feat | A new feature for users |
fix | A bug fix |
docs | Documentation only |
refactor | Code change that neither fixes a bug nor adds a feature |
perf | A performance improvement |
test | Adding or fixing tests |
build / ci | Build system, dependencies, pipelines |
chore | Maintenance 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:
| Trailer | Meaning |
|---|---|
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 #142 | Close the issue when the commit reaches the default branch |
Reviewed-by: Name <email> | Record who reviewed the change |
Refs: ORB-142 | Link 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 -iwithreword(lesson 6), orgit 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
| Task | Command |
|---|---|
| Commit with editor for subject and body | git commit |
| Commit with subject and body from the CLI | git commit -m "Subject" -m "Body paragraph" |
| Add a Signed-off-by trailer | git commit -s |
| Add any trailer | git commit --trailer "Key: value" |
| Fix the last message | git commit --amend |
| Reword an older commit (2.54) | git history reword <commit> |
| Sign with SSH | gpg.format ssh, user.signingkey, commit.gpgsign true |
| Check signatures | git log --show-signature |
Exercise
Which subject line follows the conventions in this lesson best?
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?
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?
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-byandFixesadd structured information;--traileradds 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.