Thanks for the help!

I fully understand this is something you can just do in a few minutes, so I
really appreciate the support and the welcoming attitude.

On Tue, Mar 3, 2026 at 7:40 PM Junio C Hamano [off-list ref] wrote:

"Omri Sarig via GitGitGadget" [off-list ref] writes:

Thanks.  Almost there.

The usual way to compose a log message of this project is to

 - Give an observation on how the current system works in the
   present tense (so no need to say "Currently X is Y", or
   "Previously X was Y" to describe the state before your change;
   just "X is Y" is enough), and discuss what you perceive as a
   problem in it.

 - Propose a solution (optional---often, problem description
   trivially leads to an obvious solution in reader's minds).

 - Give commands to somebody editing the codebase to "make it so",
   instead of saying "This commit does X".

in this order.

Understood, I'll fix accordingly.

quoted

From: Omri Sarig <redacted>

Git supports running external commands in the user's PATH as if they
were built-in commands (see execv_dashed_external in git.c).

This feature was not fully documented in Git's user-facing
documentation.

Your description of the problem above is excellent.

quoted

This commit adds a short documentation of this feature, making it easier
for users to discover and use.

There is nothing incorrect in the above, but we would write it more
like

    Add a short documentation to describe how PATH is used to find a
    custom subcommand.

quoted

Signed-off-by: Omri Sarig <redacted>

quoted

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index ce099e78b8..903d11c530 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc

@@ -487,6 +487,13 @@ System
      `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist;
      otherwise `$USERPROFILE` if `$USERPROFILE` exists.

+`PATH`::
+     When a user runs 'git <command>' that is not part of the core Git programs
+     (installed in GIT_EXEC_PATH), 'git-<command>' that is runnable by the user
+     in a directory on `$PATH` is invoked. Argument passed after the command

OK.

quoted

+     name are passed as-is to the runnable program. These commands precedes
+     alias expansion.

We are not going to try running a program that is not runnable
anyway, so "the runnable program" -> "the program", probably?

Completely agree, will fix.

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?

Maybe adding a second paragraph with something like this can be clearer:

    External commands precedes aliases. For example, running "git foo" will
    execute "git-foo" from PATH; only if "git-foo" does not exist, will Git
    look for the alias "foo".

What do you think?

I agree - that makes good sense to me too.

Do you see it as belonging in the same commit, or in a subsequent commit? I'm
not fully clear about the rules for splitting such commits in the repo.

Thanks,
With Kind Regards,
Omri