atomaka.com/_posts/2017-04-18-write-good-git-commits.md

106 lines
3.8 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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.
![My helpful screenshot](/assets/gui-git.webp)
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!