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 the "three-dash" line,
but it is unclear what it is, unless the reader is given a more
detailed overview of what the "patch" is.

Add a brief paragraph to give an overview of what the output looks
like.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Junio C Hamano 2021-03-24 10:35:40 -07:00
parent a5828ae6b5
commit 28e29ee38b

View file

@ -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