Jeremy White <jwhite@xxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxx> > --- > 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html