emacs-diffs emails can get long subject if log starts with "*"

emacs-diffs emails can get long subject if log starts with "*"

[Glenn Morris]

So as an FYI, it looks like:

If you start your commit message with a "*" (which is quite a common
practice for Emacs), git-multimail ignores line-breaks in your commit
log, and stuffs the entire log into the subject of the mail that it
sends out to emacs-diffs.

Eg
http://lists.gnu.org/archive/html/emacs-diffs/2014-11/msg00436.html
http://lists.gnu.org/archive/html/emacs-diffs/2014-11/msg00375.html

Re: emacs-diffs emails can get long subject if log starts with "*"

[Andreas Schwab]

Glenn Morris <rgm@gnu.org> writes:

> If you start your commit message with a "*" (which is quite a common
> practice for Emacs), git-multimail ignores line-breaks in your commit
> log, and stuffs the entire log into the subject of the mail that it
> sends out to emacs-diffs.

This has nothing to do with the asterisk.  The first paragraph of the
log message is taken to be the summary.  You get the same behaviour with
git format-patch or git log --oneline.

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: emacs-diffs emails can get long subject if log starts with "*"

[Glenn Morris]

Andreas Schwab wrote:

> This has nothing to do with the asterisk.  The first paragraph of the
> log message is taken to be the summary.  You get the same behaviour with
> git format-patch or git log --oneline.

OK.

Seems dumb to me for a thing that sends out mails not to include a check
on subject length, so I'll probably attempt to patch that in.

Also seems dumb to me to ignore line-breaks, and insist on paragrpah
breaks, but whatever.

Re: emacs-diffs emails can get long subject if log starts with "*"

[Glenn Morris]

Glenn Morris wrote:

> Also seems dumb to me to ignore line-breaks, and insist on paragraph
> breaks, but whatever.

Eg over 700 Emacs commits have a "oneline" log of over 1000 characters.

git log -1 --format=oneline 0e362f54037b2f8271c905a39278fa3fa5fc7a1b 

18500 chars!

Re: emacs-diffs emails can get long subject if log starts with "*"

[Glenn Morris]

Ah, something like

git log -1 --oneline --format="%h %<(70,trunc)%s" 0e362f54037b2f8271c905a39278fa3fa5fc7a1b

restores sanity.

Re: emacs-diffs emails can get long subject if log starts with "*"

[Paul Eggert]

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

To help avoid this sort of problem in future commits, I installed the attached 
patch into the emacs-24 branch.  Once you bootstrap or run autogen.sh, it 
arranges for Git commit hooks that verify that a commit's file names are 
portable and that the commit messages are reasonable.  It's common practice in 
other projects to have commit hooks with sanity checks.  No doubt the details 
can use some tweaking for Emacs; this is just a first cut.

[-- Attachment #2: 0001-Add-git-commit-hooks-that-do-some-simple-checks-on-c.patch --]
[-- Type: text/x-diff, Size: 6095 bytes --]

From acd837f97f5701a3ebdb1bbdd79fac4ed8153629 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 22 Nov 2014 15:46:17 -0800
Subject: [PATCH] Add git commit hooks that do some simple checks on commits.

* autogen.sh: Install Git hooks, if using Git.
* build-aux/git-hooks/commit-msg, build-aux/git-hooks/pre-commit:
New files, which are Git hooks that check for portable file names, and
do some simple checks for commit message format.
---
 autogen.sh                     | 40 +++++++++++++++++++
 build-aux/git-hooks/commit-msg | 90 ++++++++++++++++++++++++++++++++++++++++++
 build-aux/git-hooks/pre-commit | 46 +++++++++++++++++++++
 3 files changed, 176 insertions(+)
 create mode 100755 build-aux/git-hooks/commit-msg
 create mode 100755 build-aux/git-hooks/pre-commit

diff --git a/autogen.sh b/autogen.sh
index bc8a73d..69812cd 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -208,6 +208,46 @@ autoreconf -i -I m4 || exit $?
 ## cause 'make' to needlessly run 'autoheader'.
 echo timestamp > src/stamp-h.in || exit
 
+## Install Git hooks, if using Git.
+if test -d .git/hooks; then
+    tailored_hooks=
+    sample_hooks=
+
+    for hook in commit-msg pre-commit; do
+	cmp build-aux/git-hooks/$hook .git/hooks/$hook >/dev/null 2>&1 ||
+	tailored_hooks="$tailored_hooks $hook"
+    done
+    for hook in applypatch-msg pre-applypatch; do
+	cmp .git/hooks/$hook.sample .git/hooks/$hook >/dev/null 2>&1 ||
+	sample_hooks="$sample_hooks $hook"
+    done
+
+    if test -n "$tailored_hooks$sample_hooks"; then
+	echo "Installing git hooks..."
+
+	case `cp --help 2>/dev/null` in
+	  *--backup*--verbose*)
+	    cp_options='--backup=numbered --verbose';;
+	  *)
+	    cp_options='';;
+	esac
+
+	if test -n "$tailored_hooks"; then
+	    for hook in $tailored_hooks; do
+		cp $cp_options build-aux/git-hooks/$hook .git/hooks || exit
+		chmod a-w .git/hooks/$hook || exit
+	    done
+	fi
+
+	if test -n "$sample_hooks"; then
+	    for hook in $sample_hooks; do
+		cp $cp_options .git/hooks/$hook.sample .git/hooks/$hook || exit
+		chmod a-w .git/hooks/$hook || exit
+	    done
+	fi
+    fi
+fi
+
 echo "You can now run \`./configure'."
 
 exit 0
diff --git a/build-aux/git-hooks/commit-msg b/build-aux/git-hooks/commit-msg
new file mode 100755
index 0000000..6a09edd
--- /dev/null
+++ b/build-aux/git-hooks/commit-msg
@@ -0,0 +1,90 @@
+#!/bin/sh
+# Check the format of GNU Emacs change log entries.
+
+# Copyright 2014 Free Software Foundation, Inc.
+
+# This file is part of GNU Emacs.
+
+# GNU Emacs is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# GNU Emacs is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+
+# Written by Paul Eggert.
+
+# Use a UTF-8 locale if available, so that the UTF-8 check works.
+# Use U+00A2 CENT SIGN to test whether the locale works.
+cent_sign_utf8_octal='\302\242'
+at_sign=`
+  printf "${cent_sign_utf8_octal}@" |
+  awk '{print substr($0, 2)}' 2>/dev/null
+`
+if test "$at_sign" != @; then
+  at_sign=`
+    printf "${cent_sign_utf8_octal}@" |
+    LC_ALL=en_US.utf8 awk '{print substr($0, 2)}' 2>/dev/null
+  `
+  if test "$at_sign" = @; then
+    LC_ALL=en_US.utf8; export LC_ALL
+  fi
+fi
+
+# Check the log entry.
+exec awk '
+  /^#/ { next }
+
+  !/^.*$/ {
+    print "Invalid character (not UTF-8)"
+    status = 1
+  }
+
+  nlines == 0 && !/[^[:space:]]/ { next }
+
+  { nlines++ }
+
+  nlines == 1 && /^[[:space:]]/ {
+    print "White space at start of first line"
+    status = 1
+  }
+
+  nlines == 2 && /[^[:space:]]/ {
+    print "Nonempty second line"
+    status = 1
+  }
+
+  /[[:cntrl:]]/ {
+    print "Text contains control character; please use spaces instead of tabs"
+    status = 1
+  }
+
+  72 < length && /[[:space:]]/ {
+    print "Line longer than 72 characters"
+    status = 1
+  }
+
+  140 < length {
+    print "Word longer than 140 characters"
+    status = 1
+  }
+
+  /^Signed-off-by: / {
+    print "'Signed-off-by:' present"
+    status = 1
+  }
+
+  END {
+    if (nlines == 0) {
+      print "Empty change log entry"
+      status = 1
+    }
+    exit status
+  }
+' <"$1"
diff --git a/build-aux/git-hooks/pre-commit b/build-aux/git-hooks/pre-commit
new file mode 100755
index 0000000..c24f9bb
--- /dev/null
+++ b/build-aux/git-hooks/pre-commit
@@ -0,0 +1,46 @@
+#!/bin/sh
+# Check file names in git commits for GNU Emacs.
+
+# Copyright 2014 Free Software Foundation, Inc.
+
+# This file is part of GNU Emacs.
+
+# GNU Emacs is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# GNU Emacs is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+
+LC_ALL=C
+export LC_ALL
+
+exec >&2
+
+. git-sh-setup
+
+git_diff='git diff --cached --name-only --diff-filter=A'
+ok_chars='\0+[=-=]./0-9A-Z_a-z'
+nbadchars=`$git_diff -z HEAD | tr -d "$ok_chars" | wc -c`
+
+if test "$nbadchars" -ne 0; then
+  echo "File name does not consist of -+./_ or ASCII letters or digits."
+  exit 1
+fi
+
+new_names=`$git_diff HEAD` || exit
+case "
+$new_names" in
+  */-* | *'
+'-*)
+    echo "File name component begins with '-'."
+    exit 1;;
+esac
+
+exec git diff-index --check --cached HEAD --
-- 
1.9.3

Re: emacs-diffs emails can get long subject if log starts with "*"

[Yuri Khan]

On Sun, Nov 23, 2014 at 5:06 AM, Glenn Morris <rgm@gnu.org> wrote:

>> This has nothing to do with the asterisk.  The first paragraph of the
>> log message is taken to be the summary.  You get the same behaviour with
>> git format-patch or git log --oneline.
>
> Seems dumb to me for a thing that sends out mails not to include a check
> on subject length, so I'll probably attempt to patch that in.

Please don’t.

Git was designed around the patch emailing workflow. One commit is one
email message. The commit message summary is the subject. The rest of
the commit message is the message body. The actual diffs are either
attached or included inline.

The subject line’s role is to draw reader interest in a mailing list,
and to serve as an anchor for subsequent searches via the list of
messages. Similarly, the commit message summary’s role is to draw
reviewer interest, and to serve as an anchor for searches via git log
and gitk.

Many graphical MUAs and Git repository browsers handle long subjects
and summaries just fine.

Instead of arbitrarily chopping the subject line, we should all be
writing commits with concise and meaningful summaries.

Re: emacs-diffs emails can get long subject if log starts with "*"

[Thien-Thi Nguyen]

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

Re: emacs-diffs emails can get long subject if log starts with "*"

[Rüdiger Sonderfeld]

On Saturday 22 November 2014 18:06:15 Glenn Morris wrote:
> Seems dumb to me for a thing that sends out mails not to include a check
> on subject length, so I'll probably attempt to patch that in.
> 
> Also seems dumb to me to ignore line-breaks, and insist on paragrpah
> breaks, but whatever.

That's why the recommendation for git is to limit the first line to 50 
characters.  This of course conflicts with the common practice in Emacs to 
simply use the ChangeLog entry as the commit message.  I personally try to 
write the commit messages in a git-friendly format and append the ChangeLog 
entry (if it is necessary) as its own paragraph.  I would suggest to make this 
common practice to improve the compatibility with the existing git tools.  But 
of course we can't got back and change all of the history to confirm.

btw. there is a git-commit-mode (used by magit), which checks for this rule.

Regards,
Rüdiger

Re: emacs-diffs emails can get long subject if log starts with "*"

[Eli Zaretskii]

> Date: Sun, 23 Nov 2014 11:44:25 +0700
> From: Yuri Khan <yuri.v.khan@gmail.com>
> Cc: Andreas Schwab <schwab@linux-m68k.org>,
> 	Emacs developers <emacs-devel@gnu.org>
> 
> Instead of arbitrarily chopping the subject line, we should all be
> writing commits with concise and meaningful summaries.

But until that idyll happens, do we really want 1000-character Subject
lines?

Re: emacs-diffs emails can get long subject if log starts with "*"

[Eli Zaretskii]

> From: Rüdiger Sonderfeld <ruediger@c-plusplus.de>
> Date: Sun, 23 Nov 2014 17:04:36 +0100
> Cc: Andreas Schwab <schwab@linux-m68k.org>
> 
> That's why the recommendation for git is to limit the first line to 50 
> characters.

That's way to few for a meaningful summary of the commit.  I normally
need at least 70, sometimes more.

> This of course conflicts with the common practice in Emacs to simply
> use the ChangeLog entry as the commit message.

There's no such practice.  Committers are requested to come up with a
summary line, and use the ChangeLog entry below that, as a separate
paragraph.  The ChangeLog entry can serve as the summary line only if
it's a single line, and there's nothing to be said except what that
one line does.

Re: emacs-diffs emails can get long subject if log starts with "*"

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Maybe we should write a front end that reformats git summaries to look
nicer in our case.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: emacs-diffs emails can get long subject if log starts with "*"

[Glenn Morris]

Rüdiger Sonderfeld wrote:

>> Also seems dumb to me to ignore line-breaks, and insist on paragrpah
>> breaks, but whatever.
>
> That's why the recommendation for git is to limit the first line to 50 
> characters. 

"First line summarizes the commit" is fine by me. What I find dumb is
the requirement for that first line to be followed by a blank line, not
a new line.

Because
who
needs
to
write
50
characters
like
this?

For example, just now I wanted to use a commit log which was about 1.5
lines long in total, but had a natural break (for a comma) at the end of
the first line. Rather than rewrite it as "1 + blank + 1.5 lines", I
simply dropped the last half line.

If a newline marked the end of the summary/title/whatever, then
log --oneline (and emacs-diffs subjects) would look fine, with no action
needed.

But obviously it isn't going to change, so we need to learn new habits,
and write little tools to enforce said habits.

Re: emacs-diffs emails can get long subject if log starts with "*"

[Andreas Schwab]

Glenn Morris <rgm@gnu.org> writes:

> "First line summarizes the commit" is fine by me. What I find dumb is
> the requirement for that first line to be followed by a blank line, not
> a new line.

https://git.kernel.org/cgit/git/git.git/commit/?id=4234a76

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: emacs-diffs emails can get long subject if log starts with "*"

[Stefan Monnier]

> This has nothing to do with the asterisk.  The first paragraph of the
> log message is taken to be the summary.  You get the same behaviour with
> git format-patch or git log --oneline.

Oh, really, is that how Git defines the "summary"?  I thought it was
just the first line; and I assumed the email program was just buggy in
this respect.

Then vc-git.el should probably be fixed accordingly to add an empty line
to separate the summary from the rest.


        Stefan

Re: emacs-diffs emails can get long subject if log starts with "*"

[Andreas Schwab]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> Then vc-git.el should probably be fixed accordingly to add an empty line
> to separate the summary from the rest.

That's what log-edit-extract-headers does.

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