summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2020-02-14 20:42:31 (GMT)
committerJunio C Hamano <gitster@pobox.com>2020-02-14 20:42:31 (GMT)
commit6e69042e26ebf17f3eda60ec90c39ee179e9bc53 (patch)
tree21bb557594e480149fedd9b48d97fdf82764cf68
parent650ed395be1cfe5d213378402bc3a778b46fb974 (diff)
parent69e104d70e29060742c75ccdcb6653e23c65f3c3 (diff)
downloadgit-6e69042e26ebf17f3eda60ec90c39ee179e9bc53.zip
git-6e69042e26ebf17f3eda60ec90c39ee179e9bc53.tar.gz
git-6e69042e26ebf17f3eda60ec90c39ee179e9bc53.tar.bz2
Merge branch 'bc/author-committer-doc' into maint
Clarify documentation on committer/author identities. * bc/author-committer-doc: doc: provide guidance on user.name format docs: expand on possible and recommended user config options doc: move author and committer information to git-commit(1)
-rw-r--r--Documentation/config/user.txt7
-rw-r--r--Documentation/git-commit-tree.txt22
-rw-r--r--Documentation/git-commit.txt40
-rw-r--r--Documentation/git.txt27
4 files changed, 69 insertions, 27 deletions
diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index 0557cbb..59aec7c 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -13,7 +13,12 @@ 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.
++
+Note that the `name` forms of these variables conventionally refer to
+some form of a personal name. See linkgit:git-commit[1] and the
+environment variables section of linkgit:git[1] for more information on
+these settings and the `credential.username` option if you're looking
+for authentication credentials instead.
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 4b90b9c..ec15ee8 100644
--- 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 ced5a9b..13f6539 100644
--- 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,43 @@ 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)
+
+The author and committer names are by convention some form of a personal name
+(that is, the name by which other humans refer to you), although Git does not
+enforce or require any particular form. Arbitrary Unicode may be used, subject
+to the constraints listed above. This name has no effect on authentication; for
+that, see the `credential.username` variable in linkgit:git-config[1].
+
+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).
+
+The `author.name` and `committer.name` and their corresponding email options
+override `user.name` and `user.email` if set and are overridden themselves by
+the environment variables.
+
+The typical usage is to set just the `user.name` and `user.email` variables;
+the other options are provided for more complex use cases.
+
+:git-commit: 1
+include::date-formats.txt[]
DISCUSSION
----------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index b1597ac..0093c64 100644
--- 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
~~~~~~~~~