106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
---
|
||
layout: post
|
||
title: Write Good Git Commits
|
||
tag:
|
||
- git
|
||
- github
|
||
---
|
||
|
||
Writing quality Git commits has been written about to death, but it is so
|
||
important that I could not help myself from sharing my thoughts on the subject.
|
||
Mostly, I will be rehashing what
|
||
[Tim Pope has shared](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
|
||
but I will also include a few of the things that I have used to improve my
|
||
source histories.
|
||
|
||
### Limit the subject of your commit to 50 characters
|
||
|
||
Many people live life as I do: at the command line. Limiting to 50 characters
|
||
allows room for us to use an 80 character width for commands such as git rebase
|
||
--interactive without width concerns. Even for those in a more modern IDE, the
|
||
limit is important.
|
||
|
||
|
||
|
||
As commit messages get longer, it becomes more difficult for everyone to
|
||
traverse your history.
|
||
|
||
### Use the commit body for important details
|
||
|
||
It is very rare that I see people extend their commit histories into the body
|
||
portion of a commit but it is the perfect place to offer extra details. Things
|
||
like what resources you used to make a specific decision are better left in the
|
||
commit history than in code comments most of the time. In a
|
||
[recent commit to my dotfiles](https://github.com/atomaka/dotfiles/commit/28a3897995ff21f63f7893f43582532e4717b8d9),
|
||
I added a quick alias to correct a TouchBar issue I was having.
|
||
|
||
```
|
||
Fix TouchBar when it (frequently) breaks
|
||
|
||
From http://osxdaily.com/2017/01/11/manually-refresh-touch-bar-mac/ this
|
||
will reset the control portion of the touch bar which has been
|
||
frequently breaking in New and Interesting Ways™.
|
||
```
|
||
|
||
Without these details, I might never be able to find the source for why I
|
||
added this.
|
||
|
||
Also, limit the line length in the body to 72 characters.
|
||
|
||
### Do not use the --message option
|
||
|
||
Pretty much everyone I watch make a commit will do so directly at their command
|
||
prompt with git commit -m. Forcing yourself into an editor will encourage you to
|
||
add additional details about a commit message. Additionally, your editor can
|
||
configured to alert you to the 50/72 rule. Simply add au FileType gitcommit set
|
||
t==72 to your vimrc to auto wrap git messages at 72 characters if vim is
|
||
configured as your Git editor. [vim-git](https://github.com/tpope/vim-git) is
|
||
also a fantastic option that will highlight based on these rules.
|
||
|
||
If you are struggling with breaking your -m habit, try creating a bash function
|
||
to prevent its usage.
|
||
|
||
```
|
||
function git {
|
||
if [[ $@ == "commit -m" ]]; then
|
||
echo "Do not specify -m for commit"
|
||
else
|
||
command git "$@"
|
||
fi
|
||
}
|
||
```
|
||
|
||
### Commit as if giving a command
|
||
|
||
[How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
|
||
made me consider the subject of my commits a little more. In bullet point 5,
|
||
Chris says "Use the imperative mood in the subject line." Considering Git itself
|
||
follows this rule, it made perfect sense to jump on board.
|
||
|
||
```
|
||
Merge branch 'bugfix/correct-spacing'
|
||
```
|
||
|
||
And
|
||
|
||
```
|
||
Revert "Implement person CRUD"
|
||
```
|
||
|
||
The best advice I picked up was write your commit as if you are completing the
|
||
following sentence: "If applied, this commit will..."
|
||
|
||
### Rebase your branches, but leave master alone
|
||
|
||
Rebasing is a heated topic in the community but the one thing that everyone can
|
||
agree on is leaving master alone. Once your commit has made it there, it is
|
||
history and should never be changed. However, your branch is your story. You get
|
||
to tell it however you want so craft it in a way that is useful to the reader.
|
||
|
||
For me, this is particularly important because the second thing I do when
|
||
reviewing a new code base is look at the commit history to see to story of the
|
||
application. Unfortunately, most are riddled with messages like "fixed typo" or
|
||
"asdf" and the history becomes unreadable.
|
||
|
||
Take care in crafting your git messages and you will find much more value in
|
||
your git logs!
|