Git Commit Message, Vim, and Markdown

It's been bothering me for years.

That is, # is both the start of a comment in a git commit message, but also the syntax for headings in Markdown.

Personally, I prefer using commit messages to populate pull request descriptions whenever possible. On GitHub, This happens automatically when the pull request contains a single commit. But I can't type, say an H3 as ### Heading in the commit message (in Vim, most of the time) because it gets treated as a comment!

But thanks to this twitter interaction with @dmartincy, I finally solved this problem:

I haven't found myself in that situation, but maybe you could do 'git config core.commentChar ";"' before creating the commits? That will change the default git commit marker (#) to something that won't conflict with Markdown titles.

— Daniel Martín (@dmartincy) April 6, 2020

As mentioned by Daniel, Git has introduced a setting called core.commentChar, documented here, which lets us control which character becomes the start of a comment line. Let's say we want to replace the default # with ;, we can edit ~/.gitconfig to include this preference:

[core]
	commentChar = ";"

… and this will affect every Git repository on this computer.

For me, though, this broke git commit syntax highlighting in Vim: the comments, beginning with ;, are no longer recognized as comments. To fix this, I updated Vim's syntax for file type gitcommit. In your Vim setting directory (~/.config/nvim/ for me), create a file syntax/gitcommit.vim file (unless you already have one), add the following line:

syn match gitcommitComment	"^;.*"

Note ; matches my preferred core.commentChar for Git.

Et voilà! Git commit message looks tippy-top in Vim again!

editing git commit in vim, with alternative character being the beginning of a comment