107 lines
3.8 KiB
Markdown
107 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!
|