git branch descriptions

git branch descriptions

[Joel Reed]

First, let me extend my thanks for a great version control tool. Git has enhanced my productivity tremendously - I appreciate the Git team's focus on performance, usability, and correctness. Awesome work.

I've used git in several jobs now and keep coming back to _really_ wishing I could attach a description to some of my branches. 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.

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

jr

Re: git branch descriptions

[Ramkumar Ramachandra]

Hi,

> I've used git in several jobs now and keep coming back to _really_ wishing I could attach a description to some of my branches. 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 git-notes(1) is the closest thing to what you want.

-- Ram

Re: git branch descriptions

[Jonathan Nieder]

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

Re: git branch descriptions

[Geert Bosch]

On May 10, 2010, at 19:26, Jonathan Nieder wrote:
> 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.

Indeed, I've not started to use the -v flag a lot more and wish
it were default. However, when I started to think about attaching
descriptions or any other information to branches, I started
to realize what we'd lose with that.
> 
> 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.

The question is what you'd do with these when moving branches around.
You could move the descriptions with the branches, though that would be
a bit ugly implementation-wise: I don't quite like the idea of programs
rewriting configuration files as part of regular operation.

Besides that, I find my self often use a workflow like:

% git checkout -b newtopic
% (hack, commit, hack, commit, ...)
% git log
% (oops, better fix up those revision histories)
% git checkout -b newtopic-fixup newtopic~2
% git cherry-pick newtopic~1 ; git commit --amend ; rinse ; repeat
% (ok, finished, pretend the old stuff never happened)
% git branch -M newtopic

If branches were more than just a way of naming a place to
put commits, it would be getting much more heaving to do this
kind of thing.

The other approach, of leaving them in place wouldn't be much
more appealing either.

It seems if we'd do branch descriptions at all, their main use
would be fore remote repositories. When you publish a branch,
you'd typically not rewrite it on a whim, so attaching a description
makes sense. Similarly, if you're tracking a remote repository,
it would be helpful to get some information for the branch.

For local repositories, I have been amazed how useful the git branch -v is.
And it comes for free, no need to enter any data!

Regards,
   -Geert

Re: git branch descriptions

[Michael J Gruber]

Jonathan Nieder venit, vidit, dixit 11.05.2010 01:26:
> 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.

I have a mostly working idea (working when done "manually") on how to
use notes for that. As we, know, we can share notes without overriding
our own notes (and improving the merge/combine facilities would benefit
all note users). I'll try to come up with a proof-of-concept patch, but
probably not before next week.

Michael

RE: git branch descriptions

[Joel Reed]

Jonathan Nieder 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.

I'm more looking for the description of the branch, not the last commit, but I did not know about this option and will give it a try. Thanks for the tip! 

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

My number one need is just to be able to add a description to local branches so I don't forget why I made them weeks later.

I have noticed when browsing around on gitweb/github looking at available branches that I sometimes wish I knew a bit more about the branch as well so I can see the need to see remote descriptions as well. Sharing the descriptions isn't of much interest to me personally.

jr

RE: git branch descriptions

[Joel Reed]

Geert Bosch wrote:

<snip>

> It seems if we'd do branch descriptions at all, their main use
> would be fore remote repositories. When you publish a branch,
> you'd typically not rewrite it on a whim, so attaching a description
> makes sense. Similarly, if you're tracking a remote repository,
> it would be helpful to get some information for the branch.

For my usage, I have to strongly disagree! I _primarily_ wish I could add a description to LOCAL branches.

jr

RE: git branch descriptions

[Joel Reed]

Michael J Gruber wrote:

<snip>

> > 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.
> 
> I have a mostly working idea (working when done "manually") on how to
> use notes for that. As we, know, we can share notes without overriding
> our own notes (and improving the merge/combine facilities would benefit
> all note users). I'll try to come up with a proof-of-concept patch, but
> probably not before next week.

Sounds awesome! If I can help test in anyway please let me know.

jr

Re: git branch descriptions

[Ævar Arnfjörð Bjarmason]

On Mon, May 10, 2010 at 14:56, Joel Reed <jreed@lantekcs.com> wrote:

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

Or you could just use long branch names coupled with bash completion
(or something like that) so it isn't hard to switch between branches
with long names.

I use branch names that are long enough so that I can tell what
they're for by looking at the name, using them isn't a pain due to
bash/magit completion.

RE: git branch descriptions

[Joel Reed]

Ævar Arnfjörð Bjarmason wrote:

> > 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.
> 
> Or you could just use long branch names coupled with bash completion
> (or something like that) so it isn't hard to switch between branches
> with long names.
> 
> I use branch names that are long enough so that I can tell what
> they're for by looking at the name, using them isn't a pain due to
> bash/magit completion.

Good point, perhaps for now I should use branch.names.like.this

jr