Git Checklist

I was juggling lots of private git branches at work and making some use of the branch description file (see git branch --edit-description) to store my notes for each branch. This was good for me because the descriptions aren't committed to the branch so they would never make it upstream (even by accident). However managing the TODOs themselves was pretty unwieldy.

And so was born git-checklist, though in actual fact I've aliased it to git todo. Assuming it's in your path:

$ git config alias.todo=checklist

Otherwise, like this:

$ git config alias.todo=!/path/to/git-checklist

Using It Is Easy

To view your TODOs, just enter the bare command from a git repository:

$ git todo

Well, if you've not got anything to do yet, it won't have anything to show you. Find out where to go next:

$ git todo --help
Usage: git-checklist [COMMAND]
  Per-branch TODO list for Git repositories

Available options:
  -h,--help                Show this help text

Available commands:
  show                     Show current TODOs
  add                      Add a TODO
  done                     Mark a TODO as done.
  undo                     Item needs redone!
  remove                   Remove a TODO (can't be undone)
  stats                    Summary statistics of checklist

It will give you a summary of the commands you can enter at this point. There are no entries yet so all you can do is add them.

$ git todo add Add an informative README file
1: [ ] Add an informative README file

Each entry has a number in the left column and a box. Empty boxes mean the item is still to be done. When you've finished a task, mark it done using the number as a reference:

$ git todo done 1
1: [x] Add an informative README file

You can also "undo" items if you realise that the fix you made wasn't so hot after all, or you didn't understand the issue fully, or whatever other reason.

Finally you can remove items entirely from the list. This is permanent and can't be undone.

Advanced Usage

If you're knee deep in work on one branch and you'd like to change the checklist for another branch, all the commands will recognise the --branch (or -b) option.

$ git todo add --branch newparser Make nicer error messages

If you want to start a description of your note with a hyphen you can separate it from the rest of the command options with a double-hyphen on its own.

$ git todo add -- -b stopped working but --branch still okay

If you want to see all your branches at once use

$ git todo show --all

Obviously you can't supply the --all flag to any of the editing commands --- you can only edit one branch's checklist at a time.

There is one more overview command that will take --branch or --all as an option:

$ git todo stats
2 tasks to do (4 in total)

Work In Progress Commits

I've got an alias called wip which lets me quickly save all my unsaved work in the current branch. You can use this as a basic command:

$ git config alias.wip=commit -a -m"WIP"

But if you use git-checklist the following might be more informative when you are trying to get the measure of your branches:

$ git config alias.wip=!git commit -a -m\""WIP $(git todo stats)"\"

Then you'll get a commit that says something like WIP 2 tasks to do (4 in total which is much nicer. For the cherry on top I also use prepare-commit-msg to pipe the result of git todo show to the commit message. The summary line will contain a summary and the rest of the message will contain the current state of the branch.

Background Details

The checklists are stored in .git/checklist/<branchname>. The serialised form is basically just the checklists without the number prefix. This is similar to the checklist format used by GitHub's extended Markdown, so you can re-use the file contents if desired.

The format is very easy to read and edit manually.

[ <mark> ] <space> <description> <newline>

The is either "x" for a completed item or a space otherwise. (The parser will accept any non-"x" as pending but will always write a space.) The description must not contain a newline but is otherwise freeform.

The checklist for the working directory is whatever branch name is pointed to by HEAD. I have not tested it with a detached head, though I guess you'd just end up with a SHA as a branch name.

Installing It Is Fairly Easy

Assuming you've got a Haskell installation (if not, [grab the Haskell platform] hp) you can grab the source and build with Cabal.

$ git clone http://github.com/dougalstanton/git-checklist
$ cd git-checklist
$ cabal build
$ cabal install

Shortcomings

The data is stored in a separate directory inside .git which isn't versioned --- this is a local list only. I am open to suggestions to make this versioned though it is not a priority for me. My workflow is based around a single computer.

The read/write step bashes into the awkwardness of lazy IO.

It doesn't cope very well with not being somewhere inside a repository. It shouldn't wreck anything but the error message isn't very refined.

Upgrading

If you were using a pre-1.0 version the file format has changed incompatibly. There is a secret flag to upgrade:

$ git-checklist --upgrade

Alternatively you can do it manually before you upgrade the application like this. The key part is to strip the first four characters from each line, ie the number--colon--space prefix.

for b in .git/checklist/* ; do
    git-checklist show --branch $(basename $b) | cut -c 5- > $b
done