Re: [PATCH v3] doc: add information regarding external commands
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 3, 2026, 18:40 UTC
- Message-ID
- <xmqqh5qwdaeh.fsf@gitster.g>
- In-Reply-To
- <pull.2220.v3.git.git.1772559813151.gitgitgadget@gmail.com>
"Omri Sarig via GitGitGadget" <gitgitgadget@gmail.com> 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.
Show 7 quoted lines
> From: Omri Sarig <omri.sarig13@gmail.com> > > 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.
> 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.> Signed-off-by: Omri Sarig <omri.sarig13@gmail.com>
Show 12 quoted lines
> 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.
> + 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?
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?
Speaking of "alias", I have always felt that it was suboptimal to make users refer to "git help config" to find out about it. I wonder if "git help git" should be the first place users would look for a help about them?
We have "GIT COMMANDS" section in "git help git" that says "We divide GIt into porcelain and plumbing" and then have two subsections there that list commands that belong to these two categories. Perhaps leaving some breadcrumbs to redirect them would be a good start, something like this?
Documentation/git.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
diff --git c/Documentation/git.adoc w/Documentation/git.adoc index ce099e78b8..fb5b477eda 100644 --- c/Documentation/git.adoc +++ w/Documentation/git.adoc @@ -235,7 +235,10 @@ GIT COMMANDS ------------ 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) -------------------------------