# branch description 23 messages from 2008-04-15 to 2008-04-19. Participants: Stephen Sinclair, Russ Dill, Brian Gernhardt, Jakub Narebski, Junio C Hamano, Jeff King, Matt Graham, Mike Hommey, Johan Herland. Thread: https://gitlist.dev/t/13125 ## Stephen Sinclair, 2008-04-15 16:51 Subject: branch description Message-ID: <9b3e2dc20804150951scf8b3c7x26f3a56eab1f9840@mail.gmail.com> URL: https://gitlist.dev/e/9b3e2dc20804150951scf8b3c7x26f3a56eab1f9840%40mail.gmail.com ``` 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 ``` ## Russ Dill, 2008-04-15 17:31 Subject: Re: branch description Message-ID: URL: https://gitlist.dev/e/f9d2a5e10804151031o1d09c1f9od0ad78dcf9b746c5%40mail.gmail.com In-Reply-To: <9b3e2dc20804150951scf8b3c7x26f3a56eab1f9840@mail.gmail.com> ``` > 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. ``` ## Brian Gernhardt, 2008-04-15 18:01 Subject: Re: branch description Message-ID: URL: https://gitlist.dev/e/C55CA6EB-D427-4CF5-923E-DE0071D2F870%40silverinsanity.com In-Reply-To: ``` 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 "\t", 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 ``` ## Jakub Narebski, 2008-04-15 18:36 Subject: Re: branch description Message-ID: URL: https://gitlist.dev/e/m3iqyjrmmk.fsf%40localhost.localdomain In-Reply-To: ``` "Russ Dill" 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//* 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 ``` ## Junio C Hamano, 2008-04-15 19:12 Subject: Re: branch description Message-ID: <7vej97x78v.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vej97x78v.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Brian Gernhardt 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 "\t", > 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. ``` ## Jeff King, 2008-04-15 19:19 Subject: Re: branch description Message-ID: <20080415191930.GC31395@sigill.intra.peff.net> URL: https://gitlist.dev/e/20080415191930.GC31395%40sigill.intra.peff.net In-Reply-To: <7vej97x78v.fsf@gitster.siamese.dyndns.org> ``` 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 "\t", > > 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 ``` ## Stephen Sinclair, 2008-04-15 20:53 Subject: Re: branch description Message-ID: <9b3e2dc20804151353p2622ab19i2a04f5da9a6417ca@mail.gmail.com> URL: https://gitlist.dev/e/9b3e2dc20804151353p2622ab19i2a04f5da9a6417ca%40mail.gmail.com In-Reply-To: <7vej97x78v.fsf@gitster.siamese.dyndns.org> ``` On Tue, Apr 15, 2008 at 3:12 PM, Junio C Hamano 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 ``` ## Brian Gernhardt, 2008-04-15 21:04 Subject: Re: branch description Message-ID: URL: https://gitlist.dev/e/C4EC2200-59E0-4FBE-AA5F-4A05DAF4A427%40silverinsanity.com In-Reply-To: <9b3e2dc20804151353p2622ab19i2a04f5da9a6417ca@mail.gmail.com> ``` On Apr 15, 2008, at 4:53 PM, Stephen Sinclair wrote: > On Tue, Apr 15, 2008 at 3:12 PM, Junio C Hamano > 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 ``` ## Jeff King, 2008-04-15 22:37 Subject: Re: branch description Message-ID: <20080415223716.GA1891@sigill.intra.peff.net> URL: https://gitlist.dev/e/20080415223716.GA1891%40sigill.intra.peff.net In-Reply-To: <20080415191930.GC31395@sigill.intra.peff.net> ``` 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 --- 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 [] +git-refinfo get [ ...]' +. 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 ``` ## Junio C Hamano, 2008-04-15 22:56 Subject: Re: branch description Message-ID: <7vod8awwvz.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vod8awwvz.fsf%40gitster.siamese.dyndns.org In-Reply-To: <20080415223716.GA1891@sigill.intra.peff.net> ``` Jeff King 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. ``` ## Jakub Narebski, 2008-04-16 01:33 Subject: Re: branch description Message-ID: URL: https://gitlist.dev/e/m3abjushvs.fsf%40localhost.localdomain In-Reply-To: <7vej97x78v.fsf@gitster.siamese.dyndns.org> ``` Junio C Hamano writes: > Brian Gernhardt 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 "\t", >> 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 ``` ## Jeff King, 2008-04-16 02:55 Subject: Re: branch description Message-ID: <20080416025537.GA7878@sigill.intra.peff.net> URL: https://gitlist.dev/e/20080416025537.GA7878%40sigill.intra.peff.net In-Reply-To: ``` 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 ``` ## Stephen Sinclair, 2008-04-16 03:28 Subject: Re: branch description Message-ID: <9b3e2dc20804152028s571ea2edm3cdbac7db57e6d8d@mail.gmail.com> URL: https://gitlist.dev/e/9b3e2dc20804152028s571ea2edm3cdbac7db57e6d8d%40mail.gmail.com In-Reply-To: ``` On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski 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 ``` ## Matt Graham, 2008-04-16 03:46 Subject: Re: branch description Message-ID: <1c5969370804152046h8d67630m697ca71b523b04d9@mail.gmail.com> URL: https://gitlist.dev/e/1c5969370804152046h8d67630m697ca71b523b04d9%40mail.gmail.com In-Reply-To: ``` On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski wrote: > Junio C Hamano writes: > > > Brian Gernhardt 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 "\t", > >> 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. ``` ## Junio C Hamano, 2008-04-16 05:27 Subject: Re: branch description Message-ID: <7vfxtmtlm0.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vfxtmtlm0.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Jakub Narebski 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). ``` ## Mike Hommey, 2008-04-16 05:55 Subject: Re: branch description Message-ID: <20080416055508.GA28725@glandium.org> URL: https://gitlist.dev/e/20080416055508.GA28725%40glandium.org In-Reply-To: <9b3e2dc20804152028s571ea2edm3cdbac7db57e6d8d@mail.gmail.com> ``` On Tue, Apr 15, 2008 at 11:28:49PM -0400, Stephen Sinclair wrote: > On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski 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 ``` ## Johan Herland, 2008-04-16 08:29 Subject: Re: branch description Message-ID: <200804161029.18601.johan@herland.net> URL: https://gitlist.dev/e/200804161029.18601.johan%40herland.net In-Reply-To: <1c5969370804152046h8d67630m697ca71b523b04d9@mail.gmail.com> ``` On Wednesday 16 April 2008, Matt Graham wrote: > On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski 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, www.herland.net ``` ## Jakub Narebski, 2008-04-16 19:56 Subject: Re: branch description Message-ID: <200804162156.27435.jnareb@gmail.com> URL: https://gitlist.dev/e/200804162156.27435.jnareb%40gmail.com In-Reply-To: <7vfxtmtlm0.fsf@gitster.siamese.dyndns.org> ``` On Wed, 16 April 2008, Junio C Hamano wrote: > Jakub Narebski 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 ``` ## Jakub Narebski, 2008-04-18 21:58 Subject: Re: branch description Message-ID: <200804182358.31041.jnareb@gmail.com> URL: https://gitlist.dev/e/200804182358.31041.jnareb%40gmail.com In-Reply-To: <200804161029.18601.johan@herland.net> ``` 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..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/' file in a tree for a commit for a special '' 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 ``` ## Johan Herland, 2008-04-19 09:18 Subject: Re: branch description Message-ID: <200804191118.50105.johan@herland.net> URL: https://gitlist.dev/e/200804191118.50105.johan%40herland.net In-Reply-To: <200804182358.31041.jnareb@gmail.com> ``` 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..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/' file in a tree for > a commit for a special '' 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, www.herland.net ``` ## Junio C Hamano, 2008-04-19 17:43 Subject: Re: branch description Message-ID: <7v1w51g2q5.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v1w51g2q5.fsf%40gitster.siamese.dyndns.org In-Reply-To: <200804191118.50105.johan@herland.net> ``` Johan Herland 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. ``` ## Johan Herland, 2008-04-19 18:09 Subject: Re: branch description Message-ID: <200804192009.36243.johan@herland.net> URL: https://gitlist.dev/e/200804192009.36243.johan%40herland.net In-Reply-To: <7v1w51g2q5.fsf@gitster.siamese.dyndns.org> ``` On Saturday 19 April 2008, Junio C Hamano wrote: > Johan Herland 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, www.herland.net ``` ## Jakub Narebski, 2008-04-19 21:05 Subject: Re: branch description Message-ID: <200804192305.36780.jnareb@gmail.com> URL: https://gitlist.dev/e/200804192305.36780.jnareb%40gmail.com In-Reply-To: <200804191118.50105.johan@herland.net> ``` 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 ```