commit summary, --pretty=short and other tools

commit summary, --pretty=short and other tools

[Mike Hommey]

Hi,

I kind of shot myself in the foot with how to type proper commit
messages.

The git-commit manual page reads:
  Though not required, it´s a good idea to begin the commit message with a
  single short (less than 50 character) line summarizing the change,
  followed by a blank line and then a more thorough description. 

... and I happen to not have done the "followed by a blank line" part.

Now, git log --pretty=oneline (for instance), shows me the full commit
message on one line, which is not really what I would expect...

On the other hand, and that's how I got trapped into this, gitweb and
gitk only display the first line, be it followed by a blank line or not.

So, IMHO, there would be 2 solutions:
- either change --pretty=oneline,short and other similar things to take
  only the first line and change the git-commit manpage (and whenever
  else this might be written)
- or change gitweb, gitk and any other tool that would only take the
  first line so that it takes the same summary as --pretty=oneline.

What do you think ?

Mike

Re: commit summary, --pretty=short and other tools

[Jeff King]

On Mon, Sep 17, 2007 at 01:21:36PM +0200, Mike Hommey wrote:

> ... and I happen to not have done the "followed by a blank line" part.

If this isn't a published repo, you can fix it with filter-branch:

git filter-branch --msg-filter 'sed "1a
"'

> Now, git log --pretty=oneline (for instance), shows me the full commit
> message on one line, which is not really what I would expect...
> 
> On the other hand, and that's how I got trapped into this, gitweb and
> gitk only display the first line, be it followed by a blank line or not.

This was changed recently for git-log and company, but gitk and gitweb
have not followed suit.  Traditionally, the behavior was to take the
first line. This was changed in 4234a761 to take the first paragraph.
The rationale was that people without the nice one-line summaries are
typically importing old histories, and the paragraph makes a much more
sensible summary (as opposed to cutting off the summary in
mid-sentence).

> So, IMHO, there would be 2 solutions:
> - either change --pretty=oneline,short and other similar things to take
>   only the first line and change the git-commit manpage (and whenever
>   else this might be written)
> - or change gitweb, gitk and any other tool that would only take the
>   first line so that it takes the same summary as --pretty=oneline.
> 
> What do you think ?

It depends on whether people like the new behavior. I think it is more
sensible in every case _except_ the one you have mentioned, but your
case is hopefully somewhat rare (though it just made it to the public in
1.5.3, so yours might be the first of many comments).

I do agree that it makes sense for all of the tools to be consistent.

-Peff

Re: commit summary, --pretty=short and other tools

[Benoit SIGOURE]

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

On Sep 17, 2007, at 1:21 PM, Mike Hommey wrote:

> Hi,
>
> I kind of shot myself in the foot with how to type proper commit
> messages.
>
> The git-commit manual page reads:
>   Though not required, it´s a good idea to begin the commit message  
> with a
>   single short (less than 50 character) line summarizing the change,
>   followed by a blank line and then a more thorough description.
>
> ... and I happen to not have done the "followed by a blank line" part.
>
[...]
> What do you think ?

I started using Git as a "better SVN client" and didn't follow this  
"good idea".  The thing, as I already pointed out on IRC, these a are  
more rules than just guidelines.  Some tools (such as rebase) enforce  
them.  That is, they rewrite commit messages.  I found this extremely  
annoying (Junio provided a patch but I don't know whether it's been  
applied, I personally use it in my Git).

See this thread: http://marc.info/?t=118561729500001&r=1&w=2

My opinion is that it would be better to keep the first line and  
never ever rewrite the commit messages.

Cheers,

-- 
Benoit Sigoure aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: commit summary, --pretty=short and other tools

[Junio C Hamano]

Benoit SIGOURE <tsuna@lrde.epita.fr> writes:

> I started using Git as a "better SVN client" and didn't follow this
> "good idea".  The thing, as I already pointed out on IRC, these a are
> more rules than just guidelines.  Some tools (such as rebase) enforce
> them.  That is, they rewrite commit messages.  I found this extremely
> annoying (Junio provided a patch but I don't know whether it's been
> applied, I personally use it in my Git).

Wow, ancient history.

d7f6bae28142e07e544efdab73260cf9f60ca899 (rebase: try not to
munge commit log message) is what you are talking about.  It is
in 1.5.3.

commit d7f6bae28142e07e544efdab73260cf9f60ca899
Author: Junio C Hamano <gitster@pobox.com>
Date:   Sat Jul 28 17:57:25 2007 -0700

    rebase: try not to munge commit log message

    This makes rebase/am keep the original commit log message
    better, even when it does not conform to "single line paragraph
    to say what it does, then explain and defend why it is a good
    change in later paragraphs" convention.

    This change is a two-edged sword.  While the earlier behaviour
    would make such commit log messages more friendly to readers who
    expect to get the birds-eye view with oneline summary formats,
    users who primarily use git as a way to interact with foreign
    SCM systems would not care much about the convenience of oneline
    git log tools, but care more about preserving their own
    convention.  This changes their commits less useful to readers
    who read them with git tools while keeping them more consistent
    with the foreign SCM systems they interact with.

    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Re: commit summary, --pretty=short and other tools

[Andreas Ericsson]

Benoit SIGOURE wrote:
> 
> My opinion is that it would be better to keep the first line and never 
> ever rewrite the commit messages.
> 

I've had reason to ponder this quite a lot, as I've imported 15 repos from
CVS and SVN where the commit authors did not follow the git-recommended way
of doing things, but rather put everything as one paragraph, usually without
linebreaks, in the commit message.

>From what I've read from those rather horrid commit-messages so far, it's
usually correct to grab the first sentence in case the empty line isn't
there, so:

const char *find_commit_subject_end(const char *commit_msg)
{
	const char *dot, *paragraph_end;
	
	paragraph_end = strstr(commit_msg, "\n\n");
	dot = strchr(commit_msg, '.');
	
	return min_non_null(dot, paragraph_end); 
}

would probably get it right very nearly always.

I'll submit a patch in 3 hours when I get my lunch, unless someone
beats me to it.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: commit summary, --pretty=short and other tools

[Johannes Schindelin]

Hi,

On Tue, 18 Sep 2007, Andreas Ericsson wrote:

> const char *find_commit_subject_end(const char *commit_msg)
> {
> 	const char *dot, *paragraph_end;
> 		paragraph_end = strstr(commit_msg, "\n\n");
> 	dot = strchr(commit_msg, '.');
> 		return min_non_null(dot, paragraph_end); }
> 
> would probably get it right very nearly always.

Counterexample (not even mentioning the missing handling of NULL):

http://brick.kernel.dk/git/?p=qemu.git;a=commit;h=eb66d86e295cd5a8f13221589806e15db62a62fa

And no, the responsible developer showed a strong unwillingness to adapt 
to better tools and workflows.

Ciao,
Dscho

Re: commit summary, --pretty=short and other tools

[Andreas Ericsson]

Johannes Schindelin wrote:
> Hi,
> 
> On Tue, 18 Sep 2007, Andreas Ericsson wrote:
> 
>> const char *find_commit_subject_end(const char *commit_msg)
>> {
>> 	const char *dot, *paragraph_end;
>> 		paragraph_end = strstr(commit_msg, "\n\n");
>> 	dot = strchr(commit_msg, '.');
>> 		return min_non_null(dot, paragraph_end); }
>>
>> would probably get it right very nearly always.
> 
> Counterexample (not even mentioning the missing handling of NULL):
> 

Well, pseudo code doesn't have to handle NULL's, as it never gets bad
pseudo-input ;-)

> http://brick.kernel.dk/git/?p=qemu.git;a=commit;h=eb66d86e295cd5a8f13221589806e15db62a62fa
> 
> And no, the responsible developer showed a strong unwillingness to adapt 
> to better tools and workflows.
> 

Hmm, how about any interpunctuation char or newline followed by newline or
the first dot?

It would cover this case and not be overly hard to code.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: commit summary, --pretty=short and other tools

[Benoit SIGOURE]

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

On Sep 18, 2007, at 12:13 PM, Johannes Schindelin wrote:

> Hi,
>
> On Tue, 18 Sep 2007, Andreas Ericsson wrote:
>
>> const char *find_commit_subject_end(const char *commit_msg)
>> {
>> 	const char *dot, *paragraph_end;
>> 		paragraph_end = strstr(commit_msg, "\n\n");
>> 	dot = strchr(commit_msg, '.');
>> 		return min_non_null(dot, paragraph_end); }
>>
>> would probably get it right very nearly always.
>
> Counterexample (not even mentioning the missing handling of NULL):
>
> http://brick.kernel.dk/git/? 
> p=qemu.git;a=commit;h=eb66d86e295cd5a8f13221589806e15db62a62fa
>
> And no, the responsible developer showed a strong unwillingness to  
> adapt
> to better tools and workflows.
>

OK, look, I think this is the typical case where there is no single  
solution to fit all use cases.
To handle this specific case, you could say "OK let's stop at  
punctuation symbols then".  But what if my commit message is "Add  
namespace::member whatever."

If there is a single line followed by a blank line: it's a git-style  
commit message, do what was done before.
Otherwise, we need some heuristic to find the relevant part of the  
commit message (if there is such a relevant part in the first place!).

-- 
Benoit Sigoure aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: commit summary, --pretty=short and other tools

[Johannes Schindelin]

Hi,

On Tue, 18 Sep 2007, Benoit SIGOURE wrote:

> On Sep 18, 2007, at 12:13 PM, Johannes Schindelin wrote:
> 
> > On Tue, 18 Sep 2007, Andreas Ericsson wrote:
> > 
> > > const char *find_commit_subject_end(const char *commit_msg)
> > > {
> > > 	const char *dot, *paragraph_end;
> > > 		paragraph_end = strstr(commit_msg, "\n\n");
> > > 	dot = strchr(commit_msg, '.');
> > > 		return min_non_null(dot, paragraph_end); }
> > > 
> > > would probably get it right very nearly always.
> > 
> > Counterexample (not even mentioning the missing handling of NULL):
> > 
> > http://brick.kernel.dk/git/?p=qemu.git;a=commit;h=eb66d86e295cd5a8f13221589806e15db62a62fa
> > 
> > And no, the responsible developer showed a strong unwillingness to adapt
> > to better tools and workflows.
> > 
> 
> OK, look, I think this is the typical case where there is no single solution
> to fit all use cases.
> To handle this specific case, you could say "OK let's stop at punctuation
> symbols then".  But what if my commit message is "Add namespace::member
> whatever."
> 
> If there is a single line followed by a blank line: it's a git-style commit
> message, do what was done before.

That's the current behaviour already.  And has been for a long time.

> Otherwise, we need some heuristic to find the relevant part of the commit
> message (if there is such a relevant part in the first place!).

Or do we?

I was opposed to this change, since I think that there is really no way to 
fit all exisiting (!) repositories.

And since oneline was always only meant as a hint, it might just as well 
have stayed at "just one line, the first one".

Maybe you guys find a better method, such as providing a regular 
expression in the config or something, but let's not do another change 
that does not work for all cases.

Ciao,
Dscho

Re: commit summary, --pretty=short and other tools

[Wincent Colaiuta]

El 18/9/2007, a las 12:27, Benoit SIGOURE escribió:

> OK, look, I think this is the typical case where there is no single  
> solution to fit all use cases.
> To handle this specific case, you could say "OK let's stop at  
> punctuation symbols then".  But what if my commit message is "Add  
> namespace::member whatever."

Uh, I don't think you'd stop a punctuation symbol unless it was the  
last non-whitespace character before the newline.

Even then, as Johannes says, "oneline" is only meant as a hint  
anyway, so it doesn't really matter that much.

Wincent