Writing Good Commit Messages

Saving snapshots of your project with git commit is fundamental. However, simply saving the changes isn't enough. Each commit requires a message, and the quality of these messages significantly impacts the usefulness of your project's history. Think of commit messages as the narrative of your project's evolution. Clear, informative messages make it much easier for you (and your collaborators, if any) to understand why a change was made months or even years later.

Good commit messages are essential for:

• Understanding History: When you use git log, descriptive messages quickly tell you what each commit accomplished.
• Debugging: If a bug is introduced, well-written commit messages can help pinpoint the commit that caused the issue.
• Collaboration: They allow teammates to understand the context and purpose of changes without having to analyze the code in detail.
• Code Reviews: Clear messages provide context for reviewers, making the review process more efficient.

The Structure of a Good Commit Message

A widely accepted convention for Git commit messages follows a specific structure:

1. Subject Line: A short, concise summary of the change (ideally 50 characters or less).
2. Blank Line: A single empty line separating the subject from the body.
3. Body (Optional but Recommended): A more detailed explanation of the change, explaining the 'what' and 'why'.

Let's break down each part.

The Subject Line: Keep it Short and Imperative

The subject line is the most important part of the commit message. It's what you see when running commands like git log --oneline.

• Use the Imperative Mood: Write the subject line as if giving an order or instruction. For example, use "Fix login bug" instead of "Fixed login bug" or "Fixes login bug". This convention matches the commands generated by Git itself (like git merge or git revert). Think of it as describing what the commit does when applied.
• Capitalize the First Letter: Just like starting a sentence.
• Keep it Concise: Aim for 50 characters or fewer. This ensures it displays well in various Git tools without truncation.
• No Period at the End: Subject lines are like titles; they don't typically end with a period.

Examples:

• Good: Add user authentication endpoint
• Good: Refactor database connection logic
• Good: Correct typo in README.md
• Less Good: fixed stuff (Too vague)
• Less Good: Implemented new feature for users to log in and out. (Too long, not imperative)
• Less Good: fixing the css alignment issue on the main page (Not capitalized, not imperative)

The Body: Explain the What and Why

While the subject provides a quick summary, the body is where you can elaborate. It's separated from the subject by a blank line. This separation is important because many Git tools treat the first line as the subject and everything after the blank line as the body.

• Explain Motivation: Why was this change necessary? What problem does it solve? Provide context that might not be obvious from the code itself.
• Describe the Approach: Briefly explain how the change addresses the issue, especially if it involves non-obvious decisions or trade-offs.
• Wrap Lines: Keep lines in the body wrapped at around 72 characters. This improves readability in terminals and tools like git log. Most text editors can be configured to do this automatically.
• Reference Issues (If Applicable): If your project uses an issue tracker (like GitHub Issues or Jira), reference the relevant issue number (e.g., Fixes #42, Addresses ticket T-123). Some platforms automatically link commits to issues based on these references.

You don't always need a body. For very simple changes (like fixing a typo), a clear subject line might be sufficient. However, for anything more complex, providing a detailed body is highly recommended.

A Complete Example

Here’s an example of a well-structured commit message:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here.

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Example commit message structure based on community best practices.

Why It Matters

Spending a few extra moments crafting a good commit message pays off significantly in the long run. It transforms your Git history from a simple log of changes into a valuable resource for understanding your project's development. When you need to figure out why a particular piece of code exists, or when tracking down a regression, clear commit messages can save you hours of frustration. As you start collaborating with others, consistent and informative commit messages become even more important for effective teamwork. Start forming this habit now, even for your personal projects; your future self will thank you.