What Makes a Good Commit?

I'm sure most of us have written commit messages like "asd", "asdfg", or "update" at some point. The thing is, it helps to stop thinking of the commit command as a save button and instead treat it as a meaningful entry in your project's development journal.

A year from now — or when a teammate looks at it an hour from now — we should be able to answer the question: why did I do this?

Things to Keep in Mind When Committing

Since we've established that commits are a project's journal, there are some well-accepted golden rules for keeping that journal clean. Let's go through them. Here's what to watch out for when running git commit -m "message".

Atomic Commits (Small and Focused)

A good commit should be atomic — it should do exactly one thing. This maps nicely to the Single Responsibility Principle from the SOLID principles in software design.

  • Wrong: Changing a button color and fixing a database connection error in the same commit.
  • Right: Sending those two changes as two separate commits.
  • Why? If the database fix causes a problem, we can revert just that commit without touching anything else.

Message Anatomy: The 50/72 Rule

There's a standardized commit structure in the software world — an unwritten but universally accepted convention. Following it prevents eye fatigue when reading logs.

  • Subject line: Maximum 50 characters. It's a very short summary of the change — something you can understand at a glance without having to think about it.
  • Blank line: Leaving a blank line between the subject and the body both helps the reader and lets platforms like GitHub and GitLab correctly separate the two. It's a good habit.
  • Body: Where the necessary details go. Lines should be a maximum of 72 characters — meaning you should actually hard-wrap at 72 characters (this makes reading in the terminal much easier).

The Right Voice: Imperative Mood

This is somewhat a matter of convention, but the widely accepted standard is to write in the imperative mood.

  • Wrong: "Added user login", "Adding user login"
  • Right: "Add user login"
To check whether your subject line is correct, use this magic sentence: "If applied, this commit will [your subject line]." If it reads naturally, your subject line is good.

Explain "Why" and "What" — Not "How"

There's no need to describe in detail how a change works, because the code is right there. The body of a commit message should answer:

  • Why was this change necessary?
  • What does this commit do?
  • Are there any side effects or impacts on other modules?

To illustrate with an example:

  • Bad example (explains the "how"): "Removed the for loop in the user list, replaced it with map(), and dropped the i variable." (You can already see this by looking at the diff.)
  • Good example (explains the "why" and "what"): "Resolved a performance bottleneck that occurred while loading the user list. Switched from the old loop structure to map() to reduce data processing time."

Traceability

If your team uses project management tools like Jira, Trello, or GitHub Issues, the relevant task reference number (e.g., TICKET-10) should appear in the commit message. This makes it easy to follow the workflow on the integrated platform. Example: fix: resolve validation error on user login (TICKET-10)

Never Commit Broken Code

If we haven't finished something, or we've broken it and need to step away from the computer, we should never push that to a shared branch (main, develop, etc.). Pushing broken code to main branches is especially dangerous in team environments and projects with CI/CD (Continuous Integration) pipelines. In these situations, opening your own branch or using git stash are the right options.

Example Template

example template 
Subject line
Short and focused subject line (max 50 characters, imperative mood)

Body
Write the detailed body here explaining why the change was made.
Keep lines under 72 characters so it reads cleanly in the terminal.
Explain what solved the problem and, if applicable, why alternative
approaches were rejected.

Reference (if applicable)
Resolves Issue #10

Bonus: Conventional Commits

Today, many popular open source projects and enterprise teams have adopted a standard of adding a specific prefix to commit messages. Think of it as a shared language that both humans and machines can understand. It also makes generating automatic release notes much easier. You can find the official specification and full details at conventionalcommits.org. The most commonly used prefixes are:

  • feat: When a new feature is added. (e.g., feat: add user profile page)
  • fix: When a bug is fixed. (e.g., fix: resolve password reset email error)
  • refactor: Changes that neither add a feature nor fix a bug — just improving the structure of existing code. (e.g., refactor: simplify data fetching function)
  • docs: Documentation-only updates. (e.g., docs: add installation steps to README)
  • style: Formatting changes that don't affect how the code runs (whitespace, semicolons, etc.). (e.g., style: remove trailing spaces and fix indentation)

To Wrap Up

Following all these rules might feel a bit slow or tedious at first. But once you've made them a habit, you'll thank yourself when you look back at your own code months later — or when a new teammate joins the project. Remember: the code you write is for machines, but your commit messages are for people. Clean logs and bug-free days ahead!