This monday I decided that my new week resolution is to put more effort in to my commit messages. Previously I considered it a success if I managed to keep profanity out of my messages.
How to make a better commit message.
Everyone has a different opinion of how commit messages should be written but there are a few generally agreed upon rules.
The over all format for a commit message
type(scope):subject
body
footer
Formatting rules include:
The subject and the body should be separated by a blank line for readability.
Unnessaccary punctuation marks should be removed from the message.
The subject line and each paragraph should be capitalized.
The imperative mood should be used for the subject line.
The body should be used to state what changes you have made and why you made them.
Summarize changes in around 50 characters or less
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 the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
The Imperative mood
When it comes to moods in languages I have historically been uninterested in learning the differences. However, there is a wonderful little phrase that helps us format our subject lines. Before every subject line you write imagine the phrase, "if applied, this commit will..." This will force you into the imperative mood.
if applied, this commit will update getting started documentation
if applied, this commit will remove deprecated methods
if applied, this commit will merge pull request #123 from user/branch
The reason we use the imperative mood is because it continues the pattern that git itself established for commit messages. Consistency is key.
Types
Types are used so you can quickly see what kind of change has been made.
feat: is used for changes that pertain to feature updates.
fix: is used for bug fixes
style: is used to fix code styling such as indentations
refactor: is used for when code has been refactored
chore: is used for regular code maintenance.
perf: is used for an update that addresses the performance of the code
docs: is used for any change that has to do with documentation of the code
test: is used for changes made to tests.
This method of commit messages may be a bit extensive for smaller project or if you are going to rebase your commits and the smaller messages will be lost in the git void.
The short form of commit messages would be just the type, scope and subject line.
<type>([optional file name]): <short description>
A way to format the subject line when using a shorter commit message would be
Remove the X & Add the Y to allow Z
This phrase addresses everything that is needed to make your commit messages easy to understand by an outsider.
There are three things to remember about commit messages if nothing else.
- Do not assume that the reader knows what the original problem was. 2 Your code is not self-explanatory.
- Follow the convention set by your team.
Consistency is important for keeping commit messages understandable, especially when working in a team.
Top comments (0)