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

From: Jeff King <peff@peff.net>
Date: Nov 4, 2019, 22:18 UTC
Message-ID: <20191104221822.GA22367@sigill.intra.peff.net>
In-Reply-To: <20191102192615.10013-2-sandals@crustytoothpaste.net>

On Sat, Nov 02, 2019 at 07:26:12PM +0000, brian m. carlson wrote:

Show 10 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.

I think we might want to keep documentation that gets too low-level out of git-commit(1).

So for instance, this part that got moved from commit-tree:

Show 6 quoted lines

> +A commit encapsulates:
> +
> +- all parent object ids
> +- author name, email and date
> +- committer name and email and the commit time.
> +

I think could just stay there.

The part just below that:

Show 12 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)

would be appropriate in git-commit. Though possibly they should just be broken out into an ENVIRONMENT VARIABLES section.

I thought we already did so in git.txt, but it looks like it just refers to commit-tree (and if we don't do anything more drastic, I think you'd probably want to update that reference). Since these do affect multiple commands, I wonder if it would make sense to define them there in git.txt, giving a more user-facing description. Something like:

  GIT_COMMITTER_NAME::
	The human-readable name used in the committer identity when
	creating commit or tags objects, or when writing reflogs.
	Overrides the user.name config.

and so forth for COMMITTER_EMAIL, AUTHOR_NAME, etc.

-Peff