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>
brian m. carlson committed
Jan 22, 2020 at 03:45 UTC
bc94e5862aed854c77d4f96da9447161ce84a824
4 files changed
+51
-27
Documentation/config/user.txt
+1
-1
@@ -13,7 +13,7 @@ committer.email::
13
Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
14
`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
15
`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
16
- See linkgit:git-commit-tree[1] for more information.
16
+ See linkgit:git-commit[1] for more information.
17
18
user.useConfigOnly::
19
Instruct Git to avoid trying to guess defaults for `user.email`
Documentation/git-commit-tree.txt
+1
-21
@@ -69,7 +69,6 @@ OPTIONS
69
Do not GPG-sign commit, to countermand a `--gpg-sign` option
70
given earlier on the command line.
71
72
-
72
Commit Information
73
------------------
74
@@ -79,26 +78,6 @@ A commit encapsulates:
78
- author name, email and date
79
- committer name and email and the commit time.
80
82
-While parent object ids are provided on the command line, author and
83
-committer information is taken from the following environment variables,
84
-if set:
85
-
86
- GIT_AUTHOR_NAME
87
- GIT_AUTHOR_EMAIL
88
- GIT_AUTHOR_DATE
89
- GIT_COMMITTER_NAME
90
- GIT_COMMITTER_EMAIL
91
- GIT_COMMITTER_DATE
92
-
93
-(nb "<", ">" and "\n"s are stripped)
94
-
95
-In case (some of) these environment variables are not set, the information
96
-is taken from the configuration items user.name and user.email, or, if not
97
-present, the environment variable EMAIL, or, if that is not set,
98
-system user name and the hostname used for outgoing mail (taken
99
-from `/etc/mailname` and falling back to the fully qualified hostname when
100
-that file does not exist).
101
-
81
A commit comment is read from stdin. If a changelog
82
entry is not provided via "<" redirection, 'git commit-tree' will just wait
83
for one to be entered and terminated with ^D.
@@ -117,6 +96,7 @@ FILES
96
SEE ALSO
97
--------
98
linkgit:git-write-tree[1]
99
+linkgit:git-commit[1]
100
101
GIT
102
---
Documentation/git-commit.txt
+24
-3
@@ -367,9 +367,6 @@ changes to tracked files.
367
+
368
For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
369
370
-:git-commit: 1
371
-include::date-formats.txt[]
372
-
370
EXAMPLES
371
--------
372
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
460
should be recorded as a single commit. In fact, the command
461
refuses to run when given pathnames (but see `-i` option).
462
463
+COMMIT INFORMATION
464
+------------------
465
+
466
+Author and committer information is taken from the following environment
467
+variables, if set:
468
+
469
+ GIT_AUTHOR_NAME
470
+ GIT_AUTHOR_EMAIL
471
+ GIT_AUTHOR_DATE
472
+ GIT_COMMITTER_NAME
473
+ GIT_COMMITTER_EMAIL
474
+ GIT_COMMITTER_DATE
475
+
476
+(nb "<", ">" and "\n"s are stripped)
477
+
478
+In case (some of) these environment variables are not set, the information
479
+is taken from the configuration items `user.name` and `user.email`, or, if not
480
+present, the environment variable EMAIL, or, if that is not set,
481
+system user name and the hostname used for outgoing mail (taken
482
+from `/etc/mailname` and falling back to the fully qualified hostname when
483
+that file does not exist).
484
+
485
+:git-commit: 1
486
+include::date-formats.txt[]
487
488
DISCUSSION
489
----------
Documentation/git.txt
+25
-2
@@ -482,13 +482,36 @@ double-quotes and respecting backslash escapes. E.g., the value
482
Git Commits
483
~~~~~~~~~~~
484
`GIT_AUTHOR_NAME`::
485
+ The human-readable name used in the author identity when creating commit or
486
+ tag objects, or when writing reflogs. Overrides the `user.name` and
487
+ `author.name` configuration settings.
488
+
489
`GIT_AUTHOR_EMAIL`::
490
+ The email address used in the author identity when creating commit or
491
+ tag objects, or when writing reflogs. Overrides the `user.email` and
492
+ `author.email` configuration settings.
493
+
494
`GIT_AUTHOR_DATE`::
495
+ The date used for the author identity when creating commit or tag objects, or
496
+ when writing reflogs. See linkgit:git-commit[1] for valid formats.
497
+
498
`GIT_COMMITTER_NAME`::
499
+ The human-readable name used in the committer identity when creating commit or
500
+ tag objects, or when writing reflogs. Overrides the `user.name` and
501
+ `committer.name` configuration settings.
502
+
503
`GIT_COMMITTER_EMAIL`::
504
+ The email address used in the author identity when creating commit or
505
+ tag objects, or when writing reflogs. Overrides the `user.email` and
506
+ `committer.email` configuration settings.
507
+
508
`GIT_COMMITTER_DATE`::
490
-'EMAIL'::
491
- see linkgit:git-commit-tree[1]
509
+ The date used for the committer identity when creating commit or tag objects, or
510
+ when writing reflogs. See linkgit:git-commit[1] for valid formats.
511
+
512
+`EMAIL`::
513
+ The email address used in the author and committer identities if no other
514
+ relevant environment variable or configuration setting has been set.
515
516
Git Diffs
517
~~~~~~~~~