Question about commit message wrapping

Question about commit message wrapping

[Sidney San Martín]

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.

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.)

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.

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.

Am I crazy? 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);
+			strbuf_addch(sb, '\n');
+		}
 	}
 }
 
-- 
1.7.8

Re: Question about commit message wrapping

[Frans Klaver]

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

Re: Question about commit message wrapping

[Frans Klaver]

On Fri, Dec 9, 2011 at 8:05 AM, Frans Klaver <fransklaver@gmail.com> wrote:

>> *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.

It appears none of the books I have available here have more than 80
characters on one line. It's a typography thing. And typographers for
some reason rarely get it wrong. Why not make use of that knowledge?

Re: Question about commit message wrapping

[Jakub Narebski]

Sidney San Martín <s@sidneysm.com> writes:

> *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.

The problem with automatic wrapping on the display is that there could
be parts of commit message that *shouldn't* be wrapped, like code
sample, or URL... and in plain text you don't have a way to separate
flowed from non-flowed part.

Also with long non-breakable identifiers you sometimes need to wrap by
hand (or use linebreaking algorithm from TeX) or go bit over the limit
to make it look nice.

BTW. proper editor used to create commit message can wrap it for you
;-).
-- 
Jakub Narębski

Re: Question about commit message wrapping

[Sidney San Martín]

On Dec 9, 2011, at 2:05 AM, Frans Klaver wrote:

> 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.
> 

Interesting… either way, the end result is that the receiving mail client can wrap the lines to whatever length it (or you, as its operator) desires, which I think we can agree is a good thing, right?

> 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.
> 

That's my basic point. I hope it didn't seem like I was arguing against reading commit messages wrapped to 80 columns, by default. I only wanted to discuss whether it makes more sense to handle it on the display end instead of asking committers to do it in advance.

- My phone shows text most comfortably at about 40 characters per line. I do look at terminals at 80 columns most of the time, but not always, and I sometimes browse projects in GUI tools that use a proportional font in a window may be narrower or wider than that.

- Right now, when I *am* in an 80-col terminal I have to trust everyone else to wrap their commit messages. Not everyone does. I feel like it would be more effective to give git the ability to wrap them automatically when I read them.

>> 
>> 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 ;).
> 

Sorry, I'm not sure what you mean by, “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”.

Interesting, I didn't realize that Mail didn't use it. It does, however, use quoted-printable which, as far as I can tell, has a similar effect on line wrapping. What happens when you view this email in mutt?

> 
>> 
>> 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.

Good point, that makes it clearer either way. I put an updated patch at the bottom of this email (also fixed forgetting the newline after lines with leading whitespace). I hope it's OK to include patches this way, I understand that they're supposed to represent whole emails but want to include them with this discussion.

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


From 53fd7deedaf5ac522c9d752e79cf71561cc57f07 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 |    9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)

diff --git a/pretty.c b/pretty.c
index 230fe1c..841ccd1 100644
--- a/pretty.c
+++ b/pretty.c
@@ -1243,7 +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);
+		if (line[0] == ' ' || line[0] == '\t') {
+			strbuf_add(sb, line, linelen);
+		} else {
+			struct strbuf wrapped = STRBUF_INIT;
+			strbuf_add(&wrapped, line, linelen);
+			int hanging_indent = ((line[0] == '-' && line[1] == ' ') ? 2 : 0);
+			strbuf_add_wrapped_text(sb, wrapped.buf, 0, indent + hanging_indent, 80 - indent);
+		}
 		strbuf_addch(sb, '\n');
 	}
 }
-- 
1.7.8

Re: Question about commit message wrapping

[Frans Klaver]

I'm adding git@vger... again, cause there didn't seem to be a reason not to.

On Fri, Dec 9, 2011 at 3:10 PM, Sidney San Martín <s@sidneysm.com> wrote:
> On Dec 9, 2011, at 2:05 AM, Frans Klaver wrote:
>
>> 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.
>>
>
> Interesting… either way, the end result is that the receiving mail client can wrap the lines to whatever length it (or you, as its operator) desires, which I think we can agree is a good thing, right?
>

Yes.

>> 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.
>>
>
> That's my basic point. I hope it didn't seem like I was arguing against reading commit messages wrapped to 80 columns, by default. I only wanted to discuss whether it makes more sense to handle it on the display end instead of asking committers to do it in advance.
>

It somewhat looked like that. I think it might make sense for clients
to ignore the line wrapping when they can only show less than 80
characters on a line, but that would probably break the code part of a
patch mail.


> - My phone shows text most comfortably at about 40 characters per line. I do look at terminals at 80 columns most of the time, but not always, and I sometimes browse projects in GUI tools that use a proportional font in a window may be narrower or wider than that.
>
> - Right now, when I *am* in an 80-col terminal I have to trust everyone else to wrap their commit messages. Not everyone does. I feel like it would be more effective to give git the ability to wrap them automatically when I read them.
>

It could be a useful option to wrap when the lines extend the window
width, but I'd actually think it's better to leave that up to the
pager than to git.

>>>
>>> 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 ;).
>>
>
> Sorry, I'm not sure what you mean by, “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”.

I thought you might want to have wrapped text in the git commit
messages, but actually put a format flowed tag into the mail header.
I'm not sure what that would do to the code though.


> Interesting, I didn't realize that Mail didn't use it. It does, however, use quoted-printable which, as far as I can tell, has a similar effect on line wrapping. What happens when you view this email in mutt?
>

I had no idea quoted printable had any effect on line wrapping. As far
as I know it's just a way to encode non-ascii characters in 7bit, no
more no less. Your current e-mail happens to end lines with =<nl>,
which probably handles the wrapping. Your original message didn't have
that.


>>> - - -
>>>
>>> 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.
>
> Good point, that makes it clearer either way. I put an updated patch at the bottom of this email (also fixed forgetting the newline after lines with leading whitespace). I hope it's OK to include patches this way, I understand that they're supposed to represent whole emails but want to include them with this discussion.
>

You can include them in the discussion. While it is probably OK to put
some code into your mail to propose something (I've seen it happen
more than once), the end result is supposed to be submitted with a
git-format-patch'd commit. You can read more about contributing in
Documentation/SubmittingPatches.


>>
>>
>>> +                    strbuf_addch(sb, '\n');
>>> +            }
>>>      }
>>> }
>>>
>>
>> Cheers,
>> Frans
>
>
> From 53fd7deedaf5ac522c9d752e79cf71561cc57f07 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 |    9 ++++++++-
>  1 files changed, 8 insertions(+), 1 deletions(-)
>
> diff --git a/pretty.c b/pretty.c
> index 230fe1c..841ccd1 100644
> --- a/pretty.c
> +++ b/pretty.c
> @@ -1243,7 +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);
> +               if (line[0] == ' ' || line[0] == '\t') {
> +                       strbuf_add(sb, line, linelen);
> +               } else {
> +                       struct strbuf wrapped = STRBUF_INIT;
> +                       strbuf_add(&wrapped, line, linelen);
> +                       int hanging_indent = ((line[0] == '-' && line[1] == ' ') ? 2 : 0);
> +                       strbuf_add_wrapped_text(sb, wrapped.buf, 0, indent + hanging_indent, 80 - indent);

It's common in C (and in certain flavors even required) to have your
variable declaration at the beginning of the scope:

+               } else {
+                       int hanging_indent;
+                       struct strbuf wrapped = STRBUF_INIT;
+                       strbuf_add(&wrapped, line, linelen);
+                       hanging_indent = ((line[0] == '-' && line[1]
== ' ') ? 2 : 0);
+                       strbuf_add_wrapped_text(sb, wrapped.buf, 0,
indent + hanging_indent, 80 - indent);


Gmail webclient mucks up the whitespace. Don't copy & paste ;)


As I said earlier in the mail, I'm not sure if this is something that
should be done by git. Maybe someone else can shed some light on that.


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

Re: Question about commit message wrapping

[Sidney San Martín]

Ah, thank you!

On Dec 9, 2011, at 11:49 AM, Frans Klaver wrote:

> I'm adding git@vger... again, cause there didn't seem to be a reason not to.
> 
> On Fri, Dec 9, 2011 at 3:10 PM, Sidney San Martín <s@sidneysm.com> wrote:
>> On Dec 9, 2011, at 2:05 AM, Frans Klaver wrote:
>> 
>>> 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.
>>> 
>> 
>> Interesting… either way, the end result is that the receiving mail client can wrap the lines to whatever length it (or you, as its operator) desires, which I think we can agree is a good thing, right?
>> 
> 
> Yes.
> 
>>> 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.
>>> 
>> 
>> That's my basic point. I hope it didn't seem like I was arguing against reading commit messages wrapped to 80 columns, by default. I only wanted to discuss whether it makes more sense to handle it on the display end instead of asking committers to do it in advance.
>> 
> 
> It somewhat looked like that. I think it might make sense for clients
> to ignore the line wrapping when they can only show less than 80
> characters on a line, but that would probably break the code part of a
> patch mail.
> 
> 
>> - My phone shows text most comfortably at about 40 characters per line. I do look at terminals at 80 columns most of the time, but not always, and I sometimes browse projects in GUI tools that use a proportional font in a window may be narrower or wider than that.
>> 
>> - Right now, when I *am* in an 80-col terminal I have to trust everyone else to wrap their commit messages. Not everyone does. I feel like it would be more effective to give git the ability to wrap them automatically when I read them.
>> 
> 
> It could be a useful option to wrap when the lines extend the window
> width, but I'd actually think it's better to leave that up to the
> pager than to git.
> 
>>>> 
>>>> 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 ;).
>>> 
>> 
>> Sorry, I'm not sure what you mean by, “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”.
> 
> I thought you might want to have wrapped text in the git commit
> messages, but actually put a format flowed tag into the mail header.
> I'm not sure what that would do to the code though.
> 
> 
>> Interesting, I didn't realize that Mail didn't use it. It does, however, use quoted-printable which, as far as I can tell, has a similar effect on line wrapping. What happens when you view this email in mutt?
>> 
> 
> I had no idea quoted printable had any effect on line wrapping. As far
> as I know it's just a way to encode non-ascii characters in 7bit, no
> more no less. Your current e-mail happens to end lines with =<nl>,
> which probably handles the wrapping. Your original message didn't have
> that.
> 
> 
>>>> - - -
>>>> 
>>>> 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.
>> 
>> Good point, that makes it clearer either way. I put an updated patch at the bottom of this email (also fixed forgetting the newline after lines with leading whitespace). I hope it's OK to include patches this way, I understand that they're supposed to represent whole emails but want to include them with this discussion.
>> 
> 
> You can include them in the discussion. While it is probably OK to put
> some code into your mail to propose something (I've seen it happen
> more than once), the end result is supposed to be submitted with a
> git-format-patch'd commit. You can read more about contributing in
> Documentation/SubmittingPatches.
> 
> 
>>> 
>>> 
>>>> +                    strbuf_addch(sb, '\n');
>>>> +            }
>>>>      }
>>>> }
>>>> 
>>> 
>>> Cheers,
>>> Frans
>> 
>> 
>> From 53fd7deedaf5ac522c9d752e79cf71561cc57f07 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 |    9 ++++++++-
>>  1 files changed, 8 insertions(+), 1 deletions(-)
>> 
>> diff --git a/pretty.c b/pretty.c
>> index 230fe1c..841ccd1 100644
>> --- a/pretty.c
>> +++ b/pretty.c
>> @@ -1243,7 +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);
>> +               if (line[0] == ' ' || line[0] == '\t') {
>> +                       strbuf_add(sb, line, linelen);
>> +               } else {
>> +                       struct strbuf wrapped = STRBUF_INIT;
>> +                       strbuf_add(&wrapped, line, linelen);
>> +                       int hanging_indent = ((line[0] == '-' && line[1] == ' ') ? 2 : 0);
>> +                       strbuf_add_wrapped_text(sb, wrapped.buf, 0, indent + hanging_indent, 80 - indent);
> 
> It's common in C (and in certain flavors even required) to have your
> variable declaration at the beginning of the scope:
> 
> +               } else {
> +                       int hanging_indent;
> +                       struct strbuf wrapped = STRBUF_INIT;
> +                       strbuf_add(&wrapped, line, linelen);
> +                       hanging_indent = ((line[0] == '-' && line[1]
> == ' ') ? 2 : 0);
> +                       strbuf_add_wrapped_text(sb, wrapped.buf, 0,
> indent + hanging_indent, 80 - indent);
> 
> 
> Gmail webclient mucks up the whitespace. Don't copy & paste ;)
> 
> 
> As I said earlier in the mail, I'm not sure if this is something that
> should be done by git. Maybe someone else can shed some light on that.
> 
> 
>> +               }
>>                strbuf_addch(sb, '\n');
>>        }
>>  }
>> --
>> 1.7.8
>> 
>> 

Re: Question about commit message wrapping

[Sidney San Martín]

On Dec 9, 2011, at 8:41 AM, Jakub Narebski wrote:

> Sidney San Martín <s@sidneysm.com> writes:
> 
>> *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.
> 
> The problem with automatic wrapping on the display is that there could
> be parts of commit message that *shouldn't* be wrapped, like code
> sample, or URL... and in plain text you don't have a way to separate
> flowed from non-flowed part.
> 

I usually lead code, URLs, and other preformatted lines like this with a few spaces. Markdown uses the same convention, and it looks like commits in this repo do too.

The patch in my last email prints lines which begin with whitespace verbatim. How does that work?

> Also with long non-breakable identifiers you sometimes need to wrap by
> hand (or use linebreaking algorithm from TeX) or go bit over the limit
> to make it look nice.
> 

Could you elaborate on this? The patch uses strbuf_add_wrapped_text, which was already in Git. If an identifier is longer than the wrap width, it leaves it alone.

> BTW. proper editor used to create commit message can wrap it for you
> ;-).

Only if everybody else in the world does it too! And only if I never care about seeing my commits at any width besides 80 columns.

> -- 
> Jakub Narębski
> 

Re: Question about commit message wrapping

[Andreas Schwab]

Sidney San Martín <s@sidneysm.com> writes:

> Interesting… either way, the end result is that the receiving mail client can wrap the lines to whatever length it (or you, as its operator) desires, which I think we can agree is a good thing, right?

Only if format=flowed.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Question about commit message wrapping

[Jakub Narebski]

On Fri, 9 Dec 2011, Sidney San Martín wrote:
> On Dec 9, 2011, at 8:41 AM, Jakub Narebski wrote:
>> Sidney San Martín <s@sidneysm.com> writes:
>> 
>>> *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.
>> 
>> The problem with automatic wrapping on the display is that there could
>> be parts of commit message that *shouldn't* be wrapped, like code
>> sample, or URL... and in plain text you don't have a way to separate
>> flowed from non-flowed part.
 
Additional and the more serious problem with wrapping on output is
related to backward compatibility.  If you have commit message that is
wrapped e.g. to 80 characters, and you wrap on output to 72 characters,
you would get ugly and nigh unreadable ragged output:

original:

  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
  tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
  veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
  commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
  velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
  occaecat cupidatat non proident, sunt in culpa qui officia deserunt
  mollit anim id est laborum.

wrapped to 70th column:

  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
  eiusmod
  tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
  minim
  veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
  ex ea
  commodo consequat. Duis aute irure dolor in reprehenderit in
  voluptate
  velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
  occaecat cupidatat non proident, sunt in culpa qui officia deserunt
  mollit anim id est laborum.

You can re-wrap, but this is more code, and additional problems, like
with ASCII-art like this or pseudo-Markdown headers like this
               ^^^^^^^^^

  Header
  ======
 
> I usually lead code, URLs, and other preformatted lines like this with
> a few spaces. Markdown uses the same convention, and it looks like
> commits in this repo do too.  
> 
> The patch in my last email prints lines which begin with whitespace
> verbatim. How does that work? 

What about lists done using hanging indent, e.g.:

  * Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
or

  - Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua.

or

 1. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
    eiusmod tempor incididunt ut labore et dolore magna aliqua.

>> Also with long non-breakable identifiers you sometimes need to wrap by
>> hand (or use linebreaking algorithm from TeX) or go bit over the limit
>> to make it look nice.
> 
> Could you elaborate on this? The patch uses strbuf_add_wrapped_text,
> which was already in Git. If an identifier is longer than the wrap
> width, it leaves it alone.  

The line breaking algorithm of TeX typesetting engine takes into account
look of whole paragraph (well, mathematical representation of "good look")
before breaking lines and hyphenating words.

What I meant here that if you have long identifier, naive line-breaking
(word-wrapping) algorithm could leave the paragraph unbalanced, with one
or more lines much shorter than the rest, while allowing one line to be
overly long over 1 character leads to nicely wrapped result.


BTW. In Polish (and Czech) typography there is rule that you don't leave
single-letter prepositions like 'i' ('and' in English) hanging at the end
of the line... automatic wrapper cannot ensure that.
 
>> BTW. proper editor used to create commit message can wrap it for you
>> ;-).
> 
> Only if everybody else in the world does it too!

Educate.

> And only if I never care about seeing my commits at any width besides
> 80 columns.  

Overly long lines are hard to read, and sometimes fit-to-width would give
us too long lines to read comfortably.


Anyway I am not against adding support for wrapping commit message and
tag payload, but IMHO it must be *optional*: --no-wrap, --wrap=auto
(or just --wrap), --wrap=80, and log.wrap or core.wrap.

-- 
Jakub Narebski
Poland

Re: Question about commit message wrapping

[Andrew Ardill]

Hi,

On Sunday, December 11, 2011, Jakub Narebski <jnareb@gmail.com> wrote:
...

> Additional and the more serious problem with wrapping on output is
> related to backward compatibility.  If you have commit message that is
> wrapped e.g. to 80 characters, and you wrap on output to 72 characters,
> you would get ugly and nigh unreadable ragged output

For what it's worth, I do a lot of reading emails on my phone, which
force wraps line-length to the width of the display (not a set number
of characters).
This is always less than 80.

Emails on this list are almost exclusively sent pre-wrapped to 80
character line lengths.
The result is exactly the kind of ragged output you used in your
example. Changing this behaviour may break backwards compatibility,
but it is already broken for 'future' compatibility.

Regards,

Andrew Ardill

Re: Question about commit message wrapping

[Frans Klaver]

On Sun, Dec 11, 2011 at 11:00 PM, Andrew Ardill <andrew.ardill@gmail.com> wrote:

>> Additional and the more serious problem with wrapping on output is
>> related to backward compatibility.  If you have commit message that is
>> wrapped e.g. to 80 characters, and you wrap on output to 72 characters,
>> you would get ugly and nigh unreadable ragged output
>
> For what it's worth, I do a lot of reading emails on my phone, which
> force wraps line-length to the width of the display (not a set number
> of characters).
> This is always less than 80.

Good point.

>
> Emails on this list are almost exclusively sent pre-wrapped to 80
> character line lengths.
> The result is exactly the kind of ragged output you used in your
> example. Changing this behaviour may break backwards compatibility,
> but it is already broken for 'future' compatibility.

I am starting to think that we need to somehow keep the current
behavior, but override at smaller widths. Maybe even use format=flowed
in format-patch. On the other hand, the fundamental use with git is to
communicate code, and I'm not sure how that [cw]ould be handled.

Re: Question about commit message wrapping

[Holger Hellmuth]

On 12.12.2011 09:41, Frans Klaver wrote:
>> Emails on this list are almost exclusively sent pre-wrapped to 80
>> character line lengths.
>> The result is exactly the kind of ragged output you used in your
>> example. Changing this behaviour may break backwards compatibility,
>> but it is already broken for 'future' compatibility.

I don't really see backwards compatibility broken either. At the moment 
commit messages are usually pre-wrapped at 72 columns, which looks 
perfect only on 80 column displays, ok on wider displays and bad on 
narrow displays.

If the requirement to pre-wrap would fall and either 'git log' or 'less' 
doing the wrap, old commit messages would still look perfect on 80 
column, ok on wider and bad on narrow displays. Newer commit messages 
would look good everywhere.

The only breakage would be that new long commit messages would look bad 
on older git versions. Because of that the auto-wrap should be 
implemented first and the "requirement" for 72 columns should fall in a 
later version.

> I am starting to think that we need to somehow keep the current
> behavior, but override at smaller widths. Maybe even use format=flowed
> in format-patch.

Could you explain what overriding at smaller widths would achieve? 
Supporting format=flowed would be nice though.

> On the other hand, the fundamental use with git is to
> communicate code, and I'm not sure how that [cw]ould be handled.

I prefer wrapped code to code that is cut of at a specific column. 
Wrapped code has much less possibility for misinterpretation. Python 
programmers might disagree?

I see your proposal mainly as an improvement to the display of texts, 
not code.

Re: Question about commit message wrapping

[Frans Klaver]

On Mon, 12 Dec 2011 17:37:13 +0100, Holger Hellmuth <hellmuth@ira.uka.de>  
wrote:

>> I am starting to think that we need to somehow keep the current
>> behavior, but override at smaller widths. Maybe even use format=flowed
>> in format-patch.
>
> Could you explain what overriding at smaller widths would achieve?  
> Supporting format=flowed would be nice though.

I specifically meant trying to detect pre-wrapped text, removing the  
new-lines where we think it is because of wrapping at 80 characters. So  
the result would be: perfect on screens up to 80 characters wide, and ok  
on anything wider.

The implementation of that however could affect code in the mail if it  
isn't done properly.

>
>> On the other hand, the fundamental use with git is to
>> communicate code, and I'm not sure how that [cw]ould be handled.
>
> I prefer wrapped code to code that is cut of at a specific column.  
> Wrapped code has much less possibility for misinterpretation. Python  
> programmers might disagree?

Wrapped code as in auto-wrapped? Or as in manually wrapped? Python  
programmers have significant white space, but you can still hard wrap  
stuff, as long as the next statement is properly indented.

>
> I see your proposal mainly as an improvement to the display of texts,  
> not code.

Me too.


-- 
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/

Re: Question about commit message wrapping

[Michael Haggerty]

On 12/12/2011 11:16 PM, Frans Klaver wrote:
> Wrapped code as in auto-wrapped? Or as in manually wrapped? Python
> programmers have significant white space, but you can still hard wrap
> stuff, as long as the next statement is properly indented.

This is incorrect.  Python statements can only be broken across lines
within unbalanced parenthesis (or using '\' or within a multiline
string).  For example,

    x =
        1

is a syntax error, while

    y = (
        1
        )

or

    f(1,
          2,
      3,
      4)

are both valid.

FWIW I think automatic wrapping of commit messages is a bad idea.  I
wrap my commit messages deliberately to make them look the way I want
them to look.  The assumption of an 80-character display has historical
reasons, but it is also a relatively comfortable line-width to read
(even on wider displays).  And given that commit messages sometimes
contain "flowable" paragraph text, sometimes code snippets, sometimes
ASCII art, etc, no automatic wrapping will work correctly unless
everybody agrees that commit messages must be written in some specific
form of markup (or lightweight markup).  And I can't imagine such a
thing ever happening.

As for "future-proofing", do you really think there will be a lot of
programming happening on mobile phones with less than 80-character-wide
displays?  (And even my little HTC can easily fit 80 characters if I
rotate the phone to "landscape" mode.)

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Re: Question about commit message wrapping

[Frans Klaver]

On Tue, 13 Dec 2011 04:14:36 +0100, Michael Haggerty  
<mhagger@alum.mit.edu> wrote:

> On 12/12/2011 11:16 PM, Frans Klaver wrote:
>> Wrapped code as in auto-wrapped? Or as in manually wrapped? Python
>> programmers have significant white space, but you can still hard wrap
>> stuff, as long as the next statement is properly indented.
>
> This is incorrect.  Python statements can only be broken across lines
> within unbalanced parenthesis (or using '\' or within a multiline
> string).  For example,
>
>     x =
>         1
>
> is a syntax error, while
>
>     y = (
>         1
>         )
>
> or
>
>     f(1,
>           2,
>       3,
>       4)
>
> are both valid.

Hm yes, my statement was quite incomplete. What you describe here is what  
I meant, and I should have taken the time to word it down properly. Thanks  
for taking the time to do so.



>
> FWIW I think automatic wrapping of commit messages is a bad idea.  I
> wrap my commit messages deliberately to make them look the way I want
> them to look.  The assumption of an 80-character display has historical
> reasons, but it is also a relatively comfortable line-width to read
> (even on wider displays).  And given that commit messages sometimes
> contain "flowable" paragraph text, sometimes code snippets, sometimes
> ASCII art, etc, no automatic wrapping will work correctly unless
> everybody agrees that commit messages must be written in some specific
> form of markup (or lightweight markup).  And I can't imagine such a
> thing ever happening.
>
> As for "future-proofing", do you really think there will be a lot of
> programming happening on mobile phones with less than 80-character-wide
> displays?  (And even my little HTC can easily fit 80 characters if I
> rotate the phone to "landscape" mode.)

Makes sense.

Re: Question about commit message wrapping

[Holger Hellmuth]

On 13.12.2011 04:14, Michael Haggerty wrote:
> On 12/12/2011 11:16 PM, Frans Klaver wrote:
>> Wrapped code as in auto-wrapped? Or as in manually wrapped? Python
>> programmers have significant white space, but you can still hard wrap
>> stuff, as long as the next statement is properly indented.

I meant as in auto-wrapped and also not as a permanent change but 
something done to a long line on output to the screen.

> FWIW I think automatic wrapping of commit messages is a bad idea.  I
> wrap my commit messages deliberately to make them look the way I want

Which you still can do (since hard line endings would not be ignored). 
On displays wider than your line limit you will still see it exactly 
like intended. Only on narrow displays your commit message would look 
bad, admittedly even worse than cut-off lines.

> them to look.  The assumption of an 80-character display has historical
> reasons, but it is also a relatively comfortable line-width to read
> (even on wider displays).  And given that commit messages sometimes
> contain "flowable" paragraph text, sometimes code snippets, sometimes
> ASCII art, etc, no automatic wrapping will work correctly unless
> everybody agrees that commit messages must be written in some specific
> form of markup (or lightweight markup).  And I can't imagine such a
> thing ever happening.

With that assumption everyone could be happy with automatic wrapping of 
lines on screen output. You can hard wrap and it will look exactly as 
intended. In the same commit message you could also just write a 
paragraph without hitting the return-key at all and have a commit 
message that looks good in web browsers and too narrow gitk windows.

Re: Question about commit message wrapping

[Sidney San Martín]

On Dec 12, 2011, at 10:14 PM, Michael Haggerty wrote:

> FWIW I think automatic wrapping of commit messages is a bad idea.  I
> wrap my commit messages deliberately to make them look the way I want
> them to look.  The assumption of an 80-character display has historical
> reasons, but it is also a relatively comfortable line-width to read
> (even on wider displays).

A lot of Git repos live in heterogeneous environments. I played a little with some of the popular Git interfaces I can use on my computer. The majority of them…

- compose and show commit messages in a proportional font (where the width of and formatting in "80 characters" means nothing),
- don’t insert line breaks when you write a commit message (and don't provide a way to do so automatically),
- do wrap commit messages when showing them.

Jakub, you said that education was the answer to getting some consistency in line wrapping, but I have trouble imagining the makers of new tools using fixed-width text for anything other than code.

> And given that commit messages sometimes
> contain "flowable" paragraph text, sometimes code snippets, sometimes
> ASCII art, etc, no automatic wrapping will work correctly unless
> everybody agrees that commit messages must be written in some specific
> form of markup (or lightweight markup).  And I can't imagine such a
> thing ever happening.

The two biggest websites I know of for talking about code, GitHub and Stack Overflow, both adopted flavors of Markdown. It is basically the formatting syntax already used for commit messages in the Git project itself (this email too), so can be formatted to look good in a specific environment (i.e. proportional fonts) and looks good by itself.

(Actually, as far as I can tell commit messages are the only place GitHub doesn’t currently render user-entered text as Markdown.)

I think, now and in the future, consistency will be found most easily in in Markdown-like formatting and least in 80 columns of fixed-width text.

- - -

## Gitbox 1.5.1
- Commit messages written and displayed in a proportional font
- Does not insert line breaks when you commit
- When displaying a commit message, turns single line breaks into spaces and keeps double line breaks, wraps as needed based on the size of the viewing area (it's somewhat intelligent about this, it does preserve some line breaks; it doesn't preserve spaces used for formatting)

## Tower 1.0.3
- Commit messages written and displayed in a proportional font
- Does not insert line breaks when you commit. Collapses multiple newlines into a single newline
- When displaying a commit message, wraps at 100 characters and collapses multiple newlines into a single one

## GitHub (Mac app) 1.1.1
- Commit messages written and displayed in a proportional font
- Inserts line breaks after 73 characters when you commit (incl. in the middle of a long identifier)
- Does not wrap lines when displaying commit messages, and doesn’t provide a way to scroll to read them

## GitHub (website)
- Commit messages written and displayed in a fixed-width font
- Does not insert line breaks when you commit, input wraps, visually, at 113 characters
- When displaying a commit message, uses CSS to wrap the commit message to 700 pixels, 100 characters

## git (default configuration in a fresh Linux Mint live cd)
- Does not insert line breaks when you commit (using the default editor (nano) and pager (less, IIRC)
- Does not wrap lines when displaying commit messages.

Re: Question about commit message wrapping

[Sidney San Martín]

On Dec 10, 2011, at 2:30 PM, Jakub Narebski wrote:

> BTW. In Polish (and Czech) typography there is rule that you don't leave
> single-letter prepositions like 'i' ('and' in English) hanging at the end
> of the line... automatic wrapper cannot ensure that.

I meant to ask… how is that rule followed by browsers/on the web?

Re: Question about commit message wrapping

[Drew Northup]

FWIW, I'm leaving text in this email as my mail client found it (and not
reflowing as I usually do). You can clearly see the effect of one mail
client assuming that the end display is doing all of the wrapping (I'll
not name names). When I first read the mail it looked fine because my
mail client IGNORED the inconsistencies in line wrap modes.

On Wed, 2011-12-14 at 16:04 -0500, Sidney San Martín wrote:
> On Dec 12, 2011, at 10:14 PM, Michael Haggerty wrote:
> 
> > FWIW I think automatic wrapping of commit messages is a bad idea.  I
> > wrap my commit messages deliberately to make them look the way I want
> > them to look.  The assumption of an 80-character display has historical
> > reasons, but it is also a relatively comfortable line-width to read
> > (even on wider displays).
> 
> A lot of Git repos live in heterogeneous environments. I played a little with some of the popular Git interfaces I can use on my computer. The majority of them…
> 
> - compose and show commit messages in a proportional font (where the width of and formatting in "80 characters" means nothing),

In virtually all modern tools the default font is the "system default"
font, which is typically variable width. In some places I've even seen
variable pitch font rendering (I know there's a more technical term for
it, but I'm not taking the time to look it up right now) used, which is
distinct in that it makes the text easier to read when there are
potentially overlapping descenders and ascenders on adjoining lines
while leaving text without that feature unchanged in line spacing and
kerning. Try rendering ASCII-ART with that enabled!
However, it is a rare GUI tool that does not allow the user to change
the font to something more appropriate (I use fixed-width fonts for most
programming and scripting, but they are not any more helpful for reading
log messages for instance). Text-based programming tools usually just
use the console font, whatever it is--and woe be to the programmer who
switches their "console" font to something variable width. (Doing so
makes any application written with curses/ncurses in mind look very very
odd as well.)

> - don’t insert line breaks when you write a commit message (and don't provide a way to do so automatically),

Most of the "tools" I have seen that ignore all user-entered line breaks
are actually poorly written applications attempting to protect some sort
of backing database from an injection attack. Given that, many WIKI
systems typically ignore single line breaks when rendering (double line
breaks are taken to be paragraph breaks in those cases I am aware of),
so any argument about that quickly becomes moot as well. If somebody is
writing a tool that does not allow me to force multiple line breaks when
desired then so far as I am concerned their tool is broken. I don't see
a point in changing GIT as a whole because somebody writes a broken GUI
implementation.

> - do wrap commit messages when showing them.
> 
> Jakub, you said that education was the answer to getting some consistency in line wrapping, but I have trouble imagining the makers of new tools using fixed-width text for anything other than code.

Remember, as soon as you think you've idiot-proofed something somebody
builds a better idiot. That's why Jakub (and many others of us) would
prefer just to tell people about the way things are intended to work and
then get out of the way and let people make their own mistakes.

> > And given that commit messages sometimes
> > contain "flowable" paragraph text, sometimes code snippets, sometimes
> > ASCII art, etc, no automatic wrapping will work correctly unless
> > everybody agrees that commit messages must be written in some specific
> > form of markup (or lightweight markup).  And I can't imagine such a
> > thing ever happening.
> 
> The two biggest websites I know of for talking about code, GitHub and Stack Overflow, both adopted flavors of Markdown. It is basically the formatting syntax already used for commit messages in the Git project itself (this email too), so can be formatted to look good in a specific environment (i.e. proportional fonts) and looks good by itself.
> 
> (Actually, as far as I can tell commit messages are the only place GitHub doesn’t currently render user-entered text as Markdown.)
> 
> I think, now and in the future, consistency will be found most easily in in Markdown-like formatting and least in 80 columns of fixed-width text.

Given that there is little consensus even between Markdown-like
formatting methods (which have in some cases been around since the
advent of movable type presses, so far as I am aware) I have to agree
with Michael here.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Question about commit message wrapping

[Sidney San Martín]

Hey Drew. Sorry about the lag; I really appreciate your (and the other guys on the list) taking the time to write back. You made some interesting points in your last email and I want to respond to them.

- - -

It may come down to personal preference and how we are each used to editing text.

All the programs I use on a daily basis use soft line wrapping (not encoding any of the line breaks I see on screen into what I’m typing). Most of them use proportional type too. So, I guess I don’t *expect* to be able to manage how text wraps. Neither my email client nor the editor I use to write commit messages are set up for hard wrapping.

I posed the question to the list because having to switch into “I have to hit return every so often” mode (or play with my editor) to write commit message screws with my head, and lately I just stopped doing it in my own projects. I was wondering if anyone else was thinking along the same lines and would prefer to write their commits without line breaks (except to break paragraphs, lists, etc.).

On Jan 1, 2012, at 8:03 AM, Drew Northup wrote:

> FWIW, I'm leaving text in this email as my mail client found it (and not
> reflowing as I usually do). You can clearly see the effect of one mail
> client assuming that the end display is doing all of the wrapping (I'll
> not name names). When I first read the mail it looked fine because my
> mail client IGNORED the inconsistencies in line wrap modes.

That's interesting — it looks like my main mail client, Apple Mail, uses tricks (which I think we've discovered are mostly powered by quoted-printable encoding) to get around the old SMTP line length limits. (Is there where the differences in behavior between mail clients come from? I don't know much about the history.)

As a result, I’m not really sure what you mean. What effects and inconsistencies are you seeing? My phone, my computer, and my webmail (Google) all show pretty much the same thing: the lines from your and Michael’s emails are wrapped at ~72 characters, and the lines from my email are wrapped to the width of the window. But, they all look OK.

The only side effect is that on my phone, your/Michael’s text breaks about half way through every other line (since it's wrapped to a wider width than fits on the screen).

I don’t think I have ever manually reflowed text like you mention. When do you do it, and why?

(It may be that the thing I’m proposing wouldn’t be appropriate for git itself and other repos that use email to exchange patches. I use remotes for the repos I use on a daily basis, so I don’t have to deal with email clients like you guys do.)

> In virtually all modern tools the default font is the "system default"
> font, which is typically variable width. In some places I've even seen
> variable pitch font rendering (I know there's a more technical term for
> it, but I'm not taking the time to look it up right now) used, which is
> distinct in that it makes the text easier to read when there are
> potentially overlapping descenders and ascenders on adjoining lines
> while leaving text without that feature unchanged in line spacing and
> kerning. Try rendering ASCII-ART with that enabled!
> However, it is a rare GUI tool that does not allow the user to change
> the font to something more appropriate (I use fixed-width fonts for most
> programming and scripting, but they are not any more helpful for reading
> log messages for instance).

That’s not really the motivation behind my proposal, but I checked and actually none of the GUIs I tested before have options to change to a fixed-width font for commit messages.

It’s not really the point, though. Proportional type is nice! Have you ever seen Docco? It’s a tool that takes a well-commented source file like <http://documentcloud.github.com/backbone/backbone.js> and creates a beautiful two-column view like <http://documentcloud.github.com/backbone/docs/backbone.html> with the comments on one side in a nice (for text) proportional font and the code on the other in a nice (for code) monospaced one. The text and the code both each look great. I want the guys who develop the next generation of git clients to have the same freedom to make commit messages look great.

ASCII art in text has been a casualty of the rise of proportional type… but there are ways to save it (GitHub’s code blocks are an example); teaching everyone (and forcing the tools) to format text the old way is, I believe, the wrong approach.

> Text-based programming tools usually just
> use the console font, whatever it is--and woe be to the programmer who
> switches their "console" font to something variable width. (Doing so
> makes any application written with curses/ncurses in mind look very very
> odd as well.)

What about manpages? They use the console font but lines get wrapped to the width of the terminal (and I want this feature of git to do that, too). They’re *not* preformatted in terms of width.

>> - don’t insert line breaks when you write a commit message (and don't provide a way to do so automatically),
> 
> Most of the "tools" I have seen that ignore all user-entered line breaks
> are actually poorly written applications attempting to protect some sort
> of backing database from an injection attack. Given that, many WIKI
> systems typically ignore single line breaks when rendering (double line
> breaks are taken to be paragraph breaks in those cases I am aware of),
> so any argument about that quickly becomes moot as well. If somebody is
> writing a tool that does not allow me to force multiple line breaks when
> desired then so far as I am concerned their tool is broken. I don't see
> a point in changing GIT as a whole because somebody writes a broken GUI
> implementation.

Misunderstanding — the tools I tested don’t insert don’t insert line breaks for you to help you wrap your commit messages to a certain width. They keep user-entered line breaks (but since they use proportional type and lack column counters, there’s no way to wrap to 72 columns, even by hand, except by copying and pasting from another editor… or counting).

> 
>> - do wrap commit messages when showing them.
>> 
>> Jakub, you said that education was the answer to getting some consistency in line wrapping, but I have trouble imagining the makers of new tools using fixed-width text for anything other than code.
> 
> Remember, as soon as you think you've idiot-proofed something somebody
> builds a better idiot. That's why Jakub (and many others of us) would
> prefer just to tell people about the way things are intended to work and
> then get out of the way and let people make their own mistakes.

See above, this isn’t idiot-proofing. New tools use proportional fonts because they’re more readable, and soft wrapping because it makes sense in the context that they create and read commit messages.

>>> And given that commit messages sometimes
>>> contain "flowable" paragraph text, sometimes code snippets, sometimes
>>> ASCII art, etc, no automatic wrapping will work correctly unless
>>> everybody agrees that commit messages must be written in some specific
>>> form of markup (or lightweight markup).  And I can't imagine such a
>>> thing ever happening.
>> 
>> The two biggest websites I know of for talking about code, GitHub and Stack Overflow, both adopted flavors of Markdown. It is basically the formatting syntax already used for commit messages in the Git project itself (this email too), so can be formatted to look good in a specific environment (i.e. proportional fonts) and looks good by itself.
>> 
>> (Actually, as far as I can tell commit messages are the only place GitHub doesn’t currently render user-entered text as Markdown.)
>> 
>> I think, now and in the future, consistency will be found most easily in in Markdown-like formatting and least in 80 columns of fixed-width text.
> 
> Given that there is little consensus even between Markdown-like
> formatting methods (which have in some cases been around since the
> advent of movable type presses, so far as I am aware) I have to agree
> with Michael here.

I think that the syntax laid out at <http://daringfireball.net/projects/markdown/syntax> is pretty consistently-used. Any differences that you think would affect this case? I think only a small subset would be relevant (paragraph breaks, ordered and unordered lists, and indented code blocks) and every implementation I’ve seen handles those the same way.

I think that supporting this small subset, and only for users who turn it on, would work. It matches how many commits are already formatted, there’s nothing new to learn.

P.S. Happy belated New Year!