Re: Question about commit message wrapping

From: Jakub Narebski <jnareb@gmail.com>
Date: Dec 10, 2011, 19:30 UTC
Message-ID: <201112102030.15504.jnareb@gmail.com>
In-Reply-To: <E085218D-9287-4F82-B34C-8379742F818A@sidneysm.com>

On Fri, 9 Dec 2011, Sidney San Martín wrote:

Show 12 quoted lines

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

Show 6 quoted lines

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

Show 7 quoted lines

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