Re: branch description

[Johan Herland <johan@herland.net>]

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