Writing good commit messages in Git - Deep Dive

Overview - Writing good commit messages

What is it?

Writing good commit messages means creating clear, concise notes that explain what changes were made in a set of code updates. These messages help everyone understand why the change was done and what it affects. Good commit messages make it easier to track history, fix bugs, and collaborate with others. They are a key part of using git, a tool for managing code versions.

Why it matters

Without good commit messages, it becomes hard to understand the history of a project or why certain changes were made. This can slow down debugging, cause confusion in teams, and make collaboration frustrating. Clear commit messages save time and reduce mistakes by providing a simple story of the code’s evolution. They help everyone, including your future self, work smarter and faster.

Where it fits

Before learning to write good commit messages, you should know basic git commands like git add and git commit. After mastering commit messages, you can learn about branching, pull requests, and code reviews, where clear messages become even more important. Writing good commit messages fits early in the git learning journey as a foundation for effective teamwork.

Mental Model

Core Idea

A good commit message is a clear, short story that explains what changed and why, helping everyone understand the code’s history.

Think of it like...

Writing a commit message is like leaving a note on a shared fridge explaining what you cooked and why you put it there, so others know what’s inside and why it matters.

┌───────────────────────────────┐
│ Commit Message Structure       │
├───────────────┬───────────────┤
│ Header        │ Short summary │
├───────────────┼───────────────┤
│ Blank line    │ Separator     │
├───────────────┼───────────────┤
│ Body (opt.)   │ Detailed why  │
├───────────────┼───────────────┤
│ Footer (opt.) │ Metadata      │
└───────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a commit message

Concept: Introduce the basic idea of a commit message as a note explaining code changes.

A commit message is a text note you write when saving changes in git. It tells what you changed in the code. For example, if you fix a typo, your commit message might say 'Fix typo in README'. This helps you and others remember what each change does.

Result

You understand that every saved change in git should have a message explaining it.

Knowing that commit messages are the story behind code changes helps you see their value beyond just saving code.

2

Foundation

Basic git commit command usage

Concept: Learn how to create a commit with a message using git commands.

To save changes with a message, you use: git commit -m "Your message here". For example: git commit -m "Add login button". This command records your changes with the message you provide.

Result

You can create commits with messages that describe your changes.

Understanding the command to add messages is the first step to writing meaningful commit notes.

3

Intermediate

Structure of a good commit message

🤔Before reading on: do you think a commit message should be one long paragraph or have a clear structure? Commit to your answer.

Concept: Learn the recommended format: a short header, optional body, and optional footer.

A good commit message has three parts: 1. Header: A short summary (50 characters or less) of the change. 2. Blank line: Separates header from body. 3. Body (optional): Explains why the change was made, details, and context. 4. Footer (optional): Extra info like issue numbers or breaking changes. Example: Fix login button alignment The button was misaligned on mobile screens. Adjusted CSS to fix. Closes #42

Result

You know how to format commit messages for clarity and usefulness.

Recognizing the structure helps you write messages that are easy to read and understand later.

4

Intermediate

Writing clear and concise headers

🤔Before reading on: do you think the header should describe what changed or why it changed? Commit to your answer.

Concept: Focus on making the header a brief, clear summary of what changed, using imperative mood.

The header should be a short command-like phrase describing the change, e.g., 'Fix typo', 'Add login button', 'Remove unused code'. Use present tense verbs like 'Fix', 'Add', 'Remove'. Avoid vague words like 'Update' or 'Change'. Keep it under 50 characters for readability.

Result

You can write headers that quickly tell what the commit does.

Clear headers make scanning commit history fast and effective, saving time in teamwork.

5

Intermediate

Using the body to explain why changes matter

🤔Before reading on: do you think the body should explain how the change was done or why it was done? Commit to your answer.

Concept: Use the body to provide context, reasons, and details that the header can’t fit.

The body explains why the change was needed, what problem it solves, or any important details. For example: Fix login button alignment The button was off-center on small screens, causing confusion. Adjusted CSS margins to fix this. This helps others understand the reason behind the change, not just what changed.

Result

You can write commit messages that tell the full story behind changes.

Knowing why a change was made helps future developers avoid repeating mistakes or understand design choices.

6

Advanced

Including metadata and references in footers

🤔Before reading on: do you think footers are for code details or for references like issue numbers? Commit to your answer.

Concept: Footers add extra info like issue tracker IDs, breaking changes, or co-authors.

Footers are optional lines at the end of a commit message. They can: - Link to issue numbers (e.g., Closes #123) - Note breaking changes (e.g., BREAKING CHANGE: API updated) - Credit co-authors Example: Add user profile page Closes #56 BREAKING CHANGE: User API endpoint changed This helps tools and teammates track related work and important warnings.

Result

You can add useful metadata that integrates with project management and alerts.

Using footers connects commits to broader project context and automates workflows.

7

Expert

Common pitfalls and advanced tips for commit messages

🤔Before reading on: do you think very long commit messages are helpful or harmful? Commit to your answer.

Concept: Learn what to avoid and how to write messages that stay useful over time and in large projects.

Avoid: - Vague messages like 'fix stuff' or 'update code' - Mixing multiple unrelated changes in one commit - Writing too long or too short messages Tips: - Use present tense verbs - Keep commits focused on one task - Review messages before pushing - Use tools like commitlint to enforce style Good messages improve collaboration and reduce bugs in complex projects.

Result

You write commit messages that help teams work efficiently and maintain code quality.

Understanding pitfalls prevents common mistakes that cause confusion and wasted time in real projects.

Under the Hood

When you run git commit, git takes the staged changes and saves them as a snapshot in the repository. The commit message is stored as metadata with this snapshot. Git uses this message to build the project’s history log, which tools and developers read to understand changes over time.

Why designed this way?

Git was designed to track changes with context. Storing messages with commits helps humans understand the purpose behind code changes. The structured format (header, body, footer) was adopted from conventions like the Linux kernel to improve readability and automation.

┌─────────────┐     ┌───────────────┐     ┌───────────────┐
│ Working Dir │ --> │ Staging Area  │ --> │ Commit Object │
└─────────────┘     └───────────────┘     └───────────────┘
                             │
                             ▼
                    Commit Message Metadata
                             │
                             ▼
                    Git History Log

Myth Busters - 4 Common Misconceptions

Quick: Do you think a commit message should explain only what changed, not why? Commit to yes or no.

Common Belief: Commit messages only need to say what changed in the code.

Reality: Good commit messages explain both what changed and why, giving context to the change.

Why it matters: Without the why, future developers may not understand the reason behind changes, leading to repeated mistakes or wasted time.

Quick: Do you think very long commit messages are always better? Commit to yes or no.

Common Belief: Long commit messages with every detail are best for clarity.

Reality: Commit messages should be concise; too long messages are hard to read and often contain unnecessary info better suited for documentation.

Why it matters: Overly long messages reduce readability and slow down code reviews and history scanning.

Quick: Do you think it’s okay to combine unrelated changes in one commit? Commit to yes or no.

Common Belief: Combining multiple unrelated changes in one commit is fine if they happen at the same time.

Reality: Each commit should focus on a single logical change to keep history clear and make debugging easier.

Why it matters: Mixed commits make it hard to isolate bugs and understand project history.

Quick: Do you think the commit message header should be written in past tense? Commit to yes or no.

Common Belief: The header should describe what was done, so past tense is correct.

Reality: The header should use imperative present tense, like a command (e.g., 'Fix bug', not 'Fixed bug').

Why it matters: Using imperative tense keeps messages consistent and matches git’s built-in messages, improving clarity.

Expert Zone

1

Experienced developers use commit message templates and hooks to enforce style automatically.

2

Some teams adopt semantic commit messages with prefixes like feat:, fix:, docs: to automate changelog generation.

3

Rebasing and squashing commits before merging helps keep history clean and messages meaningful.

When NOT to use

Avoid writing detailed commit messages for trivial or experimental commits in local branches; instead, use detailed messages when preparing for sharing or merging. For very large changes, break them into smaller commits. Use pull request descriptions for broader explanations.

Production Patterns

In professional projects, commit messages often follow strict style guides and are linked to issue trackers. Automated tools parse messages to generate release notes. Teams review commit messages during code reviews to ensure clarity and consistency.

Connections

Version Control Systems

Writing good commit messages builds on the concept of version control by adding human-readable context to code snapshots.

Understanding commit messages deepens your grasp of how version control systems track and communicate changes.

Technical Writing

Good commit messages are a form of concise technical writing focused on clarity and purpose.

Skills in clear, purposeful writing improve commit message quality and overall communication in software projects.

Project Management

Commit messages often link to tasks and issues in project management tools, connecting code changes to business goals.

Knowing how commit messages relate to project tracking helps align development work with organizational priorities.

Common Pitfalls

#1 Writing vague commit messages that don’t explain the change.

Wrong approach:

git commit -m "Update stuff"

Correct approach:

git commit -m "Fix login button alignment on mobile screens"

Root cause:

Not understanding the importance of clarity and context in commit messages.

#2 Combining unrelated changes in a single commit.

Wrong approach:

git commit -m "Fix login button and update README and remove debug logs"

Correct approach:

git commit -m "Fix login button alignment"
git commit -m "Update README with setup instructions"
git commit -m "Remove debug logs from user module"

Root cause:

Lack of discipline in separating logical changes for easier tracking.

#3 Using past tense in commit message headers.

Wrong approach:

git commit -m "Fixed bug in payment processing"

Correct approach:

git commit -m "Fix bug in payment processing"

Root cause:

Misunderstanding the convention of imperative present tense for headers.

Key Takeaways

Good commit messages tell a clear story of what changed and why, making code history understandable.

A well-structured commit message has a short header, optional detailed body, and optional footer for metadata.

Use concise, imperative present tense in headers to keep messages consistent and easy to scan.

Separate unrelated changes into different commits to keep history clean and debugging easier.

Clear commit messages improve teamwork, speed up debugging, and connect code changes to project goals.