git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)

From
Jakub Narebski <jnareb@gmail.com>
Date
Nov 3, 2019, 11:13 UTC
Message-ID
<86y2wx5i1c.fsf@gmail.com>
In-Reply-To
<20191102192615.10013-2-sandals@crustytoothpaste.net>
"brian m. carlson" <sandals@crustytoothpaste.net> writes:
Show 28 quoted lines
> 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.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/config/user.txt     |  2 +-
>  Documentation/git-commit-tree.txt | 39 ++++---------------------------
>  Documentation/git-commit.txt      | 34 ++++++++++++++++++++++++---
>  3 files changed, 37 insertions(+), 38 deletions(-)
>
> diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
> index 0557cbbceb..a1f80e823c 100644
> --- 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.
O.K., lets refer users to the command they actually use.
Show 14 quoted lines
>  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 4b90b9c12a..d518dffce0 100644
> --- a/Documentation/git-commit-tree.txt
> +++ b/Documentation/git-commit-tree.txt
> @@ -42,6 +42,10 @@ tend to just write the result to the file that is pointed at by
>  `.git/HEAD`, so that we can always see what the last committed
>  state was.
>  
> +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.
> +

I understand this is what is extracted from the removed part (moved to git-commit documentation). But I think it is not enough to understand how to actually use this command; this change makes reference documentation not self contained.

Show 16 quoted lines
>  OPTIONS
>  -------
>  <tree>::
> @@ -69,40 +73,6 @@ OPTIONS
>  	Do not GPG-sign commit, to countermand a `--gpg-sign` option
>  	given earlier on the command line.
>  
> -
> -Commit Information
> -------------------
> -
> -A commit encapsulates:
> -
> -- all parent object ids
> -- author name, email and date
> -- committer name and email and the commit time.

O.K., I can understand moving this information to a better place (nb. what about gitglossry?).

Show 20 quoted lines
> -
> -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).

I'm not sure if this should not be left here, perhaps extracted into separate fragment file to be included in both git-commit-tree.txt and in git-commit.txt

I see that we are missing the ebvious information that if GIT_*_DATE environment variables are not set, Git will use current date and time. Is there a place where we say what format GIT_*_DATE needs to be in?

Show 13 quoted lines
> -
> -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.
> -
>  include::date-formats.txt[]
>  
>  Discussion
> @@ -117,6 +87,7 @@ FILES
>  SEE ALSO
>  --------
>  linkgit:git-write-tree[1]
> +linkgit:git-commit[1]
All right.
Show 14 quoted lines
>  
>  GIT
>  ---
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index afa7b75a23..f684f7fdc2 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -352,9 +352,6 @@ changes to tracked files.
>  	these files are also staged for the next commit on top
>  	of what have been staged before.
>  
> -:git-commit: 1
> -include::date-formats.txt[]
> -
All right, it is moved down, not removed.
Show 17 quoted lines
>  EXAMPLES
>  --------
>  When recording your own work, the contents of modified files in
> @@ -448,6 +445,37 @@ 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
> +------------------
> +
> +A commit encapsulates:
> +
> +- all parent object ids
> +- author name, email and date
> +- committer name and email and the commit time.
> +
> +While parent object ids are provided on the command line,
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This was true for `git commit-tree`, with the following synopsis
  git commit-tree <tree> [(-p <parent>)…​]
  git commit-tree [(-p <parent>)…​] [-S[<keyid>]] [(-m <message>)…​]
  		  [(-F <file>)…​] <tree>
This is decidely *NOT true* for `git commit`:
  git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
  	   [--dry-run] [(-c | -C | --fixup | --squash) <commit>]
  	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
  	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
  	   [--date=<date>] [--cleanup=<mode>] [--[no-]status]
  	   [-i | -o] [-S[<keyid>]] [--] [<file>…​]
Parent ids are *not* provided on the command line.
Show 19 quoted lines
>                                                            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).

I think that this description, while perfectly fine for plumbing command `git commit-tree`, might be needlesly confusing for `git commit` users, as it describes less often common used way of providing committer and author information first.

Also in `git commit` there are *options* specifically for adjusting how committer and author information is handled: `--reuse-message=<commit>` and `--reedit-message=<commit>`, `--reset-author` (doesn't make sense alone), `--author=<author>` and `--date=<date>`.

Maybe describe usual way first, then describe the various options and their priority?

Show 6 quoted lines
> +
> +:git-commit: 1
> +include::date-formats.txt[]
>  
>  DISCUSSION
>  ----------
Best,
-- 
Jakub Narębski
Previous: brian m. carlsonNext: Jeff King
Message 17 of 25 in “Documentation for common user misconceptions”
  1. 0/4 Documentation for common user misconceptionsbrian m. carlson, Nov 2, 2019
  2. 2/4 doc: provide guidance on user.name formatbrian m. carlson, Nov 2, 2019
  3. Jakub NarebskiNov 3, 2019
  4. brian m. carlsonNov 3, 2019
  5. 3/4 doc: dissuade users from trying to ignore tracked filesbrian m. carlson, Nov 2, 2019
  6. rsbecker@nexbridge.comNov 2, 2019
  7. Jakub NarebskiNov 3, 2019
  8. Jakub NarebskiNov 3, 2019
  9. brian m. carlsonNov 3, 2019
  10. Jakub NarebskiNov 3, 2019
  11. brian m. carlsonNov 3, 2019
  12. Jakub NarebskiNov 5, 2019
  13. Jeff KingNov 4, 2019
  14. brian m. carlsonNov 4, 2019
  15. 4/4 docs: mention when increasing http.postBuffer is valuablebrian m. carlson, Nov 2, 2019
  16. 1/4 doc: move author and committer information to git-commit(1)brian m. carlson, Nov 2, 2019
  17. Jakub NarebskiNov 3, 2019
  18. Jeff KingNov 4, 2019
  19. Junio C HamanoNov 6, 2019
  20. Jeff KingNov 4, 2019
  21. Junio C HamanoNov 6, 2019
  22. brian m. carlsonNov 6, 2019
  23. Junio C HamanoNov 6, 2019
  24. Emily ShafferJan 16, 2020
  25. brian m. carlsonJan 16, 2020

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.