Re: branch description

From: Johan Herland <johan@herland.net>
Date: Apr 19, 2008, 09:18 UTC
Message-ID: <200804191118.50105.johan@herland.net>
In-Reply-To: <200804182358.31041.jnareb@gmail.com>

On Friday 18 April 2008, Jakub Narebski wrote:

Show 7 quoted lines

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

Show 23 quoted lines

> 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