[PATCH v2] Documentation: describe subject more precisely

[PATCH v2] Documentation: describe subject more precisely

[Jeremy White]

The discussion of email subject throughout the documentation is
misleading; it indicates that the first line will always become
the subject.  In fact, the subject is generally all lines up until
the first full blank line.

Signed-off-by: Jeremy White <jwhite@codeweavers.com>
---
 Documentation/git-commit.txt       |    2 +-
 Documentation/git-for-each-ref.txt |    7 ++++---
 Documentation/git-format-patch.txt |   11 +++++++----
 Documentation/git-shortlog.txt     |    2 +-
 Documentation/gitcore-tutorial.txt |    2 +-
 Documentation/gittutorial.txt      |    2 +-
 Documentation/user-manual.txt      |    2 +-
 7 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 4622297..6b9ba20 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -389,7 +389,7 @@ DISCUSSION
 Though not required, it's a good idea to begin the commit message
 with a single short (less than 50 character) line summarizing the
 change, followed by a blank line and then a more thorough description.
-Tools that turn commits into email, for example, use the first line
+Tools that turn commits into email, for example, use the first paragraph
 on the Subject: line and the rest of the commit in the body.
 
 include::i18n.txt[]
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index c872b88..db55a4e 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`,
 and `date` to extract the named component.
 
 The complete message in a commit and tag object is `contents`.
-Its first line is `contents:subject`, the remaining lines
-are `contents:body` and the optional GPG signature
-is `contents:signature`.
+Its first line is `contents:subject`, where subject is the concatenation
+of all lines of the commit message up to the first blank line.  The next
+line is 'contents:body', where body is all of the lines after the first
+blank line.  Finally, the optional GPG signature is `contents:signature`.
 
 For sorting purposes, fields with numeric values sort in numeric
 order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 04c7346..6d43f56 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified.
 If `-o` is specified, output files are created in <dir>.  Otherwise
 they are created in the current working directory.
 
-By default, the subject of a single patch is "[PATCH] First Line" and
-the subject when multiple patches are output is "[PATCH n/m] First
-Line". To force 1/1 to be added for a single patch, use `-n`.  To omit
-patch numbers from the subject, use `-N`.
+By default, the subject of a single patch is "[PATCH] " followed by
+the concatenation of lines from the commit message up to the first blank
+line (see the DISCUSSION section of linkgit:git-commit[1]).
+
+When multiple patches are output, the subject prefix will instead be
+"[PATCH n/m] ".  To force 1/1 to be added for a single patch, use `-n`.
+To omit patch numbers from the subject, use `-N`.
 
 If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
 `References` headers to make the second and subsequent patch mails appear
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index 01d8417..6ec30e3 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -15,7 +15,7 @@ DESCRIPTION
 -----------
 Summarizes 'git log' output in a format suitable for inclusion
 in release announcements. Each commit will be grouped by author and
-the first line of the commit message will be shown.
+all text from the commit message up to the first blank line will be shown.
 
 Additionally, "[PATCH]" will be stripped from the commit description.
 
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index 9d89336..b5b3534 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 master mybranch
 ------------------------------------------------
 
 The first two lines indicate that it is showing the two branches
-and the first line of the commit log message from their
+and the first part of the commit log message from their
 top-of-the-tree commits, you are currently on `master` branch
 (notice the asterisk `*` character), and the first column for
 the later output lines is used to show commits contained in the
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index dee0505..76aba59 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -140,7 +140,7 @@ A note on commit messages: Though not required, it's a good idea to
 begin the commit message with a single short (less than 50 character)
 line summarizing the change, followed by a blank line and then a more
 thorough description.  Tools that turn commits into email, for
-example, use the first line on the Subject: line and the rest of the
+example, use the first paragraph on the Subject: line and the rest of the
 commit in the body.
 
 Git tracks content not files
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 03d95dc..65701e8 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1137,7 +1137,7 @@ Though not required, it's a good idea to begin the commit message
 with a single short (less than 50 character) line summarizing the
 change, followed by a blank line and then a more thorough
 description.  Tools that turn commits into email, for example, use
-the first line on the Subject line and the rest of the commit in the
+the first paragraph on the Subject line and the rest of the commit in the
 body.
 
 [[ignoring-files]]
-- 
1.7.10.4

Re: [PATCH v2] Documentation: describe subject more precisely

[Junio C Hamano]

Jeremy White <jwhite@codeweavers.com> writes:

> The discussion of email subject throughout the documentation is
> misleading; it indicates that the first line will always become
> the subject.  In fact, the subject is generally all lines up until
> the first full blank line.
>
> Signed-off-by: Jeremy White <jwhite@codeweavers.com>
> ---
>  Documentation/git-commit.txt       |    2 +-
>  Documentation/git-for-each-ref.txt |    7 ++++---
>  Documentation/git-format-patch.txt |   11 +++++++----
>  Documentation/git-shortlog.txt     |    2 +-
>  Documentation/gitcore-tutorial.txt |    2 +-
>  Documentation/gittutorial.txt      |    2 +-
>  Documentation/user-manual.txt      |    2 +-
>  7 files changed, 16 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 4622297..6b9ba20 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -389,7 +389,7 @@ DISCUSSION
>  Though not required, it's a good idea to begin the commit message
>  with a single short (less than 50 character) line summarizing the
>  change, followed by a blank line and then a more thorough description.
> -Tools that turn commits into email, for example, use the first line
> +Tools that turn commits into email, for example, use the first paragraph
>  on the Subject: line and the rest of the commit in the body.

Good, but as somebody else pointed out and you did in the patch for
for-each-ref, the definition of "paragraph" may want to be clarified
here.

>  include::i18n.txt[]
> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index c872b88..db55a4e 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`,
>  and `date` to extract the named component.
>  
>  The complete message in a commit and tag object is `contents`.
> -Its first line is `contents:subject`, the remaining lines
> -are `contents:body` and the optional GPG signature
> -is `contents:signature`.
> +Its first line is `contents:subject`, where subject is the concatenation
> +of all lines of the commit message up to the first blank line.  The next
> +line is 'contents:body', where body is all of the lines after the first
> +blank line.  Finally, the optional GPG signature is `contents:signature`.

Very good.

> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index 04c7346..6d43f56 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified.
>  If `-o` is specified, output files are created in <dir>.  Otherwise
>  they are created in the current working directory.
>  
> -By default, the subject of a single patch is "[PATCH] First Line" and
> -the subject when multiple patches are output is "[PATCH n/m] First
> -Line". To force 1/1 to be added for a single patch, use `-n`.  To omit
> -patch numbers from the subject, use `-N`.
> +By default, the subject of a single patch is "[PATCH] " followed by
> +the concatenation of lines from the commit message up to the first blank
> +line (see the DISCUSSION section of linkgit:git-commit[1]).
> +
> +When multiple patches are output, the subject prefix will instead be
> +"[PATCH n/m] ".  To force 1/1 to be added for a single patch, use `-n`.
> +To omit patch numbers from the subject, use `-N`.

Good.

> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
> index 01d8417..6ec30e3 100644
> --- a/Documentation/git-shortlog.txt
> +++ b/Documentation/git-shortlog.txt
> @@ -15,7 +15,7 @@ DESCRIPTION
>  -----------
>  Summarizes 'git log' output in a format suitable for inclusion
>  in release announcements. Each commit will be grouped by author and
> -the first line of the commit message will be shown.
> +all text from the commit message up to the first blank line will be shown.

OK, but I think "title" would be better for casual discussion like this.

> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
> index 9d89336..b5b3534 100644
> --- a/Documentation/gitcore-tutorial.txt
> +++ b/Documentation/gitcore-tutorial.txt
> @@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 master mybranch
>  ------------------------------------------------
>  
>  The first two lines indicate that it is showing the two branches
> -and the first line of the commit log message from their
> +and the first part of the commit log message from their
>  top-of-the-tree commits, you are currently on `master` branch
>  (notice the asterisk `*` character), and the first column for
>  the later output lines is used to show commits contained in the

Likewise.

> diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
> index dee0505..76aba59 100644
> --- a/Documentation/gittutorial.txt
> +++ b/Documentation/gittutorial.txt
> @@ -140,7 +140,7 @@ A note on commit messages: Though not required, it's a good idea to
>  begin the commit message with a single short (less than 50 character)
>  line summarizing the change, followed by a blank line and then a more
>  thorough description.  Tools that turn commits into email, for
> -example, use the first line on the Subject: line and the rest of the
> +example, use the first paragraph on the Subject: line and the rest of the
>  commit in the body.

Same for the patch to git-commit.txt

>  Git tracks content not files
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 03d95dc..65701e8 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1137,7 +1137,7 @@ Though not required, it's a good idea to begin the commit message
>  with a single short (less than 50 character) line summarizing the
>  change, followed by a blank line and then a more thorough
>  description.  Tools that turn commits into email, for example, use
> -the first line on the Subject line and the rest of the commit in the
> +the first paragraph on the Subject line and the rest of the commit in the
>  body.

Same for the patch to git-commit.txt