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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 3, 2026, 20:36 UTC
Message-ID: <xmqqy0k8bqgs.fsf@gitster.g>
In-Reply-To: <CAP9es6uT4xE2+h6mCXgYVcibutVOah1xKyS8cKaV1u=VHBpLZw@mail.gmail.com>

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

Show 12 quoted lines

>> 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.

Show 13 quoted lines

>>  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.