Merge branch 'maint'

* maint:
  git-send-email.txt: move --format-patch paragraph to a proper location
  git-shortlog.txt: improve documentation about .mailmap files
  pretty: support multiline subjects with format:
  pretty: factor out format_subject()
  pretty: factor out skip_empty_lines()
  merge-file: handle freopen() failure
  daemon: cleanup: factor out xstrdup_tolower()
  daemon: cleanup: replace loop with if
  daemon: handle freopen() failure
  describe: Avoid unnecessary warning when using --all

2 files changed, 39 insertions, 13 deletions

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 12788667d..b69846e52 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -197,12 +197,6 @@ Administering
 --[no-]validate::
 	Perform sanity checks on patches.
 	Currently, validation means the following:
-
---[no-]format-patch::
-	When an argument may be understood either as a reference or as a file name,
-	choose to understand it as a format-patch argument ('--format-patch')
-	or as a file name ('--no-format-patch'). By default, when such a conflict
-	occurs, git send-email will fail.
 +
 --
 		*	Warn of patches that contain lines longer than 998 characters; this
@@ -212,6 +206,12 @@ Administering
 Default is the value of 'sendemail.validate'; if this is not set,
 default to '--validate'.
 
+--[no-]format-patch::
+	When an argument may be understood either as a reference or as a file name,
+	choose to understand it as a format-patch argument ('--format-patch')
+	or as a file name ('--no-format-patch'). By default, when such a conflict
+	occurs, git send-email will fail.
+
 
 CONFIGURATION
 -------------
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index 7ccf31ccc..8f7c0e226 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -48,15 +48,41 @@ OPTIONS
 FILES
 -----
 
-If the file `.mailmap` exists, it will be used for mapping author
-email addresses to a real author name. One mapping per line, first
-the author name followed by the email address enclosed by
-'<' and '>'. Use hash '#' for comments. Example:
+If a file `.mailmap` exists at the toplevel of the repository,
+it is used to map an author email address to a canonical real name. This
+can be used to coalesce together commits by the same person where their
+name was spelled differently (whether with the same email address or
+not).
+
+Each line in the file consists, in this order, of the canonical real name
+of an author, whitespace, and an email address (enclosed by '<' and '>')
+to map to the name. Use hash '#' for comments, either on their own line,
+or after the email address.
+
+A canonical name may appear in more than one line, associated with
+different email addresses, but it doesn't make sense for a given address
+to appear more than once (if that happens, a later line overrides the
+earlier ones).
+
+So, for example, if your history contains commits by two authors, Jane
+and Joe, whose names appear in the repository under several forms:
+
+------------
+Joe Developer <joe@example.com>
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com>
+Jane Doe <jane@laptop.(none)>
+Jane D. <jane@desktop.(none)>
+------------
+
+Then, supposing Joe wants his middle name initial used, and Jane prefers
+her family name fully spelled out, a proper `.mailmap` file would look like:
 
 ------------
-# Keep alphabetized
-Adam Morrow <adam@localhost.localdomain>
-Eve Jones <eve@laptop.(none)>
+# Note how we don't need an entry for <jane@laptop.(none)>, because the
+# real name of that author is correct already, and coalesced directly.
+Jane Doe <jane@desktop.(none)>
+Joe R. Developer <joe@random.com>
 ------------
 
 Author