git-pair

Small utility that prepares commit templates with a story id and co-authors.

Running any command with -h or without any arguments shows a help page, except git pair reset, which will disable commit templates until another command is run again.

Who is this project for?

Let's say you or your team want git commit messages that adhere to a consistent format. Typing it manually on each commit is error-prone and distracts you from the actual commit message.

Enter git-pair. When you start working on a story, use git pair story NICE-1 to set the story id and git pair authors fh jd and get coding. When you call git commit later on, your editor will be pre-filled with the following message:

NICE-1: 

Co-authored-by: Finn the Human <finn@thetreehouse.com>
Co-authored-by: Jake the Dog <jake@also.thetreehouse.com>

There is even a space after the colon: If you're using vim, you can just press A and start typing.

Slightest of Warnings: git-pair will overwrite your user commit.template setting. If you are using this for something else, this project might not work for you. Also, it will probably interact weirdly with other git commit templating tools.

Author initials

The mapping of initials that you can specify to git pair authors has to be maintained by hand. They are stored in git-pair/authors.dhall in your user config directory (XDG_CONFIG_HOME, should default to ~/.config/). If that sounds confusing, don't worry: Running git pair will show you the full file names.

The file is a dhall config file, but don't worry, if you saw json or wrote some code before it should look familiar.

To get you started, git pair exampleAuthorsFile will create the file with some example data if it doesn't exist.

Building/Installing

git-pair is written in Haskell. If you want to learn about Haskell, Learn You a Haskell for Great Good! is a nice introduction and can be read online for free.

This project uses stack as a build tool. Stack takes care of downloading the compiler and all that stuff for us. It should be available in major package repositories. Here are a few examples:

MacOS (with [homebrew](https://brew.sh/))

`brew install haskell-stack`

Nix

`nix-env -i stack`

Arch Linux

`pacman -S stack`

When you have stack installed, open a shell in the project folder and execute stack build. It takes a while on the first run, but that should be it!

Stack puts the binary in a bit of a weird place. The following command prints the full path to the binary:

echo "$PWD"/$(stack path --dist-dir)/build/git-pair/git-pair

Put it anywhere on your PATH and you will be able to call it as either git-pair or git pair

Common Issues

When I tried building it on debian 10, I got the following error:

<lots of output>
 (ConnectionFailure Network.BSD.getProtocolByName: does not exist (no such protocol name: tcp))

This can be fixed by installing netbase: apt install netbase

FAQ

I changed my mind, how can I get rid of everything this did?

Run git pair. In the text, it mentions two directories, one for config (probably ~/.config/git pair) and one for it's state (probably ~/.local/share/git pair). Run git pair reset (or unset the commit.template git setting yourself) and delete the two git pair folders and nothing will remain.

This is way too much typing. Why are the names so long?

You can use `git pair s` instead of `... story` as well as `a` for `authors`. If you think `pair` is too long, you can run `git config --global alias.ctp pair` and use `git ctp s STORY-42`.
Given that you will probably use this in a team, I suggest you agree on an alias to facilitate pairing. My proposal is git ctp, which can be set up with the above commands.

This is great, but I want to use a different template

I am sure you have a valid reason, but I would rather not add the complexity of supporting different templates. The problem isn't so much the templating itself but the configuration around it.
Right now, git-pair has very narrowly defined code paths, and I would prefer to keep it this way. Maybe you can fork this project? If you are ready to put a few minutes in, open an issue and we'll talk about it.

Licensing

This application is licensed under the GNU General Public License version 3 or later.