undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
brian m. carlson 2020-01-22 03:45:39 +00:00 committed by Junio C Hamano
parent 232378479e
commit bc94e5862a
4 changed files with 51 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/config/user.txt
View File

@ -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`

22
Documentation/git-commit-tree.txt
View File

@ -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
---

27
Documentation/git-commit.txt
View File

@ -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
----------

27
Documentation/git.txt
View File

@ -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
~~~~~~~~~