How To Write Proper Git Commit Messages

Stephen Amaza
Mar 29, 2017 · 3 min read
Image for post
Image for post

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 github.com) 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

Image for post
Image for post

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.

Capitalized, short (50 chars or less) summaryMore 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 an email 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); tools like rebase can get confused if you run the
two together.
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.
Further paragraphs come after blank lines.- Bullet points are okay, too- Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here- Use a hanging indent

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.
Image for post
Image for post
  • 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?
Image for post
Image for post

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.

Image for post
Image for post

Happy coding!

Stephen Amaza

Written by

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

Stephen Amaza

Written by

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

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

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