Re: branch description

Re: branch description

[Michael Dressel]

On Friday 18 April 2008, Jakub Narebski wrote:
> Let me sum up here proposals where to put branch description:

what's the opinion of having a new branch object? Actually the tag object 
probably already does the job? This would spoil the elegant light weight 
current branch references. But tags are not that heavy.

In this approach the tags would not reference commits but tags. And tags 
have annotation. The difference to the normal tags would be that these 
tags are referenced from refs/heads/<branch> instead of refs/tags.

I have no clue how involved this change would become and if the benefit 
would justify the effort. I guess using proper objects for branches 
would only be justified if additional advantages could be achieved.

Cheers,
 	Michael

Re: branch description

[Johan Herland]

On Tuesday 22 April 2008, Michael Dressel wrote:
> On Friday 18 April 2008, Jakub Narebski wrote:
> > Let me sum up here proposals where to put branch description:
>
> what's the opinion of having a new branch object? Actually the tag
> object probably already does the job? This would spoil the elegant
> light weight current branch references. But tags are not that heavy.
>
> In this approach the tags would not reference commits but tags. And
> tags have annotation. The difference to the normal tags would be that
> these tags are referenced from refs/heads/<branch> instead of
> refs/tags.
>
> I have no clue how involved this change would become and if the
> benefit would justify the effort. I guess using proper objects for
> branches would only be justified if additional advantages could be
> achieved.
>
> Cheers,
>  	Michael

Nice idea, but it won't work, simply because branches are moving
targets, whereas tags are not.

To illustrate, here's how things are structured between the refs
(tags/branches) and the object DB:


refs/tags/lighweight  -------------------------> [commit object]

refs/tags/annotated   -----> [tag object] -----> [commit object]

refs/heads/branchname -------------------------> [commit object]


The annotated tag ref holds the SHA1 of the tag object which in turn
holds the SHA1 of the commit object, while the two other ref types
point directly at a commit object. The tag object works on the
assumption that the commit object pointed to by the tag never changes.
That's after all the whole point of a tag.

A branch - on the other hand - is _supposed_ to change. It changes by
adding a new commit on top of the current commit, and updating the
branch ref to point to the new commit. If we kept the branch description
in a tag object, and stuck this between the branch ref and the commit
object, we would suddenly have to rewrite the tag object every time we
added another commit on the branch. This would make commits much more
expensive, not to mention that for every commit you would drop the
tag object pointing to the previous commit, in effect generating one
garbage object per commit. This is clearly not what we want.


...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: branch description

[Jakub Narebski]

Michael Dressel <MichaelTiloDressel@t-online.de> writes:

> On Friday 18 April 2008, Jakub Narebski wrote:

> > Let me sum up here proposals where to put branch description:
> >
> > [...]
> 
> what's the opinion of having a new branch object? Actually the tag
> object probably already does the job? This would spoil the elegant
> light weight current branch references. But tags are not that heavy.
> 
> In this approach the tags would not reference commits but tags. And
> tags have annotation. The difference to the normal tags would be that
> these tags are referenced from refs/heads/<branch> instead of
> refs/tags.
> 
> I have no clue how involved this change would become and if the
> benefit would justify the effort. I guess using proper objects for
> branches would only be justified if additional advantages could be
> achieved.

This won't work.  With described (annotated) branches, there are two
pieces of data associated with a branch:
 * commit it points to (branch head)
 * description of a branch

Branch head changes frequently (commit, reset, bisect, rebase), while
description should change rarely.  Those two pieces of data are
independent.  Tag object would unnecessary join/fuse those two
together.


Also, for exach commit on a branch, or for each moving of branch ref
(reset, amend, bisect), you would have to create tag object, which
would accumulate only to be garbage collected some time in the
future...

-- 
Jakub Narebski
Poland
ShadeHawk on #git

branch description

[Stephen Sinclair]

Hi,

I find it useful to use fairly short names for branches.  However,
sometimes I would like to have a full sentence to actually describe
what the branch is for, without having the peruse the actual commits.

This is both for when I later can't remember why I made a certain
branch, or for when people clone and look at a list of branches
wondering what the differences are between them.

This information could of course be kept on a web page, but it would
be nice to have it in the repo.
Is there any such branch annotation command?
Ideally I'd like to see a sentence displayed next to the branch name
when I use "git-branch".
Perhaps, git-branch --info or something.


Steve

Re: branch description

[Russ Dill]

>  I find it useful to use fairly short names for branches.  However,
>  sometimes I would like to have a full sentence to actually describe
>  what the branch is for, without having the peruse the actual commits.

Me too.

>  This information could of course be kept on a web page, but it would
>  be nice to have it in the repo.

Like, putting your bug number in the branch name.

>  Is there any such branch annotation command?
>  Ideally I'd like to see a sentence displayed next to the branch name
>  when I use "git-branch".
>  Perhaps, git-branch --info or something.

The problem is that a branch is just a floating name for a line of
development. Its not really a "thing" in the repository like a tag or
a commit. You'd need to make some sort of special tag that describes
the branch or somesuch.

Re: branch description

[Brian Gernhardt]

On Apr 15, 2008, at 1:31 PM, Russ Dill wrote:

> The problem is that a branch is just a floating name for a line of
> development. Its not really a "thing" in the repository like a tag or
> a commit. You'd need to make some sort of special tag that describes
> the branch or somesuch.

No special tags needed.  A simple file that I'll call .git/info/ 
ref_names could be a set of lines that have "<ref>\t<description>",  
like the following:

refs/heads/master	Collection point for all my work
refs/heads/ref_names	Add descriptions for branches
refs/heads/segfault	Trying to fix bug #12345

Simple, no tags, new object types or anything.  All you have to do is  
add the bits to git-branch to add, edit, and remove the description  
alongside the branch itself.

Now if you want to propagate these descriptions when you push and  
pull, things get a lot more complicated.

~~ Brian

Re: branch description

[Junio C Hamano]

Brian Gernhardt <benji@silverinsanity.com> writes:

> On Apr 15, 2008, at 1:31 PM, Russ Dill wrote:
>
>> The problem is that a branch is just a floating name for a line of
>> development. Its not really a "thing" in the repository like a tag or
>> a commit. You'd need to make some sort of special tag that describes
>> the branch or somesuch.
>
> No special tags needed.  A simple file that I'll call .git/info/
> ref_names could be a set of lines that have "<ref>\t<description>",
> like the following:
>
> refs/heads/master	Collection point for all my work
> refs/heads/ref_names	Add descriptions for branches
> refs/heads/segfault	Trying to fix bug #12345
>
> Simple, no tags, new object types or anything.  All you have to do is
> add the bits to git-branch to add, edit, and remove the description
> alongside the branch itself.
>
> Now if you want to propagate these descriptions when you push and
> pull, things get a lot more complicated.

Not complicated at all.  Put that description in-tree in a known location
(say, "help-branch") in-tree and your propagation problem is solved.

And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.

Re: branch description

[Jeff King]

On Tue, Apr 15, 2008 at 12:12:16PM -0700, Junio C Hamano wrote:

> > No special tags needed.  A simple file that I'll call .git/info/
> > ref_names could be a set of lines that have "<ref>\t<description>",
> > like the following:
> >
> > refs/heads/master	Collection point for all my work
> > refs/heads/ref_names	Add descriptions for branches
> > refs/heads/segfault	Trying to fix bug #12345
> >
> > Simple, no tags, new object types or anything.  All you have to do is
> > add the bits to git-branch to add, edit, and remove the description
> > alongside the branch itself.
> 
> Not complicated at all.  Put that description in-tree in a known location
> (say, "help-branch") in-tree and your propagation problem is solved.
>
> And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.

It is perhaps a little slow if you want to do things like adding the
help text to branch name decorations in log output. Maybe instead of a
flat file, you could parallel the ref name hierarchy in a tree? I.e.,

  git checkout help-branch
  echo 'Collection point for all my work' >refs/heads/master
  git commit -a

As a bonus, you don't even need a git-help-branch script:

  git show help-branch:refs/heads/master

And if you have more than one person tweaking the help-branch text,
merging will be much less painful.

-Peff

Re: branch description

[Jeff King]

On Tue, Apr 15, 2008 at 03:19:30PM -0400, Jeff King wrote:

> > Not complicated at all.  Put that description in-tree in a known location
> > (say, "help-branch") in-tree and your propagation problem is solved.
> >
> > And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.
> 
> It is perhaps a little slow if you want to do things like adding the
> help text to branch name decorations in log output. Maybe instead of a
> flat file, you could parallel the ref name hierarchy in a tree? I.e.,

It occurred to me that you actually meant "just stick it in a file in
your actual work tree", not on a separate branch (for some reason,
reading the name "help-branch" made me think you meant a ref).

So that is obviously the very simple solution. But for fun, and because
maybe somebody could learn something, here is a script implementing my
approach. I dunno if it is worth including in contrib.

-- >8 --
contrib: add git-refinfo

This is a cute hack to show one possible way of storing ref
descriptions. It might be useful to somebody. It also serves
as a relatively short and simple example of how to script
git.

Signed-off-by: Jeff King <peff@peff.net>
---
 contrib/examples/git-refinfo.sh |   87 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 87 insertions(+), 0 deletions(-)
 create mode 100755 contrib/examples/git-refinfo.sh

diff --git a/contrib/examples/git-refinfo.sh b/contrib/examples/git-refinfo.sh
new file mode 100755
index 0000000..b79a20f
--- /dev/null
+++ b/contrib/examples/git-refinfo.sh
@@ -0,0 +1,87 @@
+#!/bin/sh
+#
+# git-refinfo: a ref-description mechanism
+#
+# git-refinfo maintains a mapping of refnames to descriptions;
+# it stores the mapping as a version-controlled tree. Each
+# path in the tree represents a ref name, and the contents of
+# that path are the description.
+#
+# That means you can either use git-refinfo to set or examine
+# ref descriptions, or you can simply "git checkout refinfo"
+# and view and edit the files directly.
+
+REFINFO=refs/heads/refinfo
+SUBDIRECTORY_OK=Yes
+USAGE='
+git-refinfo set [<ref>] <description>
+git-refinfo get [<ref> ...]'
+. git-sh-setup
+
+die_usage() {
+	echo >&2 "usage: $USAGE"
+	exit 1
+}
+
+full_ref() {
+	git show-ref "$1" | sed -e 's/^[^ ]* //' -e '1q'
+}
+
+heads() {
+	git show-ref --heads | sed 's/.*refs\/heads\///'
+}
+
+do_get() {
+	ref=`full_ref "$1"`
+	case "$ref" in
+	'') desc= ;;
+	 *) desc=`git cat-file blob "$REFINFO:$ref" 2>/dev/null` ;;
+	esac
+	printf '%s\t%s\n' "$1" "$desc"
+}
+
+do_set() {
+	ref=`full_ref "$1"`
+	case "$ref" in
+	'')
+		case "$1" in
+		refs/*) ref=$1 ;;
+		heads/*) ref=refs/$1 ;;
+		*) ref=refs/heads/* ;;
+		esac
+		;;
+	esac
+	GIT_INDEX_FILE=$GIT_DIR/refinfo-index; export GIT_INDEX_FILE
+	rm -f $GIT_INDEX
+	old=`git rev-parse --verify $REFINFO 2>/dev/null`
+	case "$old" in
+	'') parents= ;;
+	 *) parents="-p $old"; git read-tree $REFINFO ;;
+	esac
+	blob=`printf '%s\n' "$2" | git hash-object -w --stdin`
+	git update-index --add --cacheinfo 0644 $blob "$ref"
+	tree=`git write-tree`
+	commit=`echo "update $1" | git commit-tree $tree $parents`
+	git update-ref -m refinfo $REFINFO $commit $old
+}
+
+case "$1" in
+set)
+	shift
+	case "$#" in
+	1) do_set "`git symbolic-ref HEAD`" "$1" ;;
+	2) do_set "$1" "$2" ;;
+	*) die_usage ;;
+	esac
+	;;
+get)
+	shift
+	case "$#" in
+	0) for i in `heads`; do do_get "$i"; done ;;
+	*) for i in "$@"; do do_get "$i"; done ;;
+	esac
+	;;
+*)
+	die_usage
+esac
+exit 0
-- 
1.5.5.63.g4e41c

Re: branch description

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Apr 15, 2008 at 03:19:30PM -0400, Jeff King wrote:
>
>> > Not complicated at all.  Put that description in-tree in a known location
>> > (say, "help-branch") in-tree and your propagation problem is solved.
>> >
>> > And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.
>> 
>> It is perhaps a little slow if you want to do things like adding the
>> help text to branch name decorations in log output. Maybe instead of a
>> flat file, you could parallel the ref name hierarchy in a tree? I.e.,
>
> It occurred to me that you actually meant "just stick it in a file in
> your actual work tree", not on a separate branch (for some reason,
> reading the name "help-branch" made me think you meant a ref).
>
> So that is obviously the very simple solution. But for fun, and because
> maybe somebody could learn something, here is a script implementing my
> approach. I dunno if it is worth including in contrib.

Another independent approach I was very tempted to suggest was to mimick
how "What's cooking" has been maintained over time (in other words, what I
describe here is a toolset that has proven to be viable and useful, backed
by the real world experience ;-).

All the tools I use for this are stored in my 'todo' branch, and I have a
checkout of the 'todo' branch in Meta/ subdirectory.

The core workhorse of this toolset is "Meta/topic.perl" script.  It lists
topic branches, and shows the list of commits on each branch that are
still not integrated in the final integration branch.  The script has a
built-in assumption of how the topic branches are named, and what
integration branches there are (namely, 'master', 'next' and 'pu'), but it
should not be too hard if somebody wants to generalize it to have more
than two "still cooking" stages and how they are named.

The' topic' script is called by "Meta/WC" script (obviously, that stands
for "What's Cooking") that applies a slight formatting of its output.
There isn't much to see in this intermediate script.

When I send out a new edition of "What's cooking", I feed the previous
edition of the message to "Meta/UWC" ("Update What's Cooking") script.

This script:

 - reads the old edition from its standard input, to remember the commits
   and explanatory text associated with each topic in the previous round;

 - reads from the "Meta/WC" output to learn the commits that currently
   reside in each topic;

 - compares the above two, insert new branches into "[New topics]"
   section, and mark the changed topics.

 - outputs the new edition to the standard output.

Then I can add descriptions for new topics, edit them for the ones whose
status have changed.

I do not personally keep any temporary or in-tree copies, because I happen
to do all the above in my MUA edit buffer.  But if I wanted to, I could
use one in-tree file dedicated for it and track it as part of the
contents.

Re: branch description

[Stephen Sinclair]

On Tue, Apr 15, 2008 at 3:12 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
>  Not complicated at all.  Put that description in-tree in a known location
>  (say, "help-branch") in-tree and your propagation problem is solved.
>
>  And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.

Hm, I wasn't sure if an in-tree solution would be appropriate.
It's possible, but I didn't really want this branch description to be
something I have to deal with when merging..
Ideally though this information _should_ be propagated through a
clone, so something in-tree might make sense.

When I posted I thought perhaps there was already a way to do this
that I hadn't encountered.
Perhaps there could be an in-tree file .gitbranch that is simply a
name:description pair, "git-branch --info" (or whatever) could be made
to know how to parse that file if it exists.

However I was hoping that the branch description could be made when
creating the branch, instead of having to associate it with an actual
commit.

I don't know, I'll give it some thought and try to come up with a more
concrete proposal.


Steve

Re: branch description

[Brian Gernhardt]

On Apr 15, 2008, at 4:53 PM, Stephen Sinclair wrote:

> On Tue, Apr 15, 2008 at 3:12 PM, Junio C Hamano <gitster@pobox.com>  
> wrote:
>>
>> Not complicated at all.  Put that description in-tree in a known  
>> location
>> (say, "help-branch") in-tree and your propagation problem is solved.
>>
>> And have a scriptlet in $HOME/bin/git-help-branch to grep from that  
>> file.
>
> Hm, I wasn't sure if an in-tree solution would be appropriate.
> It's possible, but I didn't really want this branch description to be
> something I have to deal with when merging..
> Ideally though this information _should_ be propagated through a
> clone, so something in-tree might make sense.
>
> When I posted I thought perhaps there was already a way to do this
> that I hadn't encountered.
> Perhaps there could be an in-tree file .gitbranch that is simply a
> name:description pair, "git-branch --info" (or whatever) could be made
> to know how to parse that file if it exists.
>
> However I was hoping that the branch description could be made when
> creating the branch, instead of having to associate it with an actual
> commit.

A random thought:

refs/info/heads/help is a pointer to a blob that is full of name- 
description pairs.  Instead of a full ref name it simply keeps the  
portion for a given subdirectory.  On a pull, you can add refs/info/ 
heads/help:refs/info/remote/origin/help.  Each subdirectory of refs  
gets it's own help blob.  You may need to deal with merging on pull,  
but it keeps the information separate from the commits and still pull/ 
pushable.

~~ Brian

Re: branch description

[Jakub Narebski]

Junio C Hamano <gitster@pobox.com> writes:

> Brian Gernhardt <benji@silverinsanity.com> writes:
> 
>> On Apr 15, 2008, at 1:31 PM, Russ Dill wrote:
>>
>>> The problem is that a branch is just a floating name for a line of
>>> development. Its not really a "thing" in the repository like a tag or
>>> a commit. You'd need to make some sort of special tag that describes
>>> the branch or somesuch.
>>
>> No special tags needed.  A simple file that I'll call .git/info/
>> ref_names could be a set of lines that have "<ref>\t<description>",
>> like the following:
>>
>> refs/heads/master	Collection point for all my work
>> refs/heads/ref_names	Add descriptions for branches
>> refs/heads/segfault	Trying to fix bug #12345
[...]
>> Now if you want to propagate these descriptions when you push and
>> pull, things get a lot more complicated.
> 
> Not complicated at all.  Put that description in-tree in a known location
> (say, "help-branch") in-tree and your propagation problem is solved.
> 
> And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.

Please, let's don't repeat Mercurial mistake of placing unversioned
information (such as branch names in case of Mercurial, or branches
descriptions in this case) in-tree, i.e. version it.  Think of what
would happen if you reset to the state (or checkout to some branch
with the state) which is before some branch was created, or before
some branch got description.  Mercurial deals with this using
"special" not lika in-tree treatment of such a file... I don't think
it is a good idea.

I think it wouldb be better to put branches descriptions somewhere
outside object repository, be it .git/info/ref_names of .git/config.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: branch description

[Jeff King]

On Tue, Apr 15, 2008 at 06:33:48PM -0700, Jakub Narebski wrote:

> Please, let's don't repeat Mercurial mistake of placing unversioned
> information (such as branch names in case of Mercurial, or branches
> descriptions in this case) in-tree, i.e. version it.  Think of what
> would happen if you reset to the state (or checkout to some branch
> with the state) which is before some branch was created, or before
> some branch got description.  Mercurial deals with this using
> "special" not lika in-tree treatment of such a file... I don't think
> it is a good idea.

I think that is a reasonable argument.

> I think it wouldb be better to put branches descriptions somewhere
> outside object repository, be it .git/info/ref_names of .git/config.

But you make a jump in logic here when you make the alternative to put
it outside the object repository. Your first point argues against
versioning meta-information _along with the rest of the state_, but
there's no reason it can't be versioned separately (e.g., in another
branch that just has such meta-info).

-Peff

Re: branch description

[Stephen Sinclair]

On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski <jnareb@gmail.com> wrote:
>   (such as branch names in case of Mercurial, or branches
>  descriptions in this case)

This got me thinking...
It's a little crazy, but: since branch descriptions would essentially
just be an extension of the branch name, play basically the same role
and have the same requirements for storage, cloning, etc., what about
using some syntax in the branch name itself to separate a "short name"
and a "long name"..

That is, you could store it as,
refs/heads/wip:work_in_progress

and git-branch would report,

wip

while git-branch --long would report the long names,

wip:work_in_progress

or could parse it to something more legible:

wip     "Work in progress"

Of course this would require modification to refspec-related code,
which is likely more work than it's worth..
Hm, well just an idea anyways.  Probably not a good idea to save
meta-data in a filename.


Steve

Re: branch description

[Mike Hommey]

On Tue, Apr 15, 2008 at 11:28:49PM -0400, Stephen Sinclair wrote:
> On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> >   (such as branch names in case of Mercurial, or branches
> >  descriptions in this case)
> 
> This got me thinking...
> It's a little crazy, but: since branch descriptions would essentially
> just be an extension of the branch name, play basically the same role
> and have the same requirements for storage, cloning, etc., what about
> using some syntax in the branch name itself to separate a "short name"
> and a "long name"..
> 
> That is, you could store it as,
> refs/heads/wip:work_in_progress

Why not simply add the text after the sha1 in the refs/heads/branch_name
file ? Obviously current and older git code should be checked to know
whether they could cope with the extra data without failing...

This would also have the advantage that renaming the branch would not
lose the description.

Mike

Re: branch description

[Matt Graham]

On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>  > Brian Gernhardt <benji@silverinsanity.com> writes:
>  >
>  >> On Apr 15, 2008, at 1:31 PM, Russ Dill wrote:
>  >>
>  >>> The problem is that a branch is just a floating name for a line of
>  >>> development. Its not really a "thing" in the repository like a tag or
>  >>> a commit. You'd need to make some sort of special tag that describes
>  >>> the branch or somesuch.
>  >>
>  >> No special tags needed.  A simple file that I'll call .git/info/
>  >> ref_names could be a set of lines that have "<ref>\t<description>",
>  >> like the following:
>  >>
>  >> refs/heads/master    Collection point for all my work
>  >> refs/heads/ref_names Add descriptions for branches
>  >> refs/heads/segfault  Trying to fix bug #12345
>  [...]
>
> >> Now if you want to propagate these descriptions when you push and
>  >> pull, things get a lot more complicated.
>  >
>  > Not complicated at all.  Put that description in-tree in a known location
>  > (say, "help-branch") in-tree and your propagation problem is solved.
>  >
>  > And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.
>
>  Please, let's don't repeat Mercurial mistake of placing unversioned
>  information (such as branch names in case of Mercurial, or branches
>  descriptions in this case) in-tree, i.e. version it.  Think of what
>  would happen if you reset to the state (or checkout to some branch
>  with the state) which is before some branch was created, or before
>  some branch got description.  Mercurial deals with this using
>  "special" not lika in-tree treatment of such a file... I don't think
>  it is a good idea.
>
>  I think it wouldb be better to put branches descriptions somewhere
>  outside object repository, be it .git/info/ref_names of .git/config.

I agree that outside the object repository would be better.
Propogating branch descriptions doesn't seem all that useful.  I
wouldn't usually expect to want a branch for the same purpose as the
upstream repository and it would seem weird to get a default
description of it coming along with the branch.  Just like I give my
branches my own name, I would expect to have to give them my own
description.

Re: branch description

[Johan Herland]

On Wednesday 16 April 2008, Matt Graham wrote:
> On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> >  I think it wouldb be better to put branches descriptions somewhere
> >  outside object repository, be it .git/info/ref_names of .git/config.
> 
> I agree that outside the object repository would be better.
> Propogating branch descriptions doesn't seem all that useful.  I
> wouldn't usually expect to want a branch for the same purpose as the
> upstream repository and it would seem weird to get a default
> description of it coming along with the branch.  Just like I give my
> branches my own name, I would expect to have to give them my own
> description.

On the contrary, when I clone/pull from some repo, I would very much like to
have a copy of its branch description stored locally. Of course, these
descriptions should be renamed along with their corresponding branch upon
entering my repo. To illustrate: Suppose I clone/pull "refs/heads/foo" from
a remote repo "bob". The branch will be stored as "refs/remotes/bob/foo" in
my repo. Now, if "refs/heads/foo" on "bob" has a branch description, I would
like to have that branch description copied into my repo, but referring to
"refs/remotes/bob/foo" instead of "refs/heads/foo", of course.

Now, when it comes to my own local branches, I agree with you: If I make a
new local branch "refs/heads/foo" that tracks "refs/remotes/bob/foo", I will
probably not want git to copy the branch description automatically.

However, I do agree that putting branch description inside the working tree
is not the right solution. So far, the best proposal I've seen, is Hommey's
suggestion of storing the description after the sha1 in the ref file itself.
Of course, git would have to be taught (a) to handle ref files with
descriptions, and (b) to propagate descriptions along with refs.


...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: branch description

[Jakub Narebski]

On Wed, 16 April 2008, Johan Herland wrote:

[cut that being able to propagate description of branches is a good idea]

> However, I do agree that putting branch description inside the working tree
> is not the right solution. So far, the best proposal I've seen, is Hommey's
> suggestion of storing the description after the sha1 in the ref file itself.
> Of course, git would have to be taught (a) to handle ref files with
> descriptions, and (b) to propagate descriptions along with refs.

(c) find a place for branch descriptions in packed refs.


Let me sum up here proposals where to put branch description:
1. Put them in branch.<name>.description in repository config. Not easily
   (automatically) propagated for dumb transports.
2. Put them in-tree, which is a bad idea because branches are
   un-versioned (or versioned separately), so branches description
   should also be un-versioned.
3. Put them in GIT_DIR/info/refs_description, in some format.  It makes
   it very easy to add support for propagation for dumb transports.
   Native transport probably would need some extension.  Should not
   interfere with the rest of git code.
4. Store description after sha1 in the ref file itself.  Automatic
   propagation for dumb transport (whether we want it or not).  Native
   transport as above.  Very high probabily of interfering with the rest
   of code, especially shell part of Git.  Need to find a place for
   descriptions in pack-refs.
5. Store them as value of 'refs/heads/<branch>' file in a tree for
   a commit for a special '<description>' separate special branch; at least
   if I understand this proposal correctly.  Something like IIRC the
   'notes' / 'annotations' idea was implemented (on git mailing list;
   it never got into mainline).


I think that the best proposal is (3), not (4) as you say.
-- 
Jakub Narebski
Poland

Re: branch description

[Johan Herland]

On Friday 18 April 2008, Jakub Narebski wrote:
> On Wed, 16 April 2008, Johan Herland wrote:
> > So far, the best proposal I've seen, is Hommey's suggestion of storing
> > the description after the sha1 in the ref file itself. 
> > Of course, git would have to be taught (a) to handle ref files with
> > descriptions, and (b) to propagate descriptions along with refs.
> 
> (c) find a place for branch descriptions in packed refs.

This shouldn't be too hard. Today, we already have one kind of "special"
lines in the packed-refs format: "peeled", which uses lines starting with
"^". I think we could add another special kind of line called "description"
which uses lines starting with "#". Multiline descriptions (if we want to
support such) would just have "#" prepended to each line, and the parser
would associate all "#"-lines with the most recently parsed ref (like it
does for the "^"-line today).

> Let me sum up here proposals where to put branch description:
> 1. Put them in branch.<name>.description in repository config. Not easily
>    (automatically) propagated for dumb transports.
> 2. Put them in-tree, which is a bad idea because branches are
>    un-versioned (or versioned separately), so branches description
>    should also be un-versioned.
> 3. Put them in GIT_DIR/info/refs_description, in some format.  It makes
>    it very easy to add support for propagation for dumb transports.
>    Native transport probably would need some extension.  Should not
>    interfere with the rest of git code.
> 4. Store description after sha1 in the ref file itself.  Automatic
>    propagation for dumb transport (whether we want it or not).  Native
>    transport as above.  Very high probabily of interfering with the rest
>    of code, especially shell part of Git.  Need to find a place for
>    descriptions in pack-refs.
> 5. Store them as value of 'refs/heads/<branch>' file in a tree for
>    a commit for a special '<description>' separate special branch; at
>    least if I understand this proposal correctly.  Something like IIRC
>    the 'notes' / 'annotations' idea was implemented (on git mailing list;
>    it never got into mainline).
> 
> 
> I think that the best proposal is (3), not (4) as you say.

The problem with (3) vs. (4) is that in (3) we must make sure that whenever
a branch is moved/renamed (e.g. "git clone", "git branch -m", probably more
as well), the corresponding description is moved/renamed as well. This is
elegantly solved in (4). But as you say, (4) may have implementation
difficulties of its own. I guess the first acceptable implementation will
win.


Have fun!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: branch description

[Junio C Hamano]

Johan Herland <johan@herland.net> writes:

> The problem with (3) vs. (4) is that in (3) we must make sure that whenever
> a branch is moved/renamed (e.g. "git clone", "git branch -m", probably more
> as well), the corresponding description is moved/renamed as well. This is
> elegantly solved in (4).

If your "elegently solved" is coming from an assumption that it is enough
for "git mv" (for example) to just copy whatever is in .git/refs/heads/foo
to .git/refs/heads/bar without understanding what is contained in it, that
assumption unfortunately does not hold.

You must support packed refs, so you need to teach the refs infrastructure
what per-branch attributes there are other than the commit object name it
points at anyway.

And we already do -- when you do "branch -m foo bar", corresponding config
entries are also renamed.  We also move reflogs.

A possible approach that would work, which contains elements from (4), is
to change implementations of loose ref to have this extra info in loose
ref files (that is what (4) is), *and* introduce another separate
mechanism to store corresponding information for packed refs elsewhere.
Propagation needs to deal with both representations, renaming needs to
deal with both representations, looking up needs to deal with both
representations, everybody needs to deal with both representations.

If you are going to invent "another separate mechanism" to support packed
refs anyway, why not use that same mechanism to record information for
loose ones as well?  That is the approach suggested by (3).  In either way
we need to teach relevant parts of the code for propagation, renaming,
looking up etc about the new mechanism.

Re: branch description

[Johan Herland]

On Saturday 19 April 2008, Junio C Hamano wrote:
> Johan Herland <johan@herland.net> writes:
> 
> > The problem with (3) vs. (4) is that in (3) we must make sure that whenever
> > a branch is moved/renamed (e.g. "git clone", "git branch -m", probably more
> > as well), the corresponding description is moved/renamed as well. This is
> > elegantly solved in (4).
> 
> If your "elegently solved" is coming from an assumption that it is enough
> for "git mv" (for example) to just copy whatever is in .git/refs/heads/foo
> to .git/refs/heads/bar without understanding what is contained in it, that
> assumption unfortunately does not hold.
> 
> You must support packed refs, so you need to teach the refs infrastructure
> what per-branch attributes there are other than the commit object name it
> points at anyway.
> 
> And we already do -- when you do "branch -m foo bar", corresponding config
> entries are also renamed.  We also move reflogs.
> 
> A possible approach that would work, which contains elements from (4), is
> to change implementations of loose ref to have this extra info in loose
> ref files (that is what (4) is), *and* introduce another separate
> mechanism to store corresponding information for packed refs elsewhere.
> Propagation needs to deal with both representations, renaming needs to
> deal with both representations, looking up needs to deal with both
> representations, everybody needs to deal with both representations.
> 
> If you are going to invent "another separate mechanism" to support packed
> refs anyway, why not use that same mechanism to record information for
> loose ones as well?  That is the approach suggested by (3).  In either way
> we need to teach relevant parts of the code for propagation, renaming,
> looking up etc about the new mechanism.

You're right. Also, after thinking some more about this, it occured to me
that most code paths will probably _not_ be interested in branch
descriptions at all. It therefore makes sense to keep the descriptions away
from the refs themselves, so that they don't impact performance.

So #3 (keeping descriptions in $GIT_DIR/info/refs_description) is probably
the best solution.


Have fun! :)

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: branch description

[Jakub Narebski]

On Sat, 19 April 2008, Johan Herland wrote:
> On Friday 18 April 2008, Jakub Narebski wrote:

>> Let me sum up here proposals where to put branch description:
[...]
>> 3. Put them in GIT_DIR/info/refs_description, in some format.  It makes
>>    it very easy to add support for propagation for dumb transports.
>>    Native transport probably would need some extension.  Should not
>>    interfere with the rest of git code.
>> 4. Store description after sha1 in the ref file itself.  Automatic
>>    propagation for dumb transport (whether we want it or not).  Native
>>    transport as above.  Very high probabily of interfering with the rest
>>    of code, especially shell part of Git.  Need to find a place for
>>    descriptions in pack-refs.
[...]
>> 
>> I think that the best proposal is (3), not (4) as you say.
> 
> The problem with (3) vs. (4) is that in (3) we must make sure that whenever
> a branch is moved/renamed (e.g. "git clone", "git branch -m", probably more
> as well), the corresponding description is moved/renamed as well. This is
> elegantly solved in (4). But as you say, (4) may have implementation
> difficulties of its own. I guess the first acceptable implementation will
> win.

First, git already has move corresponding reflog and per-branch
configuration when renaming a branch, so it is nothing new for (3).

Second, implementation difficulties of (4) might be made stronger by
the fact that repository with branches with descriptions should be
fetchable and clonable using both native and dumb protocols by older
versions of git, and shouldn't cause troubles after fetching.  (Assume
that git is new enough to understand packed refs).  Backward
compatibility might kill this solution; but it might not.

BTW. I have added line with description to loose ref, and a few
commands I tried didn't return (cause) any errors... so...
-- 
Jakub Narebski
Poland

Re: branch description

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Please, let's don't repeat Mercurial mistake of placing unversioned
> information (such as branch names in case of Mercurial, or branches
> descriptions in this case) in-tree, i.e. version it.

Is it really a "mistake" in Mercurial's context?

I thought that their named branches do have defined "starting point", and
it is not a mistake at all for them to version "from this point on, this
lineage of history is associated with this symbolic name (which is a
branch)".

It probably does not make sense in the context of git where a branch is
defined to be "illusion" (at least currently).

Re: branch description

[Jakub Narebski]

On Wed, 16 April 2008, Junio C Hamano <gitster@pobox.com> wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > Please, let's don't repeat Mercurial mistake of placing unversioned
> > information (such as branch names in case of Mercurial, or branches
> > descriptions in this case) in-tree, i.e. version it.

I'm sorry, I meant here "tags" not "branch names"... I think...

> Is it really a "mistake" in Mercurial's context?

If we are talking about tags support in Mercurial, I think it is
mistake or at least bad design decision.  Tags are, and should be,
unversioned (or at least versioned separately) but propagated (or
rather propagatable).  Mercurial offers either in-tree .hgtags,
which are always automatically propagated (not merely propagatable);
but this mechanism is by default versioned, and Mercurial does
complicated dance to get reasonable tags semantic.  And there is
[theoretical] problem of merging .hgtags file; perhaps solved by
specialized merge strategy for this file.

Alternatively Mercurial offers so called local tags, which are not
versioned, but not propagated (and AFAIK non propagatable).

So yes, it is a bad design in my opinion.

> I thought that their named branches do have defined "starting point", and
> it is not a mistake at all for them to version "from this point on, this
> lineage of history is associated with this symbolic name (which is a
> branch)".

What happens if there is branching point _after_ such "branch naming tag"?
Unless branch names are purely local and non-propagatable, and Mercurial
can use local revision numbers or something  like this...

I find this CVS legacy to branching (doesn't Subversion use also
something like that) to be stupid.

> It probably does not make sense in the context of git where a branch is
> defined to be "illusion" (at least currently).

BTW. another tool that has yet another idea of what "branch" is
is Monotone, which AFAIK understands branch in reflog sense, via
Monotone's signature signatures ;-)

P.S. Cc-ed mercurial mailing list, to give them chance to respond
to those "accusations"... if it is not subscribe only...
-- 
Jakub Narebski
Poland

Re: branch description

[Jakub Narebski]

"Russ Dill" <russ.dill@gmail.com> writes:

>>  I find it useful to use fairly short names for branches.  However,
>>  sometimes I would like to have a full sentence to actually describe
>>  what the branch is for, without having the peruse the actual commits.
> 
> Me too.
> 
>>  This information could of course be kept on a web page, but it would
>>  be nice to have it in the repo.
> 
> Like, putting your bug number in the branch name.
> 
>>  Is there any such branch annotation command?
>>  Ideally I'd like to see a sentence displayed next to the branch name
>>  when I use "git-branch".
>>  Perhaps, git-branch --info or something.
> 
> The problem is that a branch is just a floating name for a line of
> development. Its not really a "thing" in the repository like a tag or
> a commit. You'd need to make some sort of special tag that describes
> the branch or somesuch.

Errr... not exactly.  It is true that refs such like branches reside
outside object database[1], and that names of refs are purely local
matter (see old master -> origin mapping, and new refs/heads/* ->
refs/remotes/<remote>/* mapping).  But you can examine list of
branches in remote repository using e.g. git-ls-remote or its
equivalent in the git API.

So I think better solution would be to add this info somewhere outside
object database, for example in repository config (assuming that not
all branches would have description) as it already stores branch
related information, _and_ enhance commands to make use of this info,
not only git-branch, but also git-for-each-ref, git-show-refs and
git-ls-remote (and its equivalents).

Footnotes:
==========
[1] And have to be, Mercurial misdesign nothwithstanding
-- 
Jakub Narebski
Poland
ShadeHawk on #git