Re: [PATCH 1/2] git-format-patch: Include diff-generate-patch documentation

[Junio C Hamano <gitster@pobox.com>]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> diff-generate-patch explains format of generated patch for text files.

That is true, but that does not justify this change.  In other
words, the sentence does not explain why is it a good idea to
describe the itty bitty details of what is in the format-patch
output (which is more for the consumption of somebody other than the
user who is running the format-patch command).

> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/git-format-patch.txt | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index 3e49bf2210..247033f8fc 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch.
>  $ git format-patch -3
>  ------------
>  
> +GENERATED DIFF FORMAT
> +---------------------
> +git-format-patch emits diff in generated patches. For text files, the
> +diff format is described as below:
> +
> +include::diff-generate-patch.txt[]
> +

I suspect that, rather than adding a new section, it would be a
better change to extend what the first parapgraph of the Description
says.

The current text says something called "patch" is prepared one for
each commit, it is suitable for e-mail submission, and "am" is the
command to use it, but does not say what that "patch" really is.
The description in the page also refers to "three-dash" line, but
that is totally unclear unless the reader is given a more detailed
overview of what the "patch" the first paragraph refers to (and
diff-generate-patch.txt will not be the place to talk about it).

In other words, something like this one.

----- >8 ----- ----- >8 ----- ----- >8 ----- ----- >8 ----- ----- >8 -----
From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 24 Mar 2021 10:35:40 -0700
Subject: [PATCH] format-patch: give an overview of what a "patch" message is

The text says something called a "patch" is prepared one for each
commit, it is suitable for e-mail submission, and "am" is the
command to use it, but does not say what the "patch" really is.  The
description in the page also refers to "three-dash" line, but that
is totally unclear unless the reader is given a more detailed
overview of what the "patch" the first paragraph refers to.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-format-patch.txt | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 3e49bf2210..3db0e036d8 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -36,11 +36,28 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Prepare each commit with its patch in
-one file per commit, formatted to resemble UNIX mailbox format.
+Prepare each commit with its "patch" in
+one "message" per commit, formatted to resemble a UNIX mailbox.
 The output of this command is convenient for e-mail submission or
 for use with 'git am'.
 
+A "message" generated by the command consists of three parts:
+
+* A brief metadata header that begins with `From <commit>`
+  with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs
+  like "file(1)" to recognize that the file is an output from this
+  command, fields that record the author identity, the author date,
+  and the title of the change (taken from the first paragraph of the
+  commit log message).
+
+* The second and subsequent paragraphs of the commit log message.
+
+* The "patch", which is the "diff -p --stat" output (see
+  linkgit:git-diff[1]) between the commit and its parent.
+
+The log message and the patch is separated by a line with a
+three-dash line.
+
 There are two ways to specify which commits to operate on.
 
 1. A single commit, <since>, specifies that the commits leading
-- 
2.31.0-464-gadc53f61d7