Git and GitHubgit 2.54 · GitHub · macOS, Linux or Windows
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
26 small wins to finish your pathNext lesson →

Writing a commit message

A commit message is the text stored with a commit, and its job is to tell the next person who reads the history why the change was made.

Last updated: 12 Oct, 2026 · git 2.54

Git takes any message you give it, including update. The cost arrives later, when someone reads the history to find out when a value changed and why. That someone is often you, six months on.

The same three commits, written twice

These two repositories hold exactly the same changes. The only difference is what was typed after -m. Both start from the same two lines, an empty repository and one fixed date so the identifiers do not move from run to run:

bash
mkdir ask-docs && cd ask-docs && git init -q -b main
export GIT_AUTHOR_DATE="2026-10-12T10:00:00+00:00" GIT_COMMITTER_DATE="2026-10-12T10:00:00+00:00"
Project files used on this pageThis lesson builds on a project from earlier lessons. The code below imports this file. Click a file to see its code, or follow the link to the lesson that wrote it. To run the code yourself, keep it in the same folder.
View the code here
.gitconfig
[user]
	name = Reader
	email = reader@example.com
ExampleThree commits nobody can use
printf 'You are a support assistant.\n' > prompt.txt
git add . && git commit -q -m "update"
printf 'chunk_size = 500\n' > loader.py
git add . && git commit -q -m "fix"
printf 'chunk_size = 800\n' > loader.py
git commit -q -am "changes"
git log --oneline

update, fix and changes. To find out what any one of them did you have to open the commit and read its patch.

ExampleThe same three changes, described
printf 'You are a support assistant.\n' > prompt.txt
git add . && git commit -q -m "Add the first support prompt"
printf 'chunk_size = 500\n' > loader.py
git add . && git commit -q -m "Split documents into 500 character chunks"
git log --oneline

Two subjects a reader can use without opening anything. The third change is the one that moves a number, and its subject says which number and why.

ExampleThe third change, with the number in its subject
printf 'chunk_size = 800\n' > loader.py
git commit -q -am "Raise the chunk size to 800 for fewer, longer chunks"
git log --oneline
  • The described history answers without being opened. The chunk size went from 500 to 800, and the subject says what the change was for.
  • Both sets took the same ten seconds to type. The good subjects name the file's purpose instead of the fact that it changed.

The shape of a message

A message has a subject line and, when it needs one, a body. Git treats the first line as the subject: it is what git log --oneline prints, what GitHub shows in its list of commits, and what a reviewer sees first.

The shape of a commit message. The first line is the subject, written in the imperative and kept under about fifty characters, and it is the only part git log --oneline prints. A blank line follows it. Under that comes the body, wrapped at about seventy-two characters, which explains why the change was made.
  • Subject, one line, about fifty characters. Long enough to say what changed, short enough to read in a list.
  • Write it as an instruction: Add, Fix, Remove, Raise. Finish the sentence “this commit will ...”. Git's own generated messages, such as Merge branch 'main', are written that way.
  • No full stop at the end and no file name when the diff already shows it.
  • A blank line, then the body, wrapped at about seventy-two characters. Use it for why, for what you tried, for anything the diff cannot say. Small commits often need none.

Writing a body with two -m flags

Each -m becomes one paragraph, and Git puts the blank line between them. Running git commit with no -m opens your editor instead, which is easier for a long body.

ExampleA subject and a body, as git log prints them
printf 'chunk_size = 800\n' > loader.py
git add .
git commit -q -m "Raise the chunk size to 800" \
  -m "Answers were being cut in half at 500 characters. 800 keeps a whole
paragraph together and costs about 20 percent more tokens per question."
git log
  • git log indents the whole message under the header, subject and body together.
  • The body carries what the diff cannot: the reason for the number and what it costs.
ExampleThe same commit in the one-line form
git log --oneline

git log --oneline keeps the subject only, which is why the first line has to stand on its own.

What to put in a message, and what to leave out

Instead ofWriteBecause
updateAdd the first support prompta history of updates says nothing
fix bugStop the loader dropping the last chunkthe next reader wants the bug, not the word
changes to loader.pyRaise the chunk size to 800the diff already names the file
asdfany sentence at allthis one reaches GitHub too
one commit called workthree commits with three subjectsa commit should hold one change

Many teams add a prefix to the subject, such as fix: or feat:, a convention called Conventional Commits. It is a team agreement rather than a Git feature. Read the last ten subjects in a repository with git log --oneline and follow whatever it does.

Where the message is read

  • In a pull request. Reviewers read the subjects before the code and decide what to look at closely.
  • When something breaks. Finding the commit that changed a value is quick; understanding why it changed depends entirely on the message.
  • On your GitHub profile. A list of commits is public, and update forty times is what a reader sees.
Watch out. A commit message is stored inside the commit, so changing it later means rewriting that commit. The last one can be reworded with git commit --amend, which the undoing part covers, and anything older is harder and unsafe once the commits are shared. Write the message as if it is permanent, because it is.
Try it yourself
  • Commit with no -m, write a subject and a body in the editor, save, and read the result with git log.
  • Run git log --oneline in a repository you did not write and judge how much the subjects tell you.
  • Set git config --global commit.template ~/.gitmessage with a file holding your own reminders, and watch it appear in the editor.
PreviousSeeing what changed with git diff

Slow is fine. Stopping is the only problem.