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.

Duplicate: http://stackoverflow.com/questions/2108405/branch-descriptions-in-git — William Pursell, Aug 19 '11 at 12:14
An aside: Long lived branches should be few and well-known like master or develop. I think if you have that many branches that you need to describe them, then it's likely you have a git flow problem or I am misunderstanding how you are using git. — datashaman, Dec 21 '16 at 10:44
Possible duplicate of [Branch descriptions in git](http://stackoverflow.com/questions/2108405/branch-descriptions-in-git) — phuclv, May 18 '17 at 04:25
@WilliamPursell If you still believe this Q is a duplicate, then vote again please. So that this doesn't age away. — imz -- Ivan Zakharyaschev, Jul 29 '21 at 19:49
@phuclv If you still believe this Q is a duplicate, then vote again please. So that this doesn't age away. — imz -- Ivan Zakharyaschev, Jul 29 '21 at 19:49

score 47 · Accepted Answer · edited Dec 19 '18 at 20:19

47

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.

edited Dec 19 '18 at 20:19

Soviut

88,194
49
192
260

answered Jan 21 '11 at 04:01

Brian Phillips

12,693
3
29
26

8

Will this note be pushed up to remote repositories? – Jason Axelson May 18 '11 at 20:14
11

No, since this is strictly a `git config` setting, it is not pushed/pulled anywhere (just like all of the rest of your configuration options). – Brian Phillips May 19 '11 at 17:34
16

nowadays there in an alias for this - `git branch --edit-description` - it's just that the property is "description", not "not" - git config branch..description will show that description. – shabunc Dec 10 '12 at 19:46
1

Hey @BrianPhillips, this works great for me... however, it does occasionally think the first word of my note is a command... git branch-note "Adding marketing login help contact option" => git config branch.$(git symbolic-ref HEAD|sed "s/refs\/heads\///").note $( if [ $# -gt 0 ]; then $1; fi): Adding: command not found – jffgrdnr Nov 18 '13 at 22:06
1

See this answer: http://stackoverflow.com/questions/2108405/branch-descriptions-in-git for git 1.7.9+ `git-branch --edit-description` to do exactly what you're asking for. – Tom Auger Feb 12 '16 at 16:33
1

As a parenthetical note, `git symbolic-ref --short HEAD` gets the branch name without having to use the `sed` pipeline. – NickD Oct 24 '17 at 09:31

score 17 · Answer 2 · answered Jul 15 '15 at 21:53

17

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.

answered Jul 15 '15 at 21:53

Don Hatch

5,041
3
31
48

4

How do you retrieve that text later on? – Yaza Jul 13 '17 at 14:07
1

One "odd" side effect of this is that your git log on master would contain that message after you merge that branch. – Zitrax Jan 24 '19 at 13:01

score 10 · Answer 3 · edited May 23 '17 at 12:02

10

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?

edited May 23 '17 at 12:02

Community

1
1

answered Mar 17 '16 at 14:47

skiphoppy

97,646
72
174
218

2

As pointed out by at least one person in each of those answer threads: that can't be pushed and is therefore useless, for me, anyway. – Don Hatch Jul 07 '16 at 03:33

score 4 · Answer 4 · answered Oct 17 '12 at 00:45

4

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

answered Oct 17 '12 at 00:45

rkj

8,787
2
29
35

Reading this comment 'Stores text note in local git repository config.' Am I correct in assuming this only works locally and someone getting from the remote repository won't see my changes? – David Sopko Dec 05 '18 at 22:41
@DavidSopko you can push/pull git notes so they can be seen by everyone. – Kevin Mar 15 '19 at 19:07

score 2 · Answer 5 · answered Jan 23 '11 at 21:30

2

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.

answered Jan 23 '11 at 21:30

Tyler

21,762
11
61
90

score 1 · Answer 6 · answered Jan 20 '11 at 18:16

1

No. Notes are attached to specific commit IDs.

answered Jan 20 '11 at 18:16

Simon Richter

28,572
1
42
64

score 1 · Answer 7 · answered Feb 10 '19 at 13:12

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.

wouldn't in also be sensible convention to say 'git tag --annotate startofbranch_branchname'? — grenix, Dec 14 '22 at 13:37

How do you annotate a branch?

7 Answers7

Linked

Related