Subject: Re: [RFC] Configuring (future) committags support in gitweb

From: Jakub Narebski <[email-masked]>
Date: Sat, 8 Nov 2008 23:35:48 +0100

Dnia sobota 8. listopada 2008 21:02, Francis Galiegue napisał:
> Le Saturday 08 November 2008 20:07:53 Jakub Narebski, vous avez écrit :
>> Francis Galiegue <[email-masked]> writes
>> in "Need help for migration from CVS to git in one go..."
>>
>>> * third: also Bonsai-related; Bonsai can link to Bugzilla by
>>> matching (wild guess) /\b(?:#?)(\d+)\b/ and transforming this into
>>> http://your.bugzilla.fqdn.here/show_bug.cgi?id=$1. Does gitweb have
>>> this built-in? (haven't looked yet) Is this planned, or has it been
>>> discussed and been considered not worth the hassle?
[...]

>> Committags are "tags" in commit messages, expanded when rendering commit
>> message, like gitweb now does for (shortened) SHA-1, converting them to
>> 'object' view link.  It should be done in a way to make it easy
>> configurable, preferably having to configure only variable part, and not
>> having to write whole replacement rule.
>>
>> Possible committags include: _BUG(n)_, bug _#n_, _FEATURE(n),
>> Message-Id, plain text URL e.g. _http://repo.or.cz_, spam protecting
>> of email addresses, "rich text formatting" like *bold* and _underline_,
>> syntax highlighting of signoff lines.
>>
> 
> What do you mean with "not having to write whole replacement rule"?

Like in example with 'link' rule, not having to write whole
<a href="http://example.com/bugzilla.php?id=$1">$&</a>
(or something like that).

>> I think it would be good idea to use repository config file for
>> setting-up repository-specific committags, and use whatever Perl
>> structure for global configuration. The config language can be
>> borrowed from "drivers" in gitattributes (`diff' and `merge' drivers).
>>
>> So the example configuration could look like this:
>>
>>   [gitweb]
>>   	committags = sha1 signoff bugzilla
>>
>>   [committag "bugzilla"]
>>   	match = "\\b(?:#?)(\\d+)\\b"
>>   	link  = "http://your.bugzilla.fqdn.here/show_bug.cgi?id=$1"
>>
>> where 'sha1' and 'signoff' are built-in committags, committags are
>> applied in the order they are put in gitweb.committags;
> 
> I don't understand what the "signoff" builtin is : is that a link to see only 
> commits "Signed-off-by:" a particular person?

Committags doesn't need to be replaced by links. In this case I meant
here using 'signoff' class for Signed-off-by: (and the like) lines, by
wrapping it in '<span class="signoff">' ... '</a>'.

> And also, what about the sha1 builtin? AFAIK, a SHA1 can point to a commit, a 
> tree, and others... In fact, it points to any of these right now, but how 
> would you tell apart these different SHA1s in a commit message? The only 
> obvious use I see for it is the builtin "Revert ..." commit message, that the 
> commiter _can_ override...

SHA1 (or shortened SHA1 from 8 charasters to 40 characters, or to be
even more exact something that looks like SHA1) is replaced by link
to 'object' view, which in turn finds type of object and _redirect_
to proper view, be it 'commit' (most frequent), 'tag', 'blob' or 'tree'.

We could have used instead gitweb link with 'h' (hash) parameter, but
without 'a' (action) parameter, which currently finds type of object
and _uses_ correct view...
 
> Finally, is there any reason to think that a sha1 or signoff committag will 
> ever need to be overriden in some way?

One might not want to link SHA1, for example if there are lots of false
positives because of commit message conventions or something, or refine
'signoff' committag to use different styles for different types of
signoff: Signed-off-by, Acked-by, Tested-by, other.  Having explicit
'signoff' committag allows us also to put some committags _after_ it,
for example SPAM-protection of emails, or add some committag before
'sha1' to filter out some SHA1 match false positives.
 
>> possible actions 
>> for committag driver include:
>>  * link: replace $match by '_<a href="$link">_$match_</a>_'
>>  * html: replace $match by '_$html_'
>>  * text: replace $match by '$text'
>> where '_a_' means that 'a' is treated as HTML, and is not expanded
>> further, and 'b' means that it can be further expanded by later
>> committags, and finally is HTML-escaped (esc_html).
>>
> 
> What use do you see for the html match? Just asking...

For example 'signoff' committag... well, it is not exactly pure "html"
but rather something like template.

  [committag "signoff"]
  	match = "(?i)^ *(signed[ \\-]off[ \\-]by[ :]|acked[ \\-]by[ :]|cc[ :])"
  	templ = "{<span class=\"signoff\">}$1{</span>}"

Or simpler

  [committag "signoff"]
  	match = "(?i)^ *(signed[ \\-]off[ \\-]by[ :]|acked[ \\-]by[ :]|cc[ :])"
  	class = signoff

> And I don't see what you '_a_' and '_b_' are about...

For example in link match, the text of the link can be further refined
by committags later in sequence.

-- 
Jakub Narebski
Poland