Re: git branch descriptions

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Joel Reed wrote:

> Working on a wide range of topics/branches from week to week and
> project to project, it's sometimes difficult to quickly remember
> what each branch is about, without doing a git diff master <branch>.
>  I like to keep branch names short so they're easy to switch to and
> from, but being able to attach a description that would display when
> doing a "git branch" would be a huge help.

I think the closest thing we have now is ‘git branch -v’, which tells
the subject of the commit at the tip of the branch.  ‘git notes’
annotates commits rather than branches, so it occupies a different
niche.

Your request is a reasonable one, and it has come up a few times in
different forms over the years:

 . per-branch descriptions in .git/description[1]
 . per-branch descriptions in .git/config[2][3]
 . README branch whose files describe the branches[4]

Number [2] is my preferred choice (and comes with code!), for what
it’s worth.

That doesn’t address the problem of how to _share_ branch
descriptions.  That could be dealt with by extending the wire protocol
as in [1], I think.  Just sharing a list of branch descriptions is a
bad idea imho, since related repositories need to be able to name
their branches independently to avoid painful coordination problems.

> My only intention with this email is to say "thanks" and put in a
> vote for git branch descriptions.

The best vote is to write a sample script for yourself, try it out,
and tell us how it goes. :)

Thanks for bringing this up.
Jonathan

[1] http://thread.gmane.org/gmane.comp.version-control.git/8130/focus=8187
[2] http://thread.gmane.org/gmane.comp.version-control.git/33528/focus=33563
[3] http://thread.gmane.org/gmane.comp.version-control.git/46855/focus=47077
[4] http://thread.gmane.org/gmane.comp.version-control.git/93333/focus=93491