Re: branch description

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 15, 2008, 22:56 UTC
Message-ID: <7vod8awwvz.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20080415223716.GA1891@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 18 quoted lines

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