Crafting Excellent Git Commit Messages: Best Practices for Clear History

Git commit messages are the notes your team depends on when code breaks, behavior changes, or a release needs explaining. A clear message tells you what changed and why without forcing you to reverse-engineer the diff.

Good commit messages do not need to be fancy. They need a useful subject line, enough context for non-trivial changes, and a consistent style your team can read months later.

Why Are Good Commit Messages Important?

Good commit messages help in several practical ways:

Understanding Changes: They provide immediate context for what a specific commit introduces or modifies, saving time when reviewing code or recalling past decisions.
Debugging: When tracking down bugs, a clear commit history allows you to pinpoint exactly when and why a problematic change was introduced.
Collaboration: For team members joining a project or revisiting old code, well-written messages make it easier to understand the project's development trajectory.
Code Reviews: They offer reviewers insight into the intent behind the changes, facilitating more productive and focused feedback.
Automated Tools: Many Git tools, such as changelog generators and release note creators, rely on commit messages to function effectively.
Historical Record: They serve as a form of documentation, preserving the evolution of the codebase over time.

The Anatomy of an Excellent Git Commit Message

A universally recognized structure for Git commit messages follows a simple, yet powerful, pattern: a concise subject line followed by an optional, more detailed body.

The Subject Line

The subject line is the first line of your commit message. It should be a brief, imperative summary of the changes. Think of it as a title for the commit.

Key Guidelines for the Subject Line:

Keep it concise: Around 50 characters is a useful target, not a hard limit. Keep the subject short enough to scan in git log --oneline.
Use the imperative mood: Start with a verb that describes the action, as if you were issuing a command. Examples: Fix, Add, Refactor, Update, Remove, Style.
Capitalize the first word: Standard convention dictates capitalizing the first letter of the subject line.
Do not end with a period: The subject line is a title, not a sentence.
Avoid using git commit -m "message" for longer messages: While convenient for short notes, it can lead to less structured messages. Use git commit without arguments to open your editor for more complex messages.

Examples of Good Subject Lines:

feat: add user authentication module
fix: resolve infinite loop in data processing
docs: update README installation steps
refactor: simplify image loading
chore: update development dependencies

The Body

The body of the commit message is where you provide more context and detail. It's separated from the subject line by a blank line. This section is optional but highly recommended for anything beyond trivial changes.

Key Guidelines for the Body:

Explain the 'why' and 'how': Don't just describe what changed; explain why the change was necessary and how it was implemented. What problem does this commit solve? What was the previous behavior? What is the new behavior?
Wrap lines at 72 characters: This is a long-standing convention that improves readability in many Git tools and terminals.
Use bullet points for lists: If you need to enumerate multiple changes or points, use bullet points for clarity.
Reference issues or tickets: If the commit relates to an issue tracker (e.g., GitHub Issues, Jira), include the ticket number for traceability.

Example of a Good Commit Message (Subject + Body):

feat: implement user profile page

This commit introduces the user profile page, allowing users to view and
edit their personal information.

Previously, users could not access or modify their profile details.
This change adds a new route (`/profile`) and a corresponding
component that fetches user data from the API and provides
forms for updating fields like name, email, and bio.

Related to #123.

Common Commit Message Types (Conventional Commits)

Following a convention for commit message types can further enhance clarity and enable automated tooling. The Conventional Commits specification is a popular standard that promotes a structured approach.

Conventional Commits use a prefix to denote the type of change:

feat (feature): A new feature is introduced to the codebase.
fix (bug fix): A bug is resolved.
docs (documentation): Changes to documentation only.
style (formatting): Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.).
refactor (refactoring code): A code change that neither fixes a bug nor adds a feature.
perf (performance): A code change that improves performance.
test (adding missing tests or correcting existing tests): Adding or correcting tests.
build (changes that affect the build system or external dependencies): Examples are npm scripts, webpack, etc.
ci (changes to our CI configuration files and scripts): Examples are Travis, Circle, BrowserStack, SauceLabs, etc.
chore (maintenance work): Tasks that do not fit the other types, such as repository housekeeping.

Scope (Optional): A scope can be added to the prefix to indicate the part of the codebase affected. For example: feat(auth): Add JWT authentication.

Footer (Optional): Use the footer to reference issues, mark breaking changes, or add other metadata. Conventional Commits uses BREAKING CHANGE: for breaking changes.

Example using Conventional Commits:

fix(api): correct endpoint for user data retrieval

Previously, the `/users/:id/data` endpoint returned outdated information.
This commit updates the endpoint to `/users/:id/profile` which fetches
the most current user profile data.

Closes #456

Tips for Writing Great Commit Messages

Commit often, but logically: Make small, atomic commits that represent a single logical change. This makes messages easier to write and understand.
Write messages from the perspective of the project's future self: Imagine you are looking back at this commit in six months. What information would you need to understand the change quickly?
Be specific: Avoid vague messages like "Update code" or "Bug fixes." Explain precisely what was updated or fixed.
Use backticks for code references: If you mention filenames, functions, or variable names, enclose them in backticks (`).
Review your messages: Before committing, take a moment to read your message. Does it make sense? Is it clear?

Takeaway

Write each commit message for the person who will read it during a review, rollback, or incident. Use a short imperative subject, add a body when the reason is not obvious, and keep each commit focused on one logical change.