Re: [PATCH v3] doc: add information regarding external commands

[Junio C Hamano <gitster@pobox.com>]

Omri Sarig <omri.sarig13@gmail.com> writes:

>> I am not sure what the last sentence wants to say, especially the
>> "alias expansion" part.  Do you mean that your "git foo" alias (not
>> just its expansion but its presence as a whole) is ignored if you
>> have a "git-foo" program on your $PATH?
>
> This is exactly what I tried to write there.
> Personally, I had expected aliases to take precedence over external commands,
> so I was surprised to see that it is reversed (so the program "git-foo" runs
> before Git looks for the alias "git foo"). I thought it'll make sense to
> mention in the documentation, to save possible headaches for future developers.
>
> I'm not sure it's too much information, or should just be described better?

The latter.

We hear "X takes precedence over Y" more often when we describe the
relationship between commands and aliases.  I do not think we use
verb "X precedes Y" in our documentation to indicate that
relationship.  We do see the verb used for "X comes before Y" in
many places in our documentation, though.

Here is my attempt.

    ... Argument passed after the command name are passed as-is to
    the program.  To execute `git <foo>`, `git` finds command
    `<foo>` (either a core Git program found in 'GIT_EXEC_PATH', or
    a custom one in a directory on 'PATH'), before trying `foo` as
    an alias.

>>  We divide Git into high level ("porcelain") commands and low level
>> -("plumbing") commands.
>> +("plumbing") commands.  For defining command aliases, see
>> +linkgit:gitconfig[1] and look for descriptions of `alias.*`.
>> +For installing custom "git" subcommands, see the description for
>> +the 'PATH' environment variable in this manual.
>>
>>  High-level commands (porcelain)
>>  -------------------------------
>
> I agree - that makes good sense to me too.
>
> Do you see it as belonging in the same commit, or in a subsequent commit?

Totally outside of your topic.  Let's concentrate on the PATH thing
and finish it first.

Thanks.