romulooliveira/commit-messages-guide

★ 6,764Audience · developerComplexity · 1/5Setup · easy

Mindmap

mindmap
  root((Commit Guide))
    Why it matters
      Faster code review
      Debug history
      Understanding decisions
    Writing rules
      Imperative subject
      Under 50 chars
      Body explains why
      One language only
    What not to write
      Fix stuff
      Vague messages
    Resources
      18 languages
      Message template

mindmap root((Commit Guide)) Why it matters Faster code review Debug history Understanding decisions Writing rules Imperative subject Under 50 chars Body explains why One language only What not to write Fix stuff Vague messages Resources 18 languages Message template

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Learn the rules for writing clear, consistent Git commit messages that help teammates review code faster.

USE CASE 2

Copy the commit message template from the guide as a starting point for your project's Git configuration.

USE CASE 3

Share the guide with new team members to align everyone on commit message conventions from day one.

Getting it running

Difficulty · easy Time to first run · 5min

Community contributions are accepted via pull requests, no software license applies, this is a documentation-only repository.

In plain English

This repository is a written guide explaining what commit messages are, why they matter, and how to write them well. A commit message is the short note a developer attaches every time they save a change to a codebase using a version control tool like Git. Over time, these messages form a record of what changed and why. The guide starts with a plain-English explanation of what a commit actually is: a snapshot of all your files at a given moment, not just a list of differences. It then makes the case for why the wording of those messages matters: well-written messages help other people review code faster, help future developers understand why a decision was made, and make debugging easier months or years later. The bulk of the content is a set of practical writing rules. These include: write the subject line in the imperative form ("Add feature" rather than "Added feature"), capitalize the first word, keep the subject line under fifty characters, use the message body to explain the reasoning rather than restating what the code already shows, and avoid vague notes like "Fix stuff" or "Adjust CSS." The guide also covers consistency: picking one language and sticking to it across a whole project. A commit message template from a widely read Git book is included as a ready-to-copy starting point. The guide is available in eighteen languages, with translations linked from the top of the README. Contributions from the community are accepted through pull requests. The repository contains no software to run, only the written guide in multiple languages, making it a reference document rather than a tool.

Copy-paste prompts

Prompt 1

Review my Git commit messages and tell me which ones break the rules from commit-messages-guide: [paste your git log output here].

Prompt 2

I'm setting up a new project. Generate a .gitmessage template file based on the best practices in romulooliveira/commit-messages-guide.

Prompt 3

Write a short onboarding document for my team explaining our commit message conventions, based on the writing rules in commit-messages-guide.

Open on GitHub → Explain another repo

← romulooliveira on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.