Re: Question about commit message wrapping

["Frans Klaver" <fransklaver@gmail.com>]

On Fri, 09 Dec 2011 02:59:06 +0100, Sidney San Martín <s@sidneysm.com>  
wrote:

> Hey, I want to ask about the practice of wrapping commit messages to  
> 70-something charaters.
>
> The webpage most cited about it, which I otherwise really like, is
>
> 	http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
>
> *Nothing else* in my everyday life works this way anymore. Line wrapping  
> gets done on the display end in my email client, my web browser, my  
> ebook reader entirely automatically, and it adapts to the size of the  
> window.

Actually, opera-mail autowraps at 72 characters but sets the text format  
to flowed. It also wraps the quoted text when you reply. But there's a  
reasonable chance that you don't use opera in your daily life. On the  
other hand I would not be surprised if most decent e-mail clients worked  
that way.

Nobody's forcing you to use the same practice in your own projects anyway.


>
> That article gives two reasons why commits should be wrapped to 72  
> columns. First:
>
>> git log doesn’t do any special special wrapping of the commit messages.  
>> With the default pager of less -S, this means your paragraphs flow far  
>> off the edge of the screen, making them difficult to read. On an 80  
>> column terminal, if we subtract 4 columns for the indent on the left  
>> and 4 more for symmetry on the right, we’re left with 72 columns.
>
> Here, I put a patch at the bottom of this email that wraps commit  
> messages to, right now, 80 columns when they're displayed. (It’s a quick  
> one, probably needs configurability. Also, beware, I don’t program in C  
> too much.)

Hm. Saying "that's how the tool works" is not a good reason in my opinion.  
There might be tons of other reasons for wrapping at 80 characters.  
Readability is one that comes to mind for me.

>
> Second:
>
>> git format-patch --stdout converts a series of commits to a series of  
>> emails, using the messages for the message body. Good email netiquette  
>> dictates we wrap our plain text emails such that there’s room for a few  
>> levels of nested reply indicators without overflow in an 80 column  
>> terminal. (The current rails.git workflow doesn’t include email, but  
>> who knows what the future will bring.)
>
> There's been a standard for flowed plain text emails (which don't have  
> to wrap at 80 columns) for well over ten years, RFC-2646 and is widely  
> supported. Besides, code in diffs is often longer than 7x characters,  
> and wrapping, like `git log`, could be done inside git. FWIW, there are  
> a bunch of merge commits with lines longer than 80 characters in the git  
> repo itself.

Yes, that standard allows e-mail clients to display the text more fluidly,  
even if the source text is word-wrapped. While git uses e-mail format, it  
isn't an e-mail client. I always interpreted this whole thing as git  
basically creating plain-text e-mails. You're actually writing the source  
of the e-mail in your commit message. If you care about actual use in  
e-mail (like we do here on the list) you might want to add the relevant  
header to the mails. That said, Apple Mail (the client you used to send  
your mail) doesn't even use the RFC you quote in the sent message. That  
mail is going to be a pain in the butt to read in mutt from work ;).


>
> Finally, people read commits these days in many other places than `git  
> log` (and make commits in many other places than a text editor  
> configured to wrap). Most every GUI and already word wraps commit  
> messages just fine. As a result, there are commits in popular repos much  
> longer than the 72-column standard and no one notices. Instead,  
> properly-formatted commit messages end up looking cramped when you see  
> them in anywhere wider than 80 columns.

Cramped? I think it's compact and actually I prefer it over long lines.

> Am I crazy?

Probably not. Don't take my word for it. I'm not a psychiatrist.


> If this makes sense to anyone else, I'd be happy to help massage this  
> into something git-worthy, with some help (never worked on Git before).
>
> - - -
>
> From a93b390d1506652d4ad41d1cbd987ba98a8deca0 Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Sidney=20San=20Marti=CC=81n?= <s@sidneysm.com>
> Date: Thu, 8 Dec 2011 20:26:23 -0500
> Subject: [PATCH] Wrap commit messages on display
>
> - Wrap to 80 characters minus the indent
> - Use a hanging indent for lines which begin with "- "
> - Do not wrap lines which begin with whitespace
> ---
>  pretty.c |   10 ++++++++--
>  1 files changed, 8 insertions(+), 2 deletions(-)
>
> diff --git a/pretty.c b/pretty.c
> index 230fe1c..15804ce 100644
> --- a/pretty.c
> +++ b/pretty.c
> @@ -1243,8 +1243,14 @@ void pp_remainder(const struct  
> pretty_print_context *pp,
>  			memset(sb->buf + sb->len, ' ', indent);
>  			strbuf_setlen(sb, sb->len + indent);
>  		}
> -		strbuf_add(sb, line, linelen);
> -		strbuf_addch(sb, '\n');
> +		if (line[0] == ' ' || line[0] == '\t') {
> +			strbuf_add(sb, line, linelen);
> +		} else {
> +			struct strbuf wrapped = STRBUF_INIT;
> +			strbuf_add(&wrapped, line, linelen);
> +			strbuf_add_wrapped_text(sb, wrapped.buf, 0, indent + (line[0] == '-'  
> && line[1] == ' ' ? 2 : 0), 80 - indent);

While on the subject, In my mail view, the new line started with the [1]  
 from line[1], in the quote the line looks entirely different. Now this is  
code we're talking about, so it makes slightly more sense to have a proper  
wrapping hard-coded. Compare the above with the following:

+			int hanging_indent = ((line[0] == '-' && line[1] == ' ') ? 2 : 0);
[...]
+			strbuf_add_wrapped_text(sb, wrapped.buf, 0,
+									indent + hanging_indent,
+									80 - indent);

Much clearer, no? I personally usually have two or three terminals tucked  
next to each other, so I can look at two or three things at the same time.  
80 characters limit is a nice feature then.


> +			strbuf_addch(sb, '\n');
> +		}
>  	}
>  }
>

Cheers,
Frans