Documentation: describe subject more precisely
PATCH v2 1/1 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 <[email protected]>
--- 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(-)
Documentation/git-commit.txt +1 -1
@@ -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[]
Documentation/git-for-each-ref.txt +4 -3
@@ -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`).
Documentation/git-format-patch.txt +7 -4
@@ -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
Documentation/git-shortlog.txt +1 -1
@@ -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.
Documentation/gitcore-tutorial.txt +1 -1
@@ -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
Documentation/gittutorial.txt +1 -1
@@ -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
Documentation/user-manual.txt +1 -1
@@ -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]]
Signature · 1 line
1.7.10.4
Quoted 21 lines · 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 <[email protected]>--- 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(-)Documentation/git-commit.txt +0
-0
Documentation/git-commit.txt DISCUSSION · line 393
Quoted 6 lines
Documentation/git-commit.txt +1
-1@@ -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.
Quoted 6 lines
Documentation/git-commit.txt +0
-0include::i18n.txt[]Documentation/git-for-each-ref.txt +0
-0
Documentation/git-for-each-ref.txt Fields that have name-email-date tuple as its value (`author`, · line 108
Quoted 10 lines
Documentation/git-for-each-ref.txt +4
-3@@ -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.
Quoted 9 lines
Documentation/git-format-patch.txt +0
-1@@ -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
Documentation/git-format-patch.txt output, unless the `--stdout` option is specified. · line 67
Quoted 10 lines
Documentation/git-format-patch.txt +7
-3-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.
Documentation/git-shortlog.txt DESCRIPTION · line 18
Quoted 10 lines
Documentation/git-shortlog.txt +1
-1@@ -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.
Documentation/gitcore-tutorial.txt $ git show-branch --topo-order --more=1 master mybranch · line 962
Quoted 13 lines
Documentation/gitcore-tutorial.txt +1
-1@@ -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.
Documentation/gittutorial.txt A note on commit messages: Though not required, it's a good idea to · line 144
Quoted 11 lines
Documentation/gittutorial.txt +1
-1@@ -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
Documentation/user-manual.txt Though not required, it's a good idea to begin the commit message · line 1141
Quoted 12 lines
Documentation/gittutorial.txt +0
-0Git tracks content not filesDocumentation/user-manual.txt +1
-1@@ -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