Level Up Your Git Commit Messages: From Cryptic to Crystal Clear

Hey developers! Ever stared at a commit message from your past self and thought, "What in the world was I thinking?" Those one-liners like "fix bug" or "changed stuff" might seem clear at the moment, but trust me, future you (and your teammates) will be scratching their heads later.

When I started my career as a developer, I used to spend so much time writing the perfect commit message and no matter what I wrote, it was just never perfect. But now, I feel like I am getting better at it!

But don't worry! Today, we're on a mission to help you craft commit messages that are informative, engaging, and downright awesome. Imagine your commit message as a quick conversation with your future self or a teammate about the changes you made. What did you do? Why did you do it? Keeping things clear and concise is key.

Battle Plan for Stellar Commit Messages:

1. Channel Your Inner Chatty Cathy (or Chad):
   Let's ditch the overly technical jargon. Use a friendly and informal tone that a fellow developer would understand. Think of explaining the changes to a teammate over coffee. ☕️

2. Start with a Bang!
   The first line of your message, the commit summary, is prime real estate. Keep it short and sweet, ideally under 50 characters. This is your chance to grab everyone's attention with a clear and concise headline.

3. Pick the Right Type: There are different types of commits, like fixing bugs ("fix") or adding new features ("feat"). Using these helps categorize your changes and makes navigating the commit history a breeze.

4. Body Language Speaks Volumes: The message body is your space to elaborate on the "what" and "why" behind your changes. Why was this fix needed? What problem does this new feature solve? Be clear, concise, and avoid filler words. Every character counts!

5. Become a Code Journalist: ️‍Think of yourself as a reporter explaining the changes to someone who wasn't there. They don't have any background information, so make sure your message tells the whole story.

   Pick the Right Type:

   There are different types of commits, like fixing bugs ("fix") or adding new features ("feat"). Using these types helps categorize your changes and makes navigating the commit history a breeze.

   Here's a cheat sheet:

   • feat - a new feature is introduced with the changes

   • fix - a bug fix has occurred

   • chore - changes that don't relate to a fix or feature and don't modify source code or test files (e.g., updating dependencies)

   • refactor - refactored code that neither fixes a bug nor adds a feature

   • docs - updates to documentation such as the README or other markdown files

   • style - changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.

   • test - including new or correcting previous tests

   • perf - performance improvements

   • ci - continuous integration related changes

   • build - changes that affect the build system or external dependencies

   • revert - reverts a previous commit

Bonus Tip: Feeling stuck? Imagine you're writing a news blurb about your code changes. What's the key takeaway? Why is this update important?

De-coding the "Why" Not the "How"

Let's delve deeper into crafting that all-important first line, the commit summary. This is your chance to shine a light on the purpose of your changes, not how you achieved them.

Here's an example:

• Bad: "Changed button color to red"

This tells us what you did, but not why. Was there a usability issue with the old color? Did the design change?

• Good: "Update button color for consistency with brand guidelines"

This is a much better explanation! It highlights the goal of the change, making it easier to understand for anyone reading the commit history, and ensures the button aligns with the overall design.

Using the Imperative Voice for Extra Impact

Another way to write strong commit summaries is to use the imperative voice. This means phrasing your message as a command that describes what the commit accomplishes.

Let's use a different example:

• Bad (not imperative): "This commit fixes an issue where the product image wouldn't load on product pages."

This is okay, but it can be worded more concisely and directly.

• Bad (how, not why): "modified image loading logic to ensure product images display correctly."

This focuses on the "how" instead of the "why."

• Good: "Fix product image loading issue on product pages." ️

This uses the imperative voice ("fix") and clearly states the purpose of the change.

Remember, good commit messages are like a treasure map for your code. They help you and your teammates navigate changes, understand the project's history, and avoid future headaches.

So, the next time you commit, take a few extra minutes to craft a clear and informative message. Your future self (and your team) will thank you for it!

Would love to catch up in comments about some more tips on writing better commit messages.