Good Commit Messages
Clear, consistent commit messages make history easy to read and search.
A good commit message explains why a change was made, not just what changed. A widely used format has a short summary line, a blank line, then an optional body.
Guidelines
- Keep the summary under about 50 characters.
- Use the imperative mood: “Add”, “Fix”, “Remove”.
- Leave a blank line before the body.
- Explain the reasoning in the body when it is not obvious.
Conventional Commits
Many teams prefix messages with a type: feat:, fix:, docs:, chore:. This enables automated changelogs and version bumps.
Example
git commit -m "feat: add password strength meter" -m "
Warn users about weak passwords before they submit the
sign-up form. Closes #128."When to use it
- A team adopts Conventional Commits so tools like semantic-release can automatically generate changelogs and determine the next version number.
- A developer writes a detailed commit body explaining why a complex algorithm was chosen, helping future reviewers understand the decision without asking.
- A CI linter (commitlint) rejects commits that don't follow the team's message format, enforcing consistency across all contributors.
More examples
Well-formed Conventional Commit
A subject line with type and scope, a blank line, a body explaining the why, and a footer closing an issue — the ideal commit message structure.
git commit -m "feat(auth): add OAuth2 login with Google
Allows users to sign in with their Google account using
the Authorization Code flow. Adds refresh-token rotation
to prevent session hijacking.
Closes #112"Install commitlint to enforce format
Installs commitlint with conventional config and wires it to a Husky pre-commit hook so badly formatted messages are rejected at commit time.
npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
# Add to .husky/commit-msg
npx husky add .husky/commit-msg 'npx commitlint --edit $1'Use commit template for consistency
A global commit template pre-populates the message editor with the required structure, guiding developers to fill in each section.
cat ~/.gitmessage
# type(scope): short summary (max 72 chars)
#
# Why this change is needed:
#
# Related issue:
git config --global commit.template ~/.gitmessage
Discussion