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\'

<

Answer 1

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.

Answer 2

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: Branch descriptions in git Can I add a message/note/comment when creating a new branch in Git?

Answer 3

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.

Answer 4

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.

Answer 5

No. Notes are attached to specific commit IDs.

Answer 6

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.