DEV Community

Favor Charles Owuor
Favor Charles Owuor

Posted on

Git Commit Messages

#git #productivity

commits

A well-written commit message is one of the most underrated skills in software development. It turns a chaotic git history into a readable, searchable record of every decision you have ever made. This will guide in writing structured.

Step 1: Understand the Standard Structure

The industry standard is the Conventional Commits specification, paired with the 50/72 length rule. Together they make your history easy to read for humans and easy to parse for automated tools.

A complete commit message follows this template:

<type>(<optional scope>): <short description in imperative mood>

[optional body — explains the what and why behind the change]

[optional footer — references issue trackers or declares breaking changes]
Enter fullscreen mode Exit fullscreen mode

Here is a real example:

feat(auth): add multi-factor authentication check

Introduce an intermediate step in the login pipeline to check for a
valid TOTP token. This protects user accounts against credential stuffing.

Closes JIRA-8422
Enter fullscreen mode Exit fullscreen mode

Step 2: Know the Parts of a Commit Message

Type A lowercase prefix that categorizes the nature of your change (e.g., feat, fix, docs).

Scope (optional) A modifier in parentheses that gives context on which part of the codebase is affected (e.g., auth, api, ui).

Description A short summary of what the commit accomplishes — written as a command, not a past-tense statement.

Body (optional) Extended paragraphs explaining the problem being solved and the motivation behind your fix. Focus on why, not how.

Footer (optional) Metadata used to reference issue IDs (e.g., Closes JIRA-8422) or declare breaking changes.

Step 3: Learn the Core Formatting Rules

For the subject line

  • Keep it under 50 characters for optimal display in GitHub and terminal interfaces.
  • Use the imperative mood — write it as a command (use add not added or adding).
  • Drop the trailing period — never end your subject line with a full stop.
  • Keep the type lowercase — feat: not Feat: or FEAT:.

For the body

  • Leave one blank line between the subject and the body.
  • Wrap lines at 72 characters to avoid truncation in terminal windows.
  • Explain why, not how — the code shows how; the message should explain why the old state was a problem.

Step 4: Learn the Standard Commit Types

You don't need to memorize all of these on day one, but this is the full reference:

Type When to use it
feat Introduces a brand-new feature
fix Corrects a bug or unintended behavior
refactor Restructures code without changing its behavior
chore Routine maintenance, config tweaks, or package updates
docs Changes made exclusively to documentation or markdown files
style Formatting or whitespace adjustments that leave logic unchanged
test Adding missing tests or repairing broken test suites
perf Performance optimizations designed to increase speed or efficiency

Step 5: Start Small — Master Three Types First

Don't try to memorize all eight types immediately. For your first few weeks, use only these three:

  • feat: — when you add something new (e.g., feat: add submit button)
  • fix: — when you repair something broken (e.g., fix: correct broken nav link)
  • docs: — when you write or update documentation (e.g., docs: update setup guide)

Once these feel automatic, layer in the others one at a time.

Step 6: Use the Imperative Mood Test

Write your subject line so it logically completes this sentence:

"If applied, this commit will [your message]."

  • Correct: feat: add login page → "If applied, this commit will add login page."
  • Incorrect: feat: added login page or feat: adding login page

If it doesn't complete that sentence naturally, rewrite it.

Step 7: Commit Small and Often

The hardest habit for beginners to build is committing frequently. The rule is simple: make one commit for every one completed task.

  • Don't write code for three hours and then commit fix: everything.
  • Do commit every time you finish a single small task — one component, one bug fix, one style correction.

Small commits are easier to review, easier to revert, and tell a much clearer story to your team.

Step 8: Automate the Rules With Commitizen

Once you want to enforce the format consistently, use Commitizen — a command-line tool that guides you through writing a conventional commit with interactive prompts. You can run it immediately with npx without any complex setup:

npx commitizen init cz-conventional-changelog --save-dev --save-exact
Enter fullscreen mode Exit fullscreen mode

From then on, instead of writing git commit -m "...", run git cz and answer the prompts. The tool assembles the correctly formatted message for you.

Conclusion: Build the Habit Now

Mastering commit messages is about transitioning from a messy, hard-to-read history to a structured, predictable one that your whole team can rely on.

Three things to take away:

  • Consistency trumps perfection. It matters less which exact types you use and more that you and your team use the same format every single time.
  • Keep it short and purposeful. Under 50 characters for the title, imperative mood, and use the body to explain the why.
  • Start small, then automate. Begin with just feat, fix, and docs. Commit frequently. Then bring in Commitizen to handle the formatting automatically.

The best time to start writing better commit messages is on your very next commit.

Top comments (0)