threads / discuss / 23765

git branch descriptions

Subject: git branch descriptions

## tl;dr

10 messages between May 10, 2010 and May 11, 2010.

replies: 9people: 6as markdown or json

Joel Reed· May 10, 2010, 14:56 UTC · lore
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
Ramkumar Ramachandra· May 10, 2010, 15:08 UTC · re: Joel Reed · lore

Re: git branch descriptions

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
Jonathan Nieder· May 10, 2010, 23:26 UTC · re: Joel Reed · lore

Re: git branch descriptions

Hi,
Joel Reed wrote:
Show 6 quoted lines
> 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

Geert Bosch· May 11, 2010, 01:16 UTC · re: Jonathan Nieder · lore

Re: git branch descriptions

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.

Show 10 quoted lines
> 
> 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
Joel Reed· May 11, 2010, 12:38 UTC · re: Geert Bosch · lore

RE: git branch descriptions

Geert Bosch wrote:
<snip>
Show 5 quoted lines
> 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
Michael J Gruber· May 11, 2010, 07:44 UTC · re: Jonathan Nieder · lore

Re: git branch descriptions

Jonathan Nieder venit, vidit, dixit 11.05.2010 01:26:
Show 31 quoted lines
> 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
Joel Reed· May 11, 2010, 12:39 UTC · re: Michael J Gruber · lore

RE: git branch descriptions

Michael J Gruber wrote:
<snip>
Show 21 quoted lines
> > 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
Joel Reed· May 11, 2010, 12:33 UTC · re: Jonathan Nieder · lore

RE: git branch descriptions

Jonathan Nieder wrote:
Show 11 quoted lines
> > 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!
Show 9 quoted lines
> 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
Ævar Arnfjörð Bjarmason· May 11, 2010, 12:54 UTC · re: Joel Reed · lore

Re: git branch descriptions

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.

Joel Reed· May 11, 2010, 12:58 UTC · re: Ævar Arnfjörð Bjarmason · lore

RE: git branch descriptions

Ævar Arnfjörð Bjarmason wrote:
Show 11 quoted lines
> > 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

← back to recent threads