How do you annotate a branch?

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.

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.

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.

The correct answer to this is now branch descriptions, a feature which was added to git after this question was originally asked.

Here are two SO questions that come up with this answer: https://stackoverflow.com/questions/2108405/branch-descriptions-in-git https://stackoverflow.com/questions/11886132/can-i-add-a-message-note-comment-when-creating-a-new-branch-in-git

Using Brian's solution I've created git-note. You can use it like:

$ git note "Some note" # set note for current branch
$ git note -b branch # see note for branch
$ git note -l # list all the branches with theirs' notes

You could just create a "tracking bug" in your issue tracker where you describe the big new feature in great detail, with mockups and UML diagrams and everything, and then name the branch bug1234.

No. Notes are attached to specific commit IDs.

Using git tag --annotate tags with descriptions may be created.

The tag is technically attributed to a commit instead of a branch. If all collaborators agree on using the branch name (as part of) the tag name, the corresponding tag(s) to a branch can be listed using the branch name as part of a filter pattern. The -n option allows to show the actual annotation. Aliases may come handy in order to automatically use the current branch name for creating and listing special branch description tags.

Note 1: git describe may be used to find the most recent tag in a branch. Unfortunately this may list tags of other branches if they are merged into the branch of interest.

Note 2: It is not recommended to update a tag to HEAD manually using --force.

An advantage of using tags is that the description is available to all collaborators.