Git Commit Guidelines

Git Commit Guidelines

Best practices for writing clear, consistent git commit messages.

When to Apply

Reference these guidelines when:

• Writing commit messages
• Reviewing pull requests for commit quality
• Setting up commit conventions for a new project

Rules

Quick Reference

Structure

Every commit message should have a short subject line. For non-trivial changes, follow with a blank line and a body that explains context.

Subject Line

• Use imperative mood: "Add feature" not "Added feature"
• Keep under 72 characters
• Capitalize the first word
• Do not end with a period

Body

• Wrap at 72 characters
• Explain what changed and why, not how
• Reference issue numbers when applicable

Scope

• Each commit should represent one logical change
• Separate refactoring from behavior changes
• Separate whitespace/formatting fixes from functional changes

body — Explain what and why, not how

Why it matters

The code diff shows how something changed. The commit body should capture the motivation and context that the diff cannot convey.

Incorrect

Refactor auth module

Changed the if-else to a switch statement and moved the helper
function from line 45 to line 12.

Describes the mechanical changes that are already visible in the diff.

Correct

Refactor auth module for readability

The nested conditionals made it difficult to add new auth providers.
Restructured to a dispatch pattern so each provider is independent.

Explains the reasoning behind the change.

scope — One logical change per commit

Why it matters

Atomic commits make git bisect, revert, and cherry-pick reliable. Mixed commits are harder to review and harder to undo.

Incorrect

One commit that:

• Fixes a typo in the README
• Adds a new API endpoint
• Reformats whitespace in three files

Correct

Three separate commits:

Fix typo in README

Add /api/users/:id/preferences endpoint

Format whitespace in auth module

Each commit is independently revertible and reviewable.

structure — Use subject + blank line + body format

Why it matters

A well-structured commit message is easy to scan in git log --oneline while still providing detail when needed.

Incorrect

Fixed the login bug where users couldn't sign in because the session token was expired and the refresh logic wasn't being triggered properly due to a race condition in the auth middleware

Long single-line message that's hard to scan and wraps poorly.

Correct

Fix session refresh race condition in auth middleware

The refresh token logic was not triggered when concurrent requests
arrived before the initial refresh completed. Added a mutex to
serialize refresh attempts.

Fixes #342

Clear subject for scanning, detailed body for context.

subject-line — Keep subject under 72 chars, imperative mood, no period

Why it matters

Short imperative subjects work well with git tooling (log --oneline, rebase -i, merge commits) and read naturally as instructions.

Incorrect

added new validation to the user registration form.

Past tense, lowercase start, trailing period.

Correct

Add validation to user registration form

Imperative mood, capitalized, no trailing period, under 72 characters.