Bagas Sanjaya <bagasdotme@xxxxxxxxx> 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@xxxxxxxxx> > --- > 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@xxxxxxxxx> 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@xxxxxxxxx> --- 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
