On Sat, Nov 02, 2019 at 07:26:12PM +0000, brian m. carlson wrote: > 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: > +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: > +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
