My Configuration

I've been using git for over ten years. Over that time I've found a collection of configuration options that seem to work well for me. I normally configure all of my workstations with these options.

These options includes a collection of "aliases" which really make my life easier.

Configuration Options

Identity

These options set the default name, email, and PGP key used for commits. The values of the options are different on personal and work machines.

• Personal machines

  git config --global user.name "John Simpson"
  git config --global user.email "jms1@jms1.net"
  git config --global user.signingkey "0xE3F7F5F76640299C5507FBAA49B9FD3BB4422EBB"
  

• For $DAYJOB machines

  git config --global user.name "John Simpson"
  git config --global user.email "jms1@domain.xyz"
  git config --global user.signingkey "0x1234C0FFEEC0FFEEC0FFEEC0FFEEC0FFEEC0FFEE"
  

Note that I also have aliases for cases where I might need to sign a commit using my personal "identity", on a $DAYJOB workstation. Because my PGP and SSH keys are stored on Yubikeys, I can just plug the "other" Yubikey into the machine and use the correct alias.

These aliases are documented below.

For all machines

I use these configuration options on every machine.

git config --global core.editor "nano"
git config --global core.excludesfile "$HOME/.gitignore_global"
git config --global credential.helper "cache --timeout=300"
git config --global init.defaultBranch "main"
git config --global clone.defaultBranch main
git config --global log.showSignature true
git config --global push.default "simple"
git config --global pull.rebase false
git config --global gpg.ssh.allowedSignersFile "$HOME/.config/git/allowed_signers"

All of my commits and tags are signed. This is a requirement at $DAYJOB, and a good idea in general.

git config --global commit.gpgsign true
git config --global tag.gpgSign true

Commit message template

This sets up a text file which is used as a template when git uses a text editor to create or edit a commit message.

In particular, I generally use the 50/72 format format when writing commit messages. As you can see below, having the ^ marks at 50 and 72 characters makes it easier for me to stay within the limits.

• To configure the file:

  git config --global commit.template "$HOME/.stCommitMsg"
  

• The contents of the file:

  $ cat ~/.stCommitMsg
  
  
  #                                             50 ^                  72 ^
  # First line: start with ticket number(s), limit to 50 characters
  # BLANK LINE
  # Additional lines: limit to 72 characters
  $ git config --global commit.template "$HOME/.stCommitMsg"
  

Note that empty lines and lines starting with # are not included in the actual commit message.

Aliases

Aliases allow you to "make up your own git commands". For example, if you were to do this ...

git config --global alias.showfiles "show --name-only"

... then git showfiles would be the same as git show --name-only.

My Usual Aliases

These are the aliases I've built up over the years. Some of these I use dozens of times every day.

git config --global alias.log1 "log --oneline --no-show-signature --abbrev=8 '--pretty=tformat:%C(auto)%h%d %C(brightcyan)%as %C(brightgreen)%al(%G?)%C(reset) %s'"
git config --global alias.tree "log --graph --decorate"
git config --global alias.tree1 "log --date-order --decorate --graph --no-show-signature '--pretty=tformat:%C(auto)%h%d %C(brightcyan)%as %C(brightgreen)%al(%G?)%C(reset) %s'"
git config --global alias.tagdates "log --tags --simplify-by-decoration --pretty=\"format:%ai %d\" --no-show-signature"
git config --global alias.taghashes "log --tags --simplify-by-decoration --pretty=\"format:%H %d\" --no-show-signature"
git config --global alias.id "describe --always --tags --long --abbrev=8 --dirty"
git config --global alias.top "rev-parse --show-toplevel"

Changes for older git versions

Some colours and tags were added between git 2.16.5 and 2.37.0.

• %as (commit date YYYY-MM-DD) -> %ad with --date=short option
• %al (author email local part) -> %an (author name)

For older versions without these newer colour codes, I use these aliases instead.

git config --global alias.log1 "log --oneline --no-show-signature --abbrev=8 --date=short '--pretty=tformat:%C(auto)%h%d %C(cyan)%ad %C(green)%an(%G?)%C(reset) %s'"
git config --global alias.tree1 "log --date-order --decorate --graph --no-show-signature --date=short '--pretty=tformat:%C(auto)%h%d %C(cyan)%ad %C(green)%an(%G?)%C(reset) %s'"

Sign commits using specific keys

These aliases allow me to sign commits using my personal PGP key on the work machine, or vice-versa, by physically plugging the correct Yubikey into the machine. By themselves they won't be very useful to anybody else, but they could be useful as examples if you have to deal with

git config --global alias.commitp "commit --gpg-sign=E3F7F5F76640299C5507FBAA49B9FD3BB4422EBB --author='John Simpson <jms1@jms1.net>'"
git config --global alias.commitw "commit --gpg-sign=1234C0FFEEC0FFEEC0FFEEC0FFEEC0FFEEC0FFEE --author='John Simpson <jms1@domain.xyz>'"

Notes

Random notes relating to git

Commits signed with SSH keys

If you're using 2.34.0 or later you may see this error message work working with repos where others users may have signed commits using SSH keys instead of PGP keys.

error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification

Reference

git 2.34.0 added the ability to sign commits using SSH keys. This functionality is related to how OpenSSH implements "SSH certificates". I've looked into this in the past, but it seems to be a lot more trouble than it's worth.

I don't really see the need for this, other than "some people can't, or don't want to, take the time to figure out PGP" ... but unfortunately, it's something we have to deal with, especially when you're working with shared repos (where other people are making commits).

Because these are not PGP keys, there is no concept of a "web of trust", so git has no way to tell if a signature created using an SSH key should be trusted or not. In order to work around this problem, git can be configured with a filename that, if it exists, will contain a list of email addresses and the SSH public keys which should be "trusted" for commits signed using those emails.

The file format is documented in the ssh-keygen(1) man page, in the "ALLOWED SIGNERS" section (near the end of the page). In most cases, each line will be an email address, followed by the public key's line from an authorized_keys file, like so:

jms1@jms1.net ssh-rsa AAAAB3Nz...Pw== jms1@jms1.net 2019-03-21 YubiKey Blue
jms1@domain.xyz ssh-ed25519 AAAAC3Nz...YDQu jms1@domain.xyz 2022-01-24 YubiKey Green

Configure SSH Signature Verification

If you are using git 2.34.0 or later and are seeing this message, you can make it go away by doing the following:

• Configure a filename which, if it exists, will contain the list of known email addresses and SSH keys.

  git config --global gpg.ssh.allowedSignersFile "$HOME/.config/git/allowed_signers"
  

  Note that the file itself doesn't have to exist - just having this option present in your $HOME/.gitconfig file is enough to prevent the error message from being shown.

  ⚠️ This is included in the list at the top of the page.

• If you work with people who use SSH keys to sign commits, you can create a $HOME/.config/git/allowed_signers file and add the email addresses and SSH public keys, in the format shown above.

Configuration scope

The git config command operates on different files, depending on which options you give it.

Changelog

2024-06-20 jms1

• Created this page (from pre-existing notes)