Git commit best practices

Below are some best practices for writing good commit messages. Try to follow the simpler rules from the start, so you don’t have to relearn later on!

Basic rule: Length

Keep it short — 50 characters or fewer.

Good:

git commit -m "Add salt before the password is hashed"

Avoid:

git commit -m "Add a salt (makes it harder to make rainbow table attacks) before passwords are being hashed"

Basic rule: Format

Capitalized first letter, a well-formed sentence, no trailing period.

Good:

git commit -m "Add salt before the password is hashed"
git commit -m "Fix bug where the password is truncated"
git commit -m "Add documentation for hashPassword"
git commit -m "Fix linting errors"

Avoid:

git commit -m "add salt before passwords are hashed."

Basic rule: Language

Write commit messages in English — it’s the standard language of the IT industry.

Basic rule: Tense

Write commit messages in the imperative mood — as an instruction, much like “Open the book.” or “Write a note.” The message should always be able to complete the following sentence:

This commit will…

Good:

git commit -m "Add salt before the password is hashed"
git commit -m "Fix bug where the password is truncated"
git commit -m "Add documentation for hashPassword"
git commit -m "Fix linting errors"

Avoid:

git commit -m "Adds salt before the password is hashed"
git commit -m "Fixing bug where the password is truncated"
git commit -m "Added documentation for hashPassword"
git commit -m "Fixed some linting errors"
git commit -m "Adding salt before the password is hashed"

Basic rule: Frequency

Try to commit as often as possible. Over time, you and your team will find a suitable frequency, but in the beginning, more often is better. Some rules of thumb to start with:

• Don’t commit based on time (for example, every ten minutes).
• Commit when you have completed a well-defined piece (e.g. a working function/method).
• If you find it hard to describe the change in a single message, you have probably changed too much since the last commit.
• Have three bugs to fix? That’s probably three separate commits.

Going further: Add a description

A commit can have both a short summary line and a longer description explaining why the change was made. Add a second -m flag to give the commit an extended description:

git commit -m "Add salt before the password is hashed" -m "Prevents rainbow table attacks against stored password hashes"

Going further: Reference issues

You can reference an issue number in the commit message to connect the change to the issue in GitLab:

git commit -m "Add salt before the password. Refs #12"

Going further: Close issues automatically

When a commit completes an issue, you can reference it with keywords such as “Fixes” or “Closes” in the commit message. GitLab then closes the issue automatically:

git commit -m "Add salt before the password. Closes #12"

Read more: Closing issues automatically (GitLab Docs).

Going further: Study other projects

A good way to learn is to look at how experienced developers do it. Browse well-known open source projects on GitHub to get a feel for how commit messages are written in practice:

• GitHub: Angular (Google)
• GitHub: VSCode (Microsoft)
• GitHub: React Native (Meta)

You will see that some break the rules above — don’t become one of them.

Going further: Let AI suggest a commit message

An AI assistant can turn a staged change into a commit message that follows the rules above — but only if it can actually see what you have changed. Two ways to meet that requirement:

• GitHub Copilot in VS Code: open the Source Control panel (Ctrl+Shift+G / Cmd+Shift+G) and click the sparkle icon above the message box. Copilot then reads your staged diff automatically and suggests a message — no extra steps needed beyond having Copilot installed.
• Chat-based assistant (Claude, ChatGPT, and others): copy the output of git diff --staged and paste it into the chat together with an instruction to write a short, imperative commit message in English following the rules above.

Read through the suggestion

The AI assistant only knows what changed, not why. Always read through the suggestion and adjust it so that it matches your actual intent with the change.

Sources and further reading

• “A Note About Git Commit Messages” by Tbaggery
• “How to Write a Git Commit Message”