threads / discuss / 9562

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

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

## tl;dr

11 messages between Aug 17, 2007 and Aug 17, 2007.

replies: 10people: 6as markdown or json

Mike Hommey· Aug 17, 2007, 16:30 UTC · lore
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
Johannes Schindelin· Aug 17, 2007, 16:52 UTC · re: Mike Hommey · lore

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

Hi,
On Fri, 17 Aug 2007, Mike Hommey wrote:
Show 7 quoted lines
>   ?   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

Mike Hommey· Aug 17, 2007, 16:56 UTC · re: Johannes Schindelin · lore

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

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
Show 25 quoted lines
> 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

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
Johannes Schindelin· Aug 17, 2007, 17:09 UTC · re: Mike Hommey · lore

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

Hi,
On Fri, 17 Aug 2007, Mike Hommey wrote:
Show 33 quoted lines
> On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> > 
> > 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
> 
> 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

Jakub Narebski· Aug 17, 2007, 17:16 UTC · re: Mike Hommey · lore

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

[Cc: Mike Hommey <mh@glandium.org>, git@vger.kernel.org]
Mike Hommey wrote:
Show 33 quoted lines
> On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
>> 
>> 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
> 
> 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
J. Bruce Fields· Aug 17, 2007, 17:04 UTC · re: Johannes Schindelin · lore

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

On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin wrote:
Show 15 quoted lines
> 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:

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.
Show 11 quoted lines
> 
> 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
Mike Hommey· Aug 17, 2007, 17:23 UTC · re: J. Bruce Fields · lore

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

On Fri, Aug 17, 2007 at 01:04:11PM -0400, J. Bruce Fields <bfields@fieldses.org> wrote:
Show 21 quoted lines
> On Fri, Aug 17, 2007 at 05:52:52PM +0100, Johannes Schindelin wrote:
> > 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:
> 
> 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
J. Bruce Fields· Aug 17, 2007, 17:36 UTC · re: Mike Hommey · lore

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

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.
Mike Hommey· Aug 17, 2007, 20:13 UTC · re: J. Bruce Fields · lore

[PATCH] Clarify commit-tree documentation

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

Signed-off-by: Mike Hommey <mh@glandium.org>
---
 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
Daniel Hulme· Aug 17, 2007, 16:55 UTC · re: Mike Hommey · lore

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

On Fri, Aug 17, 2007 at 06:30:34PM +0200, Mike Hommey wrote:
Show 18 quoted lines
> 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'

← back to recent threads