mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
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 <jwhite@codeweavers.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
e70d1632bd
commit
52ffe995b9
|
@ -389,8 +389,10 @@ DISCUSSION
|
||||||
Though not required, it's a good idea to begin the commit message
|
Though not required, it's a good idea to begin the commit message
|
||||||
with a single short (less than 50 character) line summarizing the
|
with a single short (less than 50 character) line summarizing the
|
||||||
change, followed by a blank line and then a more thorough description.
|
change, followed by a blank line and then a more thorough description.
|
||||||
Tools that turn commits into email, for example, use the first line
|
The text up to the first blank line in a commit message is treated
|
||||||
on the Subject: line and the rest of the commit in the body.
|
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[]
|
include::i18n.txt[]
|
||||||
|
|
||||||
|
|
|
@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`,
|
||||||
and `date` to extract the named component.
|
and `date` to extract the named component.
|
||||||
|
|
||||||
The complete message in a commit and tag object is `contents`.
|
The complete message in a commit and tag object is `contents`.
|
||||||
Its first line is `contents:subject`, the remaining lines
|
Its first line is `contents:subject`, where subject is the concatenation
|
||||||
are `contents:body` and the optional GPG signature
|
of all lines of the commit message up to the first blank line. The next
|
||||||
is `contents:signature`.
|
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
|
For sorting purposes, fields with numeric values sort in numeric
|
||||||
order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
|
order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
|
||||||
|
|
|
@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified.
|
||||||
If `-o` is specified, output files are created in <dir>. Otherwise
|
If `-o` is specified, output files are created in <dir>. Otherwise
|
||||||
they are created in the current working directory.
|
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] " followed by
|
||||||
the subject when multiple patches are output is "[PATCH n/m] First
|
the concatenation of lines from the commit message up to the first blank
|
||||||
Line". To force 1/1 to be added for a single patch, use `-n`. To omit
|
line (see the DISCUSSION section of linkgit:git-commit[1]).
|
||||||
patch numbers from the subject, use `-N`.
|
|
||||||
|
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
|
If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
|
||||||
`References` headers to make the second and subsequent patch mails appear
|
`References` headers to make the second and subsequent patch mails appear
|
||||||
|
|
|
@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
|
||||||
DESCRIPTION
|
DESCRIPTION
|
||||||
-----------
|
-----------
|
||||||
Summarizes 'git log' output in a format suitable for inclusion
|
Summarizes 'git log' output in a format suitable for inclusion
|
||||||
in release announcements. Each commit will be grouped by author and
|
in release announcements. Each commit will be grouped by author and title.
|
||||||
the first line of the commit message will be shown.
|
|
||||||
|
|
||||||
Additionally, "[PATCH]" will be stripped from the commit description.
|
Additionally, "[PATCH]" will be stripped from the commit description.
|
||||||
|
|
||||||
|
|
|
@ -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
|
The first two lines indicate that it is showing the two branches
|
||||||
and the first line of the commit log message from their
|
with the titles of their top-of-the-tree commits, you are currently on
|
||||||
top-of-the-tree commits, you are currently on `master` branch
|
`master` branch (notice the asterisk `*` character), and the first
|
||||||
(notice the asterisk `*` character), and the first column for
|
column for the later output lines is used to show commits contained in the
|
||||||
the later output lines is used to show commits contained in the
|
|
||||||
`master` branch, and the second column for the `mybranch`
|
`master` branch, and the second column for the `mybranch`
|
||||||
branch. Three commits are shown along with their log messages.
|
branch. Three commits are shown along with their titles.
|
||||||
All of them have non blank characters in the first column (`*`
|
All of them have non blank characters in the first column (`*`
|
||||||
shows an ordinary commit on the current branch, `-` is a merge commit), which
|
shows an ordinary commit on the current branch, `-` is a merge commit), which
|
||||||
means they are now part of the `master` branch. Only the "Some
|
means they are now part of the `master` branch. Only the "Some
|
||||||
|
|
|
@ -139,9 +139,11 @@ them to the index, and commit, all in one step.
|
||||||
A note on commit messages: Though not required, it's a good idea to
|
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)
|
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
|
line summarizing the change, followed by a blank line and then a more
|
||||||
thorough description. Tools that turn commits into email, for
|
thorough description. The text up to the first blank line in a commit
|
||||||
example, use the first line on the Subject: line and the rest of the
|
message is treated as the commit title, and that title is used
|
||||||
commit in the body.
|
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.
|
||||||
|
|
||||||
Git tracks content not files
|
Git tracks content not files
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
|
@ -1136,9 +1136,12 @@ Creating good commit messages
|
||||||
Though not required, it's a good idea to begin the commit message
|
Though not required, it's a good idea to begin the commit message
|
||||||
with a single short (less than 50 character) line summarizing the
|
with a single short (less than 50 character) line summarizing the
|
||||||
change, followed by a blank line and then a more thorough
|
change, followed by a blank line and then a more thorough
|
||||||
description. Tools that turn commits into email, for example, use
|
description. The text up to the first blank line in a commit
|
||||||
the first line on the Subject line and the rest of the commit in the
|
message is treated as the commit title, and that title is used
|
||||||
body.
|
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.
|
||||||
|
|
||||||
|
|
||||||
[[ignoring-files]]
|
[[ignoring-files]]
|
||||||
Ignoring files
|
Ignoring files
|
||||||
|
|
Loading…
Reference in a new issue