On Fri, 09 Dec 2011 02:59:06 +0100, Sidney San Martín <s@xxxxxxxxxxxx>
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@xxxxxxxxxxxx>
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html