Can't figure out some sense from the git-commit-tree man page

Hi,

The git-commit-tree man page reads:
  A commit encapsulates:

  ·   all parent object ids

  ·   author name, email and date

  ·   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense. If you're not setting the
author and committer in your config or environment, how are you supposed
to provide it ?

Naively, I tried sending a "git-cat-file commit" looking text to stdin,
but it just ended up in the changelog, which was actually no surprise.

Mike

Hi,

On Fri, 17 Aug 2007, Mike Hommey wrote:

  ?   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense.

It does, if you know how to specify the committer info.  Which the man 
page specifies how to provide:

This can be overridden by either `.git/config` file, or using the 
following environment variables.

        GIT_AUTHOR_NAME
        GIT_AUTHOR_EMAIL
        GIT_AUTHOR_DATE
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
        GIT_COMMITTER_DATE
        EMAIL

Hth,
Dscho

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin [off-list ref] wrote:

Hi,

On Fri, 17 Aug 2007, Mike Hommey wrote:

quoted

  ?   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense.

It does, if you know how to specify the committer info.  Which the man 
page specifies how to provide:

This can be overridden by either `.git/config` file, or using the 
following environment variables.

        GIT_AUTHOR_NAME
        GIT_AUTHOR_EMAIL
        GIT_AUTHOR_DATE
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
        GIT_COMMITTER_DATE
        EMAIL

This is exactly where the man page doesn't make sense to me. It tells
you that if you don't provide committer name, etc. it uses your name,
hostname, etc., and you can override this with .git/config or the
environment variable you listed.

So where were you supposed to provide these informations in the first
place ?

Mike

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin wrote:

Hi,

On Fri, 17 Aug 2007, Mike Hommey wrote:

quoted

  ?   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense.

It does, if you know how to specify the committer info.

Which the man page specifies how to provide:

At least on a first reading all of the following appears to fall under
the "if not provided" case.  I know what you mean, but the language here
is misleading.  One simple fix would be just to delete the words "If not
provided", or maybe replace them by "By default, ...".

--b.

This can be overridden by either `.git/config` file, or using the 
following environment variables.

        GIT_AUTHOR_NAME
        GIT_AUTHOR_EMAIL
        GIT_AUTHOR_DATE
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
        GIT_COMMITTER_DATE
        EMAIL

Hi,

On Fri, 17 Aug 2007, Mike Hommey wrote:

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin [off-list ref] wrote:

quoted

On Fri, 17 Aug 2007, Mike Hommey wrote:

quoted

  ?   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense.

It does, if you know how to specify the committer info.  Which the man 
page specifies how to provide:

This can be overridden by either `.git/config` file, or using the 
following environment variables.

        GIT_AUTHOR_NAME
        GIT_AUTHOR_EMAIL
        GIT_AUTHOR_DATE
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
        GIT_COMMITTER_DATE
        EMAIL

This is exactly where the man page doesn't make sense to me. It tells
you that if you don't provide committer name, etc. it uses your name,
hostname, etc., and you can override this with .git/config or the
environment variable you listed.

So where were you supposed to provide these informations in the first
place ?

In /etc/passwd.  Like on every Unix system.  (Oh yeah, there is NIS and 
other things, but in effect it is the same system.)

Ciao,
Dscho

On Fri, Aug 17, 2007 at 06:30:34PM +0200, Mike Hommey wrote:

Hi,

The git-commit-tree man page reads:
  A commit encapsulates:

  ·   all parent object ids

  ·   author name, email and date

  ·   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense. If you're not setting the
author and committer in your config or environment, how are you supposed
to provide it ?

Makes sense to me. I interpreted it as:

  If not provided (by one of the ways I'm about to mention), the default
  is ... This default can be overridden by ...

I can understand how it might be read differently, though. Assuming my
reading is correct, might something along these lines be clearer:

  To find author and committer info, "git-commit-tree" first looks at
  these environment variables:

  ...

  If they are not set, it tries the keys user.name and user.email from
  the .git/config file. Finally, it falls back to using your name,
  hostname, and domain.

Even clearer, though this might be a bit extreme, would be to not
mention .git/config and say it reads the global or repository-specific
keys using git-config.

-- 
"I like talking to Rabbit.  He talks  about sensible things.  He doesn't
use long,  difficult words,  like Owl.  He uses short,  easy words, like
'What about  lunch?' and  'Help yourself,  Pooh.'  I suppose,  really, I
ought to go and see Rabbit."     A. A. Milne, 'The House at Pooh Corner'

[Cc: Mike Hommey [off-list ref], git@vger.kernel.org]

Mike Hommey wrote:

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin [off-list ref] wrote:

quoted

On Fri, 17 Aug 2007, Mike Hommey wrote:

quoted

  ?   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense.

It does, if you know how to specify the committer info.  Which the man 
page specifies how to provide:

This can be overridden by either `.git/config` file, or using the 
following environment variables.

        GIT_AUTHOR_NAME
        GIT_AUTHOR_EMAIL
        GIT_AUTHOR_DATE
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
        GIT_COMMITTER_DATE
        EMAIL

This is exactly where the man page doesn't make sense to me. It tells
you that if you don't provide committer name, etc. it uses your name,
hostname, etc., and you can override this with .git/config or the
environment variable you listed.

So where were you supposed to provide these informations in the first
place ?

Where you are supposed to provide this information? In .git/config (per
repository) or in ~/.gitconfig (per user), in the form:

[user]
        name  = Mike Hommey
        email = mh@glandium.org


"If not provided" means that git gets your user name from system, from the
GECOS files in /etc/passwd, and composes your email address from your user
id (account name), and from the hostname of your machine (or "(localhost)").
This is last resort fallback, so you better provide user and email yourself.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

On Fri, Aug 17, 2007 at 01:04:11PM -0400, J. Bruce Fields [off-list ref] wrote:

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin wrote:

quoted

Hi,

On Fri, 17 Aug 2007, Mike Hommey wrote:

quoted

  ?   committer name and email and the commit time.
  If not provided, "git-commit-tree" uses your name, hostname and domain to
  provide author and committer info. This can be overridden by either
  .git/config file, or using the following environment variables.
  (...)

The "If not provided" part doesn't make sense.

It does, if you know how to specify the committer info.

Which the man page specifies how to provide:

At least on a first reading all of the following appears to fall under
the "if not provided" case.  I know what you mean, but the language here
is misleading.  One simple fix would be just to delete the words "If not
provided", or maybe replace them by "By default, ...".

I think it would be better to put the fact that "If not provided..."
*after* telling that you can provide author, committer, etc. by setting
environment or editing the conf.

Mike

On Fri, Aug 17, 2007 at 07:23:23PM +0200, Mike Hommey wrote:

I think it would be better to put the fact that "If not provided..."
*after* telling that you can provide author, committer, etc. by setting
environment or editing the conf.

Yup, probably.  Patch?

--b.

As per http://marc.info/?l=git&m=118737219702802&w=2 , clarify
git-commit-tree documentation.

Signed-off-by: Mike Hommey <redacted>
---
 Documentation/git-commit-tree.txt |   15 ++++++---------
 1 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 5870c2c..6a328f4 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt

@@ -51,9 +51,9 @@ A commit encapsulates:
 - author name, email and date
 - committer name and email and the commit time.
 
-If not provided, "git-commit-tree" uses your name, hostname and domain to
-provide author and committer info. This can be overridden by
-either `.git/config` file, or using the following environment variables.
+While parent object ids are provided on the command line, author and
+commiter information is taken from the following environment variables,
+if set:
 
 	GIT_AUTHOR_NAME
 	GIT_AUTHOR_EMAIL

@@ -65,12 +65,9 @@ either `.git/config` file, or using the following environment variables.
 
 (nb "<", ">" and "\n"s are stripped)
 
-In `.git/config` file, the following items are used for GIT_AUTHOR_NAME and
-GIT_AUTHOR_EMAIL:
-
-	[user]
-		name = "Your Name"
-		email = "your@email.address.xz"
+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, system user name and fully qualified hostname.
 
 A commit comment is read from stdin. If a changelog
 entry is not provided via "<" redirection, "git-commit-tree" will just wait

-- 
1.5.3.rc4