From: Ori Avtalion <ori@avtalion.name>
Date: Sat, 08 Aug 2009 13:26:10 GMT
Subject: Re: [PATCH] Change mentions of "git programs" to "git commands"
Message-ID: <4A7D7CF2.40902@avtalion.name>
In-Reply-To: <7v4osj1odt.fsf@alter.siamese.dyndns.org>

On 08/07/2009 09:15 PM, Junio C Hamano wrote:
> Ori Avtalion<ori@avtalion.name>  writes:
>
>> Most of the docs and printouts refer to "commands".
>> This patch changes the other terminology to be consistent.
>
> Thanks, but not really.
>
>> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
>> index d313795..20bf512 100644
>> --- a/Documentation/fetch-options.txt
>> +++ b/Documentation/fetch-options.txt
>> @@ -1,7 +1,7 @@
>>   -q::
>>   --quiet::
>>   	Pass --quiet to git-fetch-pack and silence any other internally
>> -	used programs.
>> +	used utilities.
>
> This does not have much to do with what you claim to have done in the
> commit log message nor the title.  Probably "utilities" is a slightly
> better word than "programs" in this context but not by a wide margin.
>

I picked the word from the glossary definition of "core git":

   "Fundamental data structures and utilities of git. [...]"

If that doesn't fit, how about:
    "Pass --quiet to git-fetch-pack and silence other output" ?

>> -'git-rev-list' is a very essential git program, since it
>> +'git-rev-list' is a very essential git command, since it
>>   provides the ability to build and traverse commit ancestry graphs. For
>>   this reason, it has a lot of different options that enables it to be
>>   used by commands as different as 'git-bisect' and
>
> Ok, but probably we would want to say "git rev-list" here.

In that case, shouldn't all of the manpages be changed to say "git foo" 
instead of "git-foo" under the NAME section?

I see the "git-foo" notation as a convention for git commands.
It may be for historical reasons, but the manpage for the "pull" git 
command is "git-pull", and that is how commands are mentioned all over 
the documentation.

>
>>   --exec-path::
>> -	Path to wherever your core git programs are installed.
>> +	Path to wherever your core git commands are installed.
>
> I do not think this is a good change.
>
> When you talk about git "command", e.g. "'git rev-list' is an essential
> command", you are talking about an abstract concept.  In the reader's
> world view, there is one single toplevel program called "git" and it has
> various commands, one of which is 'rev-list'.  But this description is not
> about an abstract concept of command, but is about a particular
> implementation detail.  For every git command, there is a corresponding
> git _program_ that implements that command, and --exec-path tells you (or
> you use --exec-path to tell the git toplevel program) where they are.
>
> You kept this intact in gitcore-tutorial:
>
>      ... Also
>      you need to make sure that you have the 'git-receive-pack'
>      program on the `$PATH`.
>
> and I think you did the right thing.  This is about a concrete instance of
> a program.  If you really really want to say _command_, you would probably
> want to do something like this instead:
>
>   --exec-path::
> -	Path to wherever your core git programs are installed.
> +	Path to the directory that holds programs that implements git commands.
>

I agree with the suggestion.


I found a few other instances that should probably be changed.

In git.txt:
"The following are helper programs used by the above"
                           ^^^^^^^^
                           commands

In git-mailsplit.txt (and cmds-purehelpers.txt):
    "Simple UNIX mbox splitter program."

Maybe the word "program" should just be dropped.


I'll submit a new patch once there's an agreement on the changes.

-Ori