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 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

Credit: Imgur

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) summary
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 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.

• 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?

Credit: xkcd

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!