Better Git Commit Messages with Vim

Git Commit Template

It is one thing to read about good commit messages and another completely to remember that information when we go to write them. One of the options when committing is -t, --template <file>. You can use any text file as your template. Just remember that any line beginning with a hash # is a comment; it will not be part of the commit message. Now, save this file some place safe such as ~/.git-commit-message-template.txt.

Here is my latest template version. It is based on things I read from Jole Henderson 2.

.git-commit-message-template.txt (Source)

 1 #   Add = Create a capability e.g. feature, test, dependency.
 2 #   Cut = Remove a capability e.g. feature, test, dependency.
 3 #   Fix = Fix an issue e.g. bug, typo, accident, misstatement.
 4 #   Bump = Increase the version of something e.g. dependency.
 5 #   Make = Change the build process, or tooling, or infra.
 6 #   Start = Begin doing something; e.g. "Branch by abstraction"
 7 #   Stop = End doing something; e.g. remove a feature flag.
 8 #   Refactor = A code change that MUST be just a refactoring.
 9 #   Reformat = Refactor of formatting, e.g. omit whitespace.
10 #   Optimize = Refactor of performance, e.g. speed up code.
11 #   Document = Refactor of documentation, e.g. help files.
12 # Capitialize, imperative, no ending period
13 # First word from above -- max of 50 ------------|
14 
15 
16 # Explain what and why this change, not HOW.  -------------------------|
17 # Trouble explaining? Split commits with `git add -p`
18 
19 # Any references to tickets, articles, or other resources at end.
20 # Ticket: #123      Resolves: #123
21 # Closes: #123      See also: #456, #789
22 # -------------------------------------
23 # Information used in creating this document is taken from:
24 # https://github.com/joelparkerhenderson/git_commit_message
25 # ======================================================================

While helpful, having to remember the template file every time I commit is going to be a chore. Technology was supposed to free us from these things. Git has this in mind and gives us a way to make commit templates, part of every project.

There are four different ways to use a template as part of a routine commit process. We can configure it as part of our --global, --system, --local

As a refresher, the system config is for all users of a system and located at /etc/gitconfig. The global config is global to a single user and is found at ~/.gitconfig. The local config is used by the repository and is at .git/config.

For most of us, we should place the template in our global config. We configure git to use the template with the following command.

$ git config --global commit.template ~/.git-commit-message-template.txt

Enhanced Vim Experience

Now, I have my reminders when creating a commit message. However, there is a rough edge I want to smooth out when vim opens the template. I want vim to place me on the first blank line in insert mode. You may think I am being finicky, and I am, but I find it an interesting problem and an opportunity to learn more about vim.

First, what command line arguments can I give vim? In vim and looking through help, :help cmdline-arguments I found that -c {command} and +{command} will allow me to give commands to vim after the buffer/file is opened.

From looking at the file, line 14 is where I want to be. The command line argument +14 will put me at the right place. At least until I change the commit message because I want to alter it. Then I have to dig up this post and figure out how to make it work again. Is there a better way?

How about I search for the beginning of a line, immediately followed by the end of a line? That command in vim is /^$ 3. When I try using it at the command line

$ vi -c "/^$" .git-commit-template.txt

it places me on the first blank line! Just what I wanted. Now how do I begin inserting? Poking around vim help with :help inse<CTRL D> showed me a list of possible topics. One that caught my eye was startinsert. Putting it all together

$vi -c "/^$" +startinsert .git-commit-template.txt

Now to make git use it. Remember that whole "storing a template in the config" thing I mentioned earlier? We can also set the editor with arguments.

$ git config --global core.editor "vim -c '/^$' +startinsert"