summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLibravatar Junio C Hamano <gitster@pobox.com>2012-09-17 15:53:39 -0700
committerLibravatar Junio C Hamano <gitster@pobox.com>2012-09-17 15:53:39 -0700
commitd6e32f6af5b806b4af18b1a4eba578a859a26056 (patch)
treea0d368a62a5a4038b84ac0e613862ce7f23995df
parentMerge branch 'mh/string-list' (diff)
parentDocumentation: describe subject more precisely (diff)
downloadtgif-d6e32f6af5b806b4af18b1a4eba578a859a26056.tar.xz
Merge branch 'jw/doc-commit-title'
Update parts of document that talked about "first line of commit log" to say "title of commit" with definition of what that "title" is. * jw/doc-commit-title: Documentation: describe subject more precisely
-rw-r--r--Documentation/git-commit.txt6
-rw-r--r--Documentation/git-for-each-ref.txt7
-rw-r--r--Documentation/git-format-patch.txt11
-rw-r--r--Documentation/git-shortlog.txt3
-rw-r--r--Documentation/gitcore-tutorial.txt9
-rw-r--r--Documentation/gittutorial.txt8
-rw-r--r--Documentation/user-manual.txt9
7 files changed, 31 insertions, 22 deletions
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 4622297ec9..9594ac8e9d 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -389,8 +389,10 @@ 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
-on the Subject: line and the rest of the commit in the body.
+The text up to the first blank line in a commit message is treated
+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[]
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index c872b883ba..db55a4e0bb 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`.
For sorting purposes, fields with numeric values sort in numeric
order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 04c7346e3e..6d43f56279 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`.
If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
`References` headers to make the second and subsequent patch mails appear
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index 01d8417316..afeb4cdf16 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
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.
+in release announcements. Each commit will be grouped by author and title.
Additionally, "[PATCH]" will be stripped from the commit description.
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index 9d893369a0..5325c5a7d5 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -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
-and the first line 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
+with the titles of 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
`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 (`*`
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
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index dee050567e..f1cb6f3be6 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -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
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 body.
+thorough description. The text up to the first blank line in a commit
+message is treated 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.
Git tracks content not files
----------------------------
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 03d95dc290..85651b57ae 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1136,9 +1136,12 @@ Creating good 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 commit in the
-body.
+description. The text up to the first blank line in a commit
+message is treated 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.
+
[[ignoring-files]]
Ignoring files