[PATCH] Documentation: Use 'First Paragraph' instead of 'First Line'.
The discussion of email subject throughout the documentation is misleading; it indicates that the first line will become the subject. In fact, the first and second and third lines will become the subject, up until the first full blank line. Describing it as the first paragraph is more accurate. Signed-off-by: Jeremy White jwh...@codeweavers.com --- Documentation/git-commit.txt |2 +- Documentation/git-for-each-ref.txt |2 +- Documentation/git-format-patch.txt |8 +--- Documentation/git-shortlog.txt |2 +- Documentation/gitcore-tutorial.txt |2 +- Documentation/gittutorial.txt |2 +- Documentation/user-manual.txt |2 +- 7 files changed, 11 insertions(+), 9 deletions(-) diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index e99bb14..a61bca9 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -349,7 +349,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 7e83288..499c26a 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -100,7 +100,7 @@ Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. -The first line of the message in a commit and tag object is +The first paragraph of the message in a commit and tag object is `subject`, the remaining lines are `body`. The whole message is `contents`. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 9674f9d..e6f6d0e 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -57,10 +57,12 @@ 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 +By default, the subject of a single patch is [PATCH] First Paragraph 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`. +Paragraph. Note that First Paragraph consists of text in the commit message +prior to the first completely blank line (see the DISCUSSION section +in linkgit:git-commit[1]). 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 dfd4d0c..9464932 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. +the first paragraph of the commit message 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 f7815e9..92f97e6 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 paragraph 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 1c16066..a1bc56c 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -139,7 +139,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
[PATCH v2] Documentation: describe subject more precisely
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 jwh...@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
Re: [PATCH] Documentation: Use 'First Paragraph' instead of 'First Line'.
For that kind of casual wording, we have used title on this list for quite a long time, I think. So I'd rather see a change that just says title (if we are making such a change to the documentation, that is). This is not a very strong preference, though. Ah, I was unaware of the use of title, and I rather like it. v3 inbound making more use of title, and hopefully addressing your other points as well. Cheers, Jeremy -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3] Documentation: describe subject more precisely
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. This patch refines that, and makes more use of the concept of a commit title, with the title being all text up to the first blank line. Signed-off-by: Jeremy White jwh...@codeweavers.com --- Documentation/git-commit.txt |6 -- Documentation/git-for-each-ref.txt |7 --- Documentation/git-format-patch.txt | 11 +++ Documentation/git-shortlog.txt |3 +-- Documentation/gitcore-tutorial.txt |9 - Documentation/gittutorial.txt |8 +--- Documentation/user-manual.txt |9 ++--- 7 files changed, 31 insertions(+), 22 deletions(-) diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 4622297..9594ac8 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -389,8 +389,10 @@ 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 -on the Subject: line and the rest of the commit in the body. +The text up to the first blank line in a commit message is treated +as the commit title, and that title is used throughout git. +For example, linkgit:git-format-patch[1] turns a commit into email, and it uses +the title 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..afeb4cd 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] 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. +in release announcements. Each commit will be grouped by author and title. Additionally, [PATCH] will be stripped from the commit description. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 9d89336..5325c5a 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -956,12 +956,11 @@ $ 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 -top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk
