How To Write Proper Git Commit Messages

A git commit records changes to a repository.

A git commit is executed in the course of a project to record progress. This progress is then pushed to a remote repository (like on by executing a git push. These changes or progress could mean any additions, deletions, or updates to the files stored in the repository.

Overview of a Proper Git Commit

The quickest way to write a git commit is to use the command git commit -m "Git commit message here". This is not recommended for commits, however, because it provides limited description of what was changed. Essentially, a git commit should explain what and why a change has been made.

Here is the guideline for writing a full git commit.

  • A subject which contains the title of the git commit. This should be limited to 50 characters and should be separated from the rest of the commit with a blank line.
  • Explanatory text explaining what has been changed and why the change was necessary. Write in the imperative mood e.g. “Fix bug causing outage” rather than “Fixed bug causing outage”.

See below for an example of an implementation of the above.

Source: Tim Pope

Writing A Proper Git Commit

  • To write a git commit, start by typing git commit on your Terminal or Command Prompt which brings up a Vim interface for entering the commit message.
  • Type the subject of your commit on the first line. Remember to keep it short (not more than 50 characters). Leave a blank line after.
  • Write a detailed description of what happened in the committed change. Use multiple paragraphs and bullet points to give a detailed breakdown. Don’t write everything out on one line, instead, wrap text at 72 characters.
  • Press Esc and then type :wq to save and exit.

Write your commit message in the imperative: “Fix bug” and not “Fixed bug” or “Fixes bug.” This convention matches up with commit messages generated by commands like git merge and git revert.

A commit message should answer three primary questions;

  • Why is this change necessary?
  • How does this commit address the issue?
  • What effects does this change have?

A proper, well written git log is an important indicator for how well thought out a project is.

Proper commit messages will make it easy to understand why a change has been made at a particular time. With this, maintainers of a project will easily be able to make changes decades later because they understand the code.

Happy coding!

Entrepreneur, music aficionado, tech geek. Stephen is the founder of @codayetech, a software dev startup targeting the African market

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store