Re: branch description

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> 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.