Topic descriptions

Topic descriptions

[Andy Parkins]

Hello,

I was just reading Junio's "what's cooking" summary, and it occurred to me 
that it would be excellent if git had support for this sort of thing.

It seems fairly easy - it wouldn't have to be versioned information.  Could we 
simply make .git/refs files be more flexible in their syntax.

-----
<sha1>
<anything at all>
-----

I don't know where the UI would go; but it would let Junio generate his what's 
cooking emails with cat .git/refs/*/*

Just an idea...


Andy
-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: Topic descriptions

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> -----
> <sha1>
> <anything at all>
> -----
>
> I don't know where the UI would go; but it would let Junio generate his what's 
> cooking emails with cat .git/refs/*/*

I think the right place to store that <anything at all>
information is per-branch configuration item.  Perhaps:

	[branch "ap/clone-origin"]
        description = we talk about what this thing does and \
        what the current status of it is.

I am unlikely to use such a thing for the "What's in" message,
though.  The part that talks about "what the current status is"
is much easier to write when I need to talk about "the current";
otherwise I'd be forced to remember to think if I need to update
the information, every time I touch topic branches.

But that description thing would be useful in gitweb, for
example.

Re: Topic descriptions

[Andy Parkins]

On Wednesday 2006, December 06 22:31, Junio C Hamano wrote:

> I am unlikely to use such a thing for the "What's in" message,
> though.  The part that talks about "what the current status is"
> is much easier to write when I need to talk about "the current";
> otherwise I'd be forced to remember to think if I need to update
> the information, every time I touch topic branches.

It wasn't so much the what's current - as you say that would be fairly 
ridiculous as it's so fluid.  It was more a description of the topic.  I've 
got tonnes of branches where I have quickly thought of an idea and started 
work on it, only to get bored and move on.  Describing a topic in such a 
short space as "ap/short-name" is hard.

The actual place it's stored isn't really relevant, more that I could see a 
use for it.  If it's going in the config I suppose all it needs is a 
magic "and so it shall be" hand wave.  It doesn't require any new code does 
it?


Andy
-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: Topic descriptions

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> The actual place it's stored isn't really relevant, more that I could see a 
> use for it.  If it's going in the config I suppose all it needs is a 
> magic "and so it shall be" hand wave.

I now have this in my .git/config:

-- >8 -- snippet from .git/config -- >8 --
[branch "ap/clone-origin"]
	description = set up a cloned repository with friendlier defaults.

[branch "jc/3way"]
	description = use three-way merge to preserve local changes upon branch switch and fast forward.
-- 8< --

and have the script attached at the end.  I can say:

	$ git-topic --base=master

to get something like that per-topic summary I sent out earlier.
The default $base is set to 'next' because usually I am
interested in keeping track of what could be merged but not yet
to next.

Hopefully gitweb (and perhaps gitk) can follow suit to read the
branch description from the same place.

-- >8 -- git-topic.perl -- >8 --
#!/usr/bin/perl -w
#
# Copyright (c) 2006 Junio C Hamano
#

use strict;
use Getopt::Long;

my $topic_pattern = '??/*';
my $base = 'next';
my @stage = qw(next pu);
my @mark = ('.', '?', '-', '+');
my $all = 0;

my @custom_stage;
my @custom_mark;
GetOptions("topic=s" => \$topic_pattern,
	   "base=s" => \$base,
	   "stage=s" => \@custom_stage,
	   "mark=s" => \@custom_mark,
	   "all!" => \$all)
    or die;

if (@custom_stage) { @stage = @custom_stage; }
if (@custom_mark) { @mark = @custom_mark; }

sub read_revs_short {
	my ($bottom, $top) = @_;
	my @revs;
	open(REVS, '-|', qw(git rev-list --no-merges), "$bottom..$top")
	    or die;
	while (<REVS>) {
		chomp;
		push @revs, $_;
	}
	close(REVS);
	return @revs;
}

sub read_revs {
	my ($bottom, $top, $mask) = @_;
	my @revs;
	open(REVS, '-|', qw(git rev-list --pretty=oneline --no-merges),
	     "$bottom..$top")
	    or die;
	while (<REVS>) {
		chomp;
		my ($sha1, $topic) = /^([0-9a-f]{40}) (.*)$/;
		push @revs, [$sha1, $topic, $mask];
	}
	close(REVS);
	return @revs;
}

sub describe_topic {
	my ($topic) = @_;
	open(CONF, '-|', qw(git repo-config --get),
		"branch.$topic.description")
		or die;
	my $it = join('',<CONF>);
	close(CONF);
	chomp($it);
	if ($it) {
		wrap_print("  $it");
	}
}

sub wrap_print {
	my ($string) = @_;
	format STDOUT =
~^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
	$string
 ~~^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
	$string
.
	write;
}

open(TOPIC, '-|', qw(git for-each-ref),
	'--sort=-authordate',
	'--format=%(objectname) %(authordate) %(refname)',
	"refs/heads/$topic_pattern")
	or die;

while (<TOPIC>) {
	chomp;
	my ($sha1, $date, $topic) = m|^([0-9a-f]{40})\s(.*?)\srefs/heads/(.+)$|
		or next;
	my @revs = read_revs($base, $sha1, (1<<@stage)-1);
	next unless (@revs || $all);

	my %revs = map { $_->[0] => $_ } @revs; # fast index
	for (my $i = 0; $i < @stage; $i++) {
		for my $item (read_revs_short($stage[$i], $sha1)) {
			if (exists $revs{$item}) {
				$revs{$item}[2] &= ~(1 << $i);
			}
		}
	}
	print "* $topic ($date)\n";
	describe_topic($topic);
	for my $item (@revs) {
		my $mark = $item->[2];
		if ($mark < @mark) {
			$mark = $mark[$mark];
		}
		wrap_print("$mark $item->[1]");
	}
}

Re: Topic descriptions

[Robin Rosenberg]

torsdag 07 december 2006 09:37 skrev Andy Parkins:
> On Wednesday 2006, December 06 22:31, Junio C Hamano wrote:
> > I am unlikely to use such a thing for the "What's in" message,
> > though.  The part that talks about "what the current status is"
> > is much easier to write when I need to talk about "the current";
> > otherwise I'd be forced to remember to think if I need to update
> > the information, every time I touch topic branches.
>
> It wasn't so much the what's current - as you say that would be fairly
> ridiculous as it's so fluid.  It was more a description of the topic.  I've
> got tonnes of branches where I have quickly thought of an idea and started
> work on it, only to get bored and move on.  Describing a topic in such a
> short space as "ap/short-name" is hard.

Your situation sounds similiar to mine, but I don't use regular git branches 
much. Rather I use stacked git instead. Stgit's patches can be though of as 
virtual branches. Instead of creating a dozen branches I have a dozen commits 
managed by stgit that I can choose from (and combine) easily, creating and 
destroying private "branches".

Re: Topic descriptions

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 298 bytes --]

hoi :)

On Wed, Dec 06, 2006 at 02:31:28PM -0800, Junio C Hamano wrote:
> But that description thing would be useful in gitweb, for
> example.

And it could be useful to automatically generate the summary for
please-pull mails or for the [0/N] patch introduction mail.

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Topic descriptions

[Sam Vilain]

Junio C Hamano wrote:
> I think the right place to store that <anything at all>
> information is per-branch configuration item.  Perhaps:
> 
> 	[branch "ap/clone-origin"]
>         description = we talk about what this thing does and \
>         what the current status of it is.
> 
> I am unlikely to use such a thing for the "What's in" message,
> though.  The part that talks about "what the current status is"
> is much easier to write when I need to talk about "the current";
> otherwise I'd be forced to remember to think if I need to update
> the information, every time I touch topic branches.

And this information could even be put into the commit message of the
merge commit.

gitweb/repo could give a "dashboard" of feature branches;

  - creator
  - aim/description of feature branch
  - (computed) mergability with master/trunk/etc (perhaps
    config "merge target(s)")
  - whether tests are passing on this branch (obviously not a
    git-core feature, but a useful thing to know)
  - how many new tests are introduced by this branch.

Some ideas that occurred from watching Martin Pool's talk on managing
distributed VCS with bzr, and the Patch Queue Manager.

Some people might like to include all of the above information in the
merge commit to close the branch, others just the non-redundant information.

Sam.