{"thread":{"id":"31527","subject":"[PATCH v2] Documentation: describe subject more precisely","startedAt":"2012-09-13T21:14:27Z","lastAt":"2012-09-13T21:36:54Z","messageCount":2,"participants":["Jeremy White","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"198968","messageId":"50524CB3.8090000@codeweavers.com","threadId":"31527","inReplyTo":null,"subject":"[PATCH v2] Documentation: describe subject more precisely","fromName":"Jeremy White","fromEmail":"jwhite@codeweavers.com","sentAt":"2012-09-13T21:14:27Z","receivedAt":"2012-09-13T21:14:27Z","isPatch":true,"sender":{"key":"jwhite@codeweavers.com","avatar":"https://avatars.githubusercontent.com/u/1063742?v=4"},"body":"The discussion of email subject throughout the documentation is\nmisleading; it indicates that the first line will always become\nthe subject.  In fact, the subject is generally all lines up until\nthe first full blank line.\n\nSigned-off-by: Jeremy White <jwhite@codeweavers.com>\n---\n Documentation/git-commit.txt       |    2 +-\n Documentation/git-for-each-ref.txt |    7 ++++---\n Documentation/git-format-patch.txt |   11 +++++++----\n Documentation/git-shortlog.txt     |    2 +-\n Documentation/gitcore-tutorial.txt |    2 +-\n Documentation/gittutorial.txt      |    2 +-\n Documentation/user-manual.txt      |    2 +-\n 7 files changed, 16 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 4622297..6b9ba20 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -389,7 +389,7 @@ DISCUSSION\n Though not required, it's a good idea to begin the commit message\n with a single short (less than 50 character) line summarizing the\n change, followed by a blank line and then a more thorough description.\n-Tools that turn commits into email, for example, use the first line\n+Tools that turn commits into email, for example, use the first paragraph\n on the Subject: line and the rest of the commit in the body.\n \n include::i18n.txt[]\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex c872b88..db55a4e 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`,\n and `date` to extract the named component.\n \n The complete message in a commit and tag object is `contents`.\n-Its first line is `contents:subject`, the remaining lines\n-are `contents:body` and the optional GPG signature\n-is `contents:signature`.\n+Its first line is `contents:subject`, where subject is the concatenation\n+of all lines of the commit message up to the first blank line.  The next\n+line is 'contents:body', where body is all of the lines after the first\n+blank line.  Finally, the optional GPG signature is `contents:signature`.\n \n For sorting purposes, fields with numeric values sort in numeric\n order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 04c7346..6d43f56 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified.\n If `-o` is specified, output files are created in <dir>.  Otherwise\n they are created in the current working directory.\n \n-By default, the subject of a single patch is \"[PATCH] First Line\" and\n-the subject when multiple patches are output is \"[PATCH n/m] First\n-Line\". To force 1/1 to be added for a single patch, use `-n`.  To omit\n-patch numbers from the subject, use `-N`.\n+By default, the subject of a single patch is \"[PATCH] \" followed by\n+the concatenation of lines from the commit message up to the first blank\n+line (see the DISCUSSION section of linkgit:git-commit[1]).\n+\n+When multiple patches are output, the subject prefix will instead be\n+\"[PATCH n/m] \".  To force 1/1 to be added for a single patch, use `-n`.\n+To omit patch numbers from the subject, use `-N`.\n \n If given `--thread`, `git-format-patch` will generate `In-Reply-To` and\n `References` headers to make the second and subsequent patch mails appear\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex 01d8417..6ec30e3 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -15,7 +15,7 @@ DESCRIPTION\n -----------\n Summarizes 'git log' output in a format suitable for inclusion\n in release announcements. Each commit will be grouped by author and\n-the first line of the commit message will be shown.\n+all text from the commit message up to the first blank line will be shown.\n \n Additionally, \"[PATCH]\" will be stripped from the commit description.\n \ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex 9d89336..b5b3534 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 master mybranch\n ------------------------------------------------\n \n The first two lines indicate that it is showing the two branches\n-and the first line of the commit log message from their\n+and the first part of the commit log message from their\n top-of-the-tree commits, you are currently on `master` branch\n (notice the asterisk `*` character), and the first column for\n the later output lines is used to show commits contained in the\ndiff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt\nindex dee0505..76aba59 100644\n--- a/Documentation/gittutorial.txt\n+++ b/Documentation/gittutorial.txt\n@@ -140,7 +140,7 @@ A note on commit messages: Though not required, it's a good idea to\n begin the commit message with a single short (less than 50 character)\n line summarizing the change, followed by a blank line and then a more\n thorough description.  Tools that turn commits into email, for\n-example, use the first line on the Subject: line and the rest of the\n+example, use the first paragraph on the Subject: line and the rest of the\n commit in the body.\n \n Git tracks content not files\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 03d95dc..65701e8 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1137,7 +1137,7 @@ Though not required, it's a good idea to begin the commit message\n with a single short (less than 50 character) line summarizing the\n change, followed by a blank line and then a more thorough\n description.  Tools that turn commits into email, for example, use\n-the first line on the Subject line and the rest of the commit in the\n+the first paragraph on the Subject line and the rest of the commit in the\n body.\n \n [[ignoring-files]]\n-- \n1.7.10.4\n"},{"id":"198978","messageId":"7vipbh61vt.fsf@alter.siamese.dyndns.org","threadId":"31527","inReplyTo":"50524CB3.8090000@codeweavers.com","subject":"Re: [PATCH v2] Documentation: describe subject more precisely","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-13T21:36:54Z","receivedAt":"2012-09-13T21:36:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeremy White <jwhite@codeweavers.com> writes:\n\n> The discussion of email subject throughout the documentation is\n> misleading; it indicates that the first line will always become\n> the subject.  In fact, the subject is generally all lines up until\n> the first full blank line.\n>\n> Signed-off-by: Jeremy White <jwhite@codeweavers.com>\n> ---\n>  Documentation/git-commit.txt       |    2 +-\n>  Documentation/git-for-each-ref.txt |    7 ++++---\n>  Documentation/git-format-patch.txt |   11 +++++++----\n>  Documentation/git-shortlog.txt     |    2 +-\n>  Documentation/gitcore-tutorial.txt |    2 +-\n>  Documentation/gittutorial.txt      |    2 +-\n>  Documentation/user-manual.txt      |    2 +-\n>  7 files changed, 16 insertions(+), 12 deletions(-)\n>\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 4622297..6b9ba20 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -389,7 +389,7 @@ DISCUSSION\n>  Though not required, it's a good idea to begin the commit message\n>  with a single short (less than 50 character) line summarizing the\n>  change, followed by a blank line and then a more thorough description.\n> -Tools that turn commits into email, for example, use the first line\n> +Tools that turn commits into email, for example, use the first paragraph\n>  on the Subject: line and the rest of the commit in the body.\n\nGood, but as somebody else pointed out and you did in the patch for\nfor-each-ref, the definition of \"paragraph\" may want to be clarified\nhere.\n\n>  include::i18n.txt[]\n> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\n> index c872b88..db55a4e 100644\n> --- a/Documentation/git-for-each-ref.txt\n> +++ b/Documentation/git-for-each-ref.txt\n> @@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`,\n>  and `date` to extract the named component.\n>  \n>  The complete message in a commit and tag object is `contents`.\n> -Its first line is `contents:subject`, the remaining lines\n> -are `contents:body` and the optional GPG signature\n> -is `contents:signature`.\n> +Its first line is `contents:subject`, where subject is the concatenation\n> +of all lines of the commit message up to the first blank line.  The next\n> +line is 'contents:body', where body is all of the lines after the first\n> +blank line.  Finally, the optional GPG signature is `contents:signature`.\n\nVery good.\n\n> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\n> index 04c7346..6d43f56 100644\n> --- a/Documentation/git-format-patch.txt\n> +++ b/Documentation/git-format-patch.txt\n> @@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified.\n>  If `-o` is specified, output files are created in <dir>.  Otherwise\n>  they are created in the current working directory.\n>  \n> -By default, the subject of a single patch is \"[PATCH] First Line\" and\n> -the subject when multiple patches are output is \"[PATCH n/m] First\n> -Line\". To force 1/1 to be added for a single patch, use `-n`.  To omit\n> -patch numbers from the subject, use `-N`.\n> +By default, the subject of a single patch is \"[PATCH] \" followed by\n> +the concatenation of lines from the commit message up to the first blank\n> +line (see the DISCUSSION section of linkgit:git-commit[1]).\n> +\n> +When multiple patches are output, the subject prefix will instead be\n> +\"[PATCH n/m] \".  To force 1/1 to be added for a single patch, use `-n`.\n> +To omit patch numbers from the subject, use `-N`.\n\nGood.\n\n> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\n> index 01d8417..6ec30e3 100644\n> --- a/Documentation/git-shortlog.txt\n> +++ b/Documentation/git-shortlog.txt\n> @@ -15,7 +15,7 @@ DESCRIPTION\n>  -----------\n>  Summarizes 'git log' output in a format suitable for inclusion\n>  in release announcements. Each commit will be grouped by author and\n> -the first line of the commit message will be shown.\n> +all text from the commit message up to the first blank line will be shown.\n\nOK, but I think \"title\" would be better for casual discussion like this.\n\n> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\n> index 9d89336..b5b3534 100644\n> --- a/Documentation/gitcore-tutorial.txt\n> +++ b/Documentation/gitcore-tutorial.txt\n> @@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 master mybranch\n>  ------------------------------------------------\n>  \n>  The first two lines indicate that it is showing the two branches\n> -and the first line of the commit log message from their\n> +and the first part of the commit log message from their\n>  top-of-the-tree commits, you are currently on `master` branch\n>  (notice the asterisk `*` character), and the first column for\n>  the later output lines is used to show commits contained in the\n\nLikewise.\n\n> diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt\n> index dee0505..76aba59 100644\n> --- a/Documentation/gittutorial.txt\n> +++ b/Documentation/gittutorial.txt\n> @@ -140,7 +140,7 @@ A note on commit messages: Though not required, it's a good idea to\n>  begin the commit message with a single short (less than 50 character)\n>  line summarizing the change, followed by a blank line and then a more\n>  thorough description.  Tools that turn commits into email, for\n> -example, use the first line on the Subject: line and the rest of the\n> +example, use the first paragraph on the Subject: line and the rest of the\n>  commit in the body.\n\nSame for the patch to git-commit.txt\n\n>  Git tracks content not files\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index 03d95dc..65701e8 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -1137,7 +1137,7 @@ Though not required, it's a good idea to begin the commit message\n>  with a single short (less than 50 character) line summarizing the\n>  change, followed by a blank line and then a more thorough\n>  description.  Tools that turn commits into email, for example, use\n> -the first line on the Subject line and the rest of the commit in the\n> +the first paragraph on the Subject line and the rest of the commit in the\n>  body.\n\nSame for the patch to git-commit.txt\n"}]}