How do you annotate a branch?

Solution 1:

This would be a totally different approach than git note but you could use git config for this functionality.

$ git config branch.<branch-name>.note 'This is what this branch is for'

This can be aliased to make the interface simpler (I'm guessing this can be improved but this is what I use):

$ git config alias.branch-note '!git config branch.$(git symbolic-ref --short HEAD).note $( if [ $# -gt 0 ]; then $1; fi)'

This allows you to set the branch note like so (make sure you quote the note):

$ git branch-note 'This is what this branch is for'

You can then retrieve the current branches note like this:

$ git branch-note
This is what this branch is for

As an added benefit, config entries defined under the branch.<branch-name> namespace will follow branch renames and be automatically cleaned up if you delete the branch later. These superfluous config entries will only persist as long as the branch exists, at which time they will be automatically deleted.

A downside to this approach is that you can only store one "note" per branch. Subsequent branch-note calls with an argument will overwrite the previous branch-note. You also don't get the benefit of storing the message in a trackable git object but maybe it will suffice for your purposes.

Solution 2:

I like to make an empty commit whenever I create a new branch, with a commit message saying whatever needs to be said.

git branch B A
git checkout B
git commit --allow-empty -m "Created branch 'B' from 'A'"

This also has a wonderful side effect of making the history shown in "git log --graph" much clearer-- namely it shows a clearly labelled fork in the tree at the time I created the branch, instead of what I'd normally get which is an unclear unlabelled fork at some later time when I happen to make my first commit while in B-- that kind of thing keeps me in a constant fog.