Skip to content

Commit 52ffe99

Browse files
jwhite66gitster
jwhite66
authored and
gitster
committed
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 <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent e70d163 commit 52ffe99

7 files changed

Lines changed: 31 additions & 22 deletions

File tree

‎Documentation/git-commit.txt‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -389,8 +389,10 @@ DISCUSSION
389389
Though not required, it's a good idea to begin the commit message
390390
with a single short (less than 50 character) line summarizing the
391391
change, followed by a blank line and then a more thorough description.
392-
Tools that turn commits into email, for example, use the first line
393-
on the Subject: line and the rest of the commit in the body.
392+
The text up to the first blank line in a commit message is treated
393+
as the commit title, and that title is used throughout git.
394+
For example, linkgit:git-format-patch[1] turns a commit into email, and it uses
395+
the title on the Subject line and the rest of the commit in the body.
394396

395397
include::i18n.txt[]
396398

‎Documentation/git-for-each-ref.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`,
102102
and `date` to extract the named component.
103103

104104
The complete message in a commit and tag object is `contents`.
105-
Its first line is `contents:subject`, the remaining lines
106-
are `contents:body` and the optional GPG signature
107-
is `contents:signature`.
105+
Its first line is `contents:subject`, where subject is the concatenation
106+
of all lines of the commit message up to the first blank line. The next
107+
line is 'contents:body', where body is all of the lines after the first
108+
blank line. Finally, the optional GPG signature is `contents:signature`.
108109

109110
For sorting purposes, fields with numeric values sort in numeric
110111
order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).

‎Documentation/git-format-patch.txt‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified.
5858
If `-o` is specified, output files are created in <dir>. Otherwise
5959
they are created in the current working directory.
6060

61-
By default, the subject of a single patch is "[PATCH] First Line" and
62-
the subject when multiple patches are output is "[PATCH n/m] First
63-
Line". To force 1/1 to be added for a single patch, use `-n`. To omit
64-
patch numbers from the subject, use `-N`.
61+
By default, the subject of a single patch is "[PATCH] " followed by
62+
the concatenation of lines from the commit message up to the first blank
63+
line (see the DISCUSSION section of linkgit:git-commit[1]).
64+
65+
When multiple patches are output, the subject prefix will instead be
66+
"[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`.
67+
To omit patch numbers from the subject, use `-N`.
6568

6669
If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
6770
`References` headers to make the second and subsequent patch mails appear

‎Documentation/git-shortlog.txt‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
1414
DESCRIPTION
1515
-----------
1616
Summarizes 'git log' output in a format suitable for inclusion
17-
in release announcements. Each commit will be grouped by author and
18-
the first line of the commit message will be shown.
17+
in release announcements. Each commit will be grouped by author and title.
1918

2019
Additionally, "[PATCH]" will be stripped from the commit description.
2120

‎Documentation/gitcore-tutorial.txt‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -956,12 +956,11 @@ $ git show-branch --topo-order --more=1 master mybranch
956956
------------------------------------------------
957957

958958
The first two lines indicate that it is showing the two branches
959-
and the first line of the commit log message from their
960-
top-of-the-tree commits, you are currently on `master` branch
961-
(notice the asterisk `*` character), and the first column for
962-
the later output lines is used to show commits contained in the
959+
with the titles of their top-of-the-tree commits, you are currently on
960+
`master` branch (notice the asterisk `*` character), and the first
961+
column for the later output lines is used to show commits contained in the
963962
`master` branch, and the second column for the `mybranch`
964-
branch. Three commits are shown along with their log messages.
963+
branch. Three commits are shown along with their titles.
965964
All of them have non blank characters in the first column (`*`
966965
shows an ordinary commit on the current branch, `-` is a merge commit), which
967966
means they are now part of the `master` branch. Only the "Some

‎Documentation/gittutorial.txt‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,9 +139,11 @@ them to the index, and commit, all in one step.
139139
A note on commit messages: Though not required, it's a good idea to
140140
begin the commit message with a single short (less than 50 character)
141141
line summarizing the change, followed by a blank line and then a more
142-
thorough description. Tools that turn commits into email, for
143-
example, use the first line on the Subject: line and the rest of the
144-
commit in the body.
142+
thorough description. The text up to the first blank line in a commit
143+
message is treated as the commit title, and that title is used
144+
throughout git. For example, linkgit:git-format-patch[1] turns a
145+
commit into email, and it uses the title on the Subject line and the
146+
rest of the commit in the body.
145147

146148
Git tracks content not files
147149
----------------------------

‎Documentation/user-manual.txt‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1136,9 +1136,12 @@ Creating good commit messages
11361136
Though not required, it's a good idea to begin the commit message
11371137
with a single short (less than 50 character) line summarizing the
11381138
change, followed by a blank line and then a more thorough
1139-
description. Tools that turn commits into email, for example, use
1140-
the first line on the Subject line and the rest of the commit in the
1141-
body.
1139+
description. The text up to the first blank line in a commit
1140+
message is treated as the commit title, and that title is used
1141+
throughout git. For example, linkgit:git-format-patch[1] turns a
1142+
commit into email, and it uses the title on the Subject line and the
1143+
rest of the commit in the body.
1144+
11421145

11431146
[[ignoring-files]]
11441147
Ignoring files

0 commit comments

Comments
 (0)