git - How do you annotate a branch?

Question

Is there any way to annotate a branch? It would be nice to be able to do something like:

$ git notes add branch-name -m 'This branch is for whatever'

but that of course is not terribly helpful, since the note applies to the current head of the branch rather than the branch itself.

An easy workaround is to drop a README.branch-name in the repository, but that seems clumsy. Slightly more elegant is to have an orphaned branch containing nothing but README.branch-names. I'm looking for a way to record what the purpose of the branch is other than just putting it in the commit message for the "first" commit of the branch. I put "first" in quotes because it's not always clear what is meant by that, which is the reason it is inconvenient to put the discussion in a commit message. It's often difficult to find the commit in which such a message is recorded.

Answer 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.