Documentation: Use 'First Paragraph' instead of 'First Line'.
PATCH 1/1 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.
--- 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(-)
Documentation/git-commit.txt +1 -1
@@ -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[]
Documentation/git-for-each-ref.txt +1 -1
@@ -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`.
Documentation/git-format-patch.txt +5 -3
@@ -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
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. +the first paragraph of the commit message 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 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
Documentation/gittutorial.txt +1 -1
@@ -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 in the body. Git tracks content not files
Documentation/user-manual.txt +1 -1
@@ -1126,7 +1126,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.9.5
Quoted 22 lines · Jeremy White
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 <[email protected]>--- 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(-)Documentation/git-commit.txt +0
-0
Documentation/git-commit.txt DISCUSSION · line 353
Quoted 6 lines
Documentation/git-commit.txt +1
-1@@ -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.
This is a good change, as the previous sentence says the norm for the first paragraph is a single line.
Documentation/git-for-each-ref.txt Fields that have name-email-date tuple as its value (`author`, · line 105
Quoted 12 lines
Documentation/git-for-each-ref.txt +1
-1@@ -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`.
This may need a bit more explanation. Just saying "First Paragraph" without saying that for all commits in a sane project it is the same as "First Line" will make the reader wonder "What happens to the second and subsequent lines?" (the answer is that the first paragraph is made into a single looooooong line).
Quoted 5 lines
Documentation/git-format-patch.txt +0
-0
Documentation/git-format-patch.txt output, unless the `--stdout` option is specified. · line 65
Quoted 10 lines
Documentation/git-format-patch.txt +5
-1@@ -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 +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`.
Ditto.
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. +the first paragraph of the commit message will be shown.
Ditto.
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 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
Ditto.
Documentation/gittutorial.txt A note on commit messages: Though not required, it's a good idea to · line 143
Quoted 11 lines
Documentation/gittutorial.txt +1
-1@@ -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 in the body.
This is a good change, as it is clear that you are expected to write a single line in the first paragraph in the previous sentence.
Documentation/user-manual.txt Though not required, it's a good idea to begin the commit message · line 1130
Quoted 11 lines
Documentation/user-manual.txt +1
-1@@ -1126,7 +1126,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.
Ditto.
Thanks for the feedback; new patch inbound. Minor nits:
Quoted 7 lines
Quoted 7 lines
Documentation/gitcore-tutorial.txt +0
-0@@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 master mybranch ------------------------------------------------
Quoted 8 lines
Documentation/gitcore-tutorial.txt $ git show-branch --topo-order --more=1 master mybranch · line 962
Quoted 6 lines
Documentation/gitcore-tutorial.txt +1
-1The 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 theDitto.
I did not substantially alter this. The emphasis of this section is on the broader show-branch output, and belaboring the subject would be distracting and unnecessary imho.
Cheers,
Jeremy
Quoted 18 lines · Jeremy White
Thanks for the feedback; new patch inbound. Minor nits:
Quoted 7 lines
Quoted 7 lines
Documentation/gitcore-tutorial.txt +0
-0@@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 master mybranch ------------------------------------------------Quoted 8 lines
Documentation/gitcore-tutorial.txt $ git show-branch --topo-order --more=1 master mybranch · line 962
Quoted 6 lines
Documentation/gitcore-tutorial.txt +1
-1The 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 theDitto.
Quoted 3 lines
I did not substantially alter this. The emphasis of this section is on the broader show-branch output, and belaboring the subject would be distracting and unnecessary imho.
Yeah, but if that is the focus of this part of the documentation, wouldn't a patch to update "the first line" with something more generic like "title of the commit" be more appropriate?
Quoted 7 lines
Quoted 3 lines
I did not substantially alter this. The emphasis of this section is on the broader show-branch output, and belaboring the subject would be distracting and unnecessary imho.
Yeah, but if that is the focus of this part of the documentation, wouldn't a patch to update "the first line" with something more generic like "title of the commit" be more appropriate?
See my patch; I went with 'first part'. That, I think, does not mislead (the goal of my change), but also does not distract from the main point of the section (detailing the various bits of git show-branch).
Cheers,
Jeremy
Quoted 4 lines · Jeremy White
Quoted 4 lines
Quoted 3 lines
I did not substantially alter this. The emphasis of this section is on the broader show-branch output, and belaboring the subject would be distracting and unnecessary imho.
Quoted 8 lines
Quoted 3 lines
Yeah, but if that is the focus of this part of the documentation, wouldn't a patch to update "the first line" with something more generic like "title of the commit" be more appropriate?
See my patch; I went with 'first part'. That, I think, does not mislead (the goal of my change), but also does not distract from the main point of the section (detailing the various bits of git show-branch).
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.
Quoted 5 lines
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
From: "Jeremy White" <[email protected]>
Sent: Thursday, September 13, 2012 1:42 PM
Quoted 4 lines
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
This "up until the first full blank line" part should also be in the documentation itself to clarify how a 'paragraph' is delineated. I've shown one place it could go below.
Quoted 23 lines
is more accurate.
Signed-off-by Jeremy White <[email protected]>---
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(-)Documentation/git-commit.txt +0
-0@@ -349,7 +349,7 @@ DISCUSSIONThough 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.
Documentation/git-commit.txt +1
-1-Tools that turn commits into email, for example, use the first line +Tools that turn commits into email, for example, use the first
Quoted 2 lines
paragraph
on the Subject: line
"up until the first full blank line"
Quoted 113 lines
and the rest of the commit in the body.
include::i18n.txt[]
Documentation/git-for-each-ref.txt +0
-0@@ -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
dateto extract the named component.Documentation/git-for-each-ref.txt +1
-1-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 arebody. The whole message iscontents.Documentation/git-format-patch.txt +0
-0@@ -57,10 +57,12 @@ output, unless the `--stdout` option is specified.If
-ois specified, output files are created in <dir>. Otherwise they are created in the current working directory.Documentation/git-format-patch.txt +1
-1-By default, the subject of a single patch is "[PATCH] First Line" and +By default, the subject of a single patch is "[PATCH] FirstParagraph" 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 omitDocumentation/git-format-patch.txt +1
-1-patch numbers from the subject, use `-N`. +Paragraph". Note that "First Paragraph" consists of text in thecommit message
Documentation/git-format-patch.txt +2
-0+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 singlepatch,
+use-n. To omit patch numbers from the subject, use-N.If given
--thread,git-format-patchwill generateIn-Reply-ToandReferencesheaders to make the second and subsequent patch mails appearDocumentation/git-shortlog.txt +0
-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
Documentation/git-shortlog.txt +1
-1-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.
Documentation/gitcore-tutorial.txt +0
-0@@ -956,7 +956,7 @@ $ git show-branch --topo-order --more=1 mastermybranch
------------------------------------------------The first two lines indicate that it is showing the two branches
Documentation/gitcore-tutorial.txt +1
-1-and the first line of the commit log message from their +and the first paragraph of the commit log message from theirtop-of-the-tree commits, you are currently on
masterbranch (notice the asterisk\*character), and the first column for the later output lines is used to show commits contained in theDocumentation/gittutorial.txt +0
-0@@ -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, forDocumentation/gittutorial.txt +1
-1-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 ofthe
commit in the body.Git tracks content not files
Documentation/user-manual.txt +0
-0@@ -1126,7 +1126,7 @@ Though not required, it's a good idea to beginthe 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, useDocumentation/user-manual.txt +1
-1-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 inthe
body.[[ignoring-files]]
Signature · 13 lines
1.7.9.5 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html ----- No virus found in this message. Checked by AVG - www.avg.com Version: 2012.0.2221 / Virus Database: 2437/5266 - Release Date: 09/13/12