doc: move author and committer information to git-commit(1)

While at one time it made perfect sense to store information about
configuring author and committer information in the documentation for
git commit-tree, in modern Git that operation is seldom used.  Most
users will use git commit and expect to find comprehensive documentation
about its use in the manual page for that command.

Considering that there is significant confusion about how one is to use
the user.name and user.email variables, let's put as much documentation
as possible into an obvious place where users will be more likely to
find it.

In addition, expand the environment variables section to describe their
use more fully.  Even though we now describe all of the options there
and in the configuration settings documentation, preserve the existing
text in git-commit.txt so that people can easily reason about the
ordering of the various options they can use.  Explain the use of the
author.* and committer.* options as well.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index 0557cbbceb8159148e8d0e7ab4771a8f53a67c0a..a1f80e823c497ecca7f6f4779333ba95cbb74417 100644 (file)
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -13,7 +13,7 @@ committer.email::
        Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
        `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
        `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
-       See linkgit:git-commit-tree[1] for more information.
+       See linkgit:git-commit[1] for more information.
 
 user.useConfigOnly::
        Instruct Git to avoid trying to guess defaults for `user.email`

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 4b90b9c12a4a87fe563d367ab8252750021969d7..ec15ee8d6fad83d5dfe7d019cbb5984303552d9e 100644 (file)
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -69,7 +69,6 @@ OPTIONS
        Do not GPG-sign commit, to countermand a `--gpg-sign` option
        given earlier on the command line.
 
-
 Commit Information
 ------------------
 
@@ -79,26 +78,6 @@ A commit encapsulates:
 - author name, email and date
 - committer name and email and the commit time.
 
-While parent object ids are provided on the command line, author and
-committer information is taken from the following environment variables,
-if set:
-
-       GIT_AUTHOR_NAME
-       GIT_AUTHOR_EMAIL
-       GIT_AUTHOR_DATE
-       GIT_COMMITTER_NAME
-       GIT_COMMITTER_EMAIL
-       GIT_COMMITTER_DATE
-
-(nb "<", ">" and "\n"s are stripped)
-
-In case (some of) these environment variables are not set, the information
-is taken from the configuration items user.name and user.email, or, if not
-present, the environment variable EMAIL, or, if that is not set,
-system user name and the hostname used for outgoing mail (taken
-from `/etc/mailname` and falling back to the fully qualified hostname when
-that file does not exist).
-
 A commit comment is read from stdin. If a changelog
 entry is not provided via "<" redirection, 'git commit-tree' will just wait
 for one to be entered and terminated with ^D.
@@ -117,6 +96,7 @@ FILES
 SEE ALSO
 --------
 linkgit:git-write-tree[1]
+linkgit:git-commit[1]
 
 GIT
 ---

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index ced5a9beab159de86148b94bc1825247ead79390..30c30ccd806e5aa7ec98482100b93c4aa21efc34 100644 (file)
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -367,9 +367,6 @@ changes to tracked files.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
 
-:git-commit: 1
-include::date-formats.txt[]
-
 EXAMPLES
 --------
 When recording your own work, the contents of modified files in
@@ -463,6 +460,30 @@ alter the order the changes are committed, because the merge
 should be recorded as a single commit.  In fact, the command
 refuses to run when given pathnames (but see `-i` option).
 
+COMMIT INFORMATION
+------------------
+
+Author and committer information is taken from the following environment
+variables, if set:
+
+       GIT_AUTHOR_NAME
+       GIT_AUTHOR_EMAIL
+       GIT_AUTHOR_DATE
+       GIT_COMMITTER_NAME
+       GIT_COMMITTER_EMAIL
+       GIT_COMMITTER_DATE
+
+(nb "<", ">" and "\n"s are stripped)
+
+In case (some of) these environment variables are not set, the information
+is taken from the configuration items `user.name` and `user.email`, or, if not
+present, the environment variable EMAIL, or, if that is not set,
+system user name and the hostname used for outgoing mail (taken
+from `/etc/mailname` and falling back to the fully qualified hostname when
+that file does not exist).
+
+:git-commit: 1
+include::date-formats.txt[]
 
 DISCUSSION
 ----------

diff --git a/Documentation/git.txt b/Documentation/git.txt
index b1597ac002f15492b861b332519cf8b5ea2d9228..0093c647bf64bc5a42d32b948e2d342c0ce61a49 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -482,13 +482,36 @@ double-quotes and respecting backslash escapes. E.g., the value
 Git Commits
 ~~~~~~~~~~~
 `GIT_AUTHOR_NAME`::
+       The human-readable name used in the author identity when creating commit or
+       tag objects, or when writing reflogs. Overrides the `user.name` and
+       `author.name` configuration settings.
+
 `GIT_AUTHOR_EMAIL`::
+       The email address used in the author identity when creating commit or
+       tag objects, or when writing reflogs. Overrides the `user.email` and
+       `author.email` configuration settings.
+
 `GIT_AUTHOR_DATE`::
+       The date used for the author identity when creating commit or tag objects, or
+       when writing reflogs. See linkgit:git-commit[1] for valid formats.
+
 `GIT_COMMITTER_NAME`::
+       The human-readable name used in the committer identity when creating commit or
+       tag objects, or when writing reflogs. Overrides the `user.name` and
+       `committer.name` configuration settings.
+
 `GIT_COMMITTER_EMAIL`::
+       The email address used in the author identity when creating commit or
+       tag objects, or when writing reflogs. Overrides the `user.email` and
+       `committer.email` configuration settings.
+
 `GIT_COMMITTER_DATE`::
-'EMAIL'::
-       see linkgit:git-commit-tree[1]
+       The date used for the committer identity when creating commit or tag objects, or
+       when writing reflogs. See linkgit:git-commit[1] for valid formats.
+
+`EMAIL`::
+       The email address used in the author and committer identities if no other
+       relevant environment variable or configuration setting has been set.
 
 Git Diffs
 ~~~~~~~~~