From: Jeff King <peff@peff.net>
Date: Tue, 15 Apr 2008 19:19:30 GMT
Subject: Re: branch description
Message-ID: <20080415191930.GC31395@sigill.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 "<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