[PATCH] doc: add information regarding external commands

[PATCH] doc: add information regarding external commands

[Omri Sarig via GitGitGadget]

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 documented in any of Git's user-facing
documentation.
This commit adds a short documentation of this feature, making it easier
for users to discover and use.

Signed-off-by: Omri Sarig <omri.sarig13@gmail.com>
---
    doc: Add information regarding external commands

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v1
Pull-Request: https://github.com/git/git/pull/2220

 Documentation/git.adoc | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index ce099e78b8..da7c1329da 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc
@@ -345,6 +345,24 @@ users typically do not use them directly.
 
 include::{build_dir}/cmds-purehelpers.adoc[]
 
+External commands
+-----------------
+
+In addition to the commands implemented by Git, Git will execute any executable
+with the prefix "git-" in the user path as if it is a Git command.
+
+All parameters of the invocation are passed to the script, making running "git
+foo arg1 arg2" equivalent to running "git-foo arg1 arg2".  When running "git
+help" with the command name, Git will invoke the man page for the given
+command, making running "git help foo" equivalent to running "man git-foo".
+
+This makes it possible to extend Git with custom commands, without the need to
+change its source code.
+
+Git looks for external commands after looking for built-in commands, but before
+looking for aliases. Therefore, if an external command have the same name as an
+alias, it'll run instead of the alias.
+
 Guides
 ------
 

base-commit: 2cc71917514657b93014134350864f4849edfc83
-- 
gitgitgadget

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

[Junio C Hamano]

"Omri Sarig via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

Correct.

> This feature was not documented in any of Git's user-facing
> documentation.

"Not documented in any" is a slight exaggeration.  See "git help
git" and look at description of "--list-cmds" option; "all commands
in $PATH that have git- prefix" is mentioned there.  Also "git help
help" talks about "--no-external-commands" that excludes "git-*"
commands found on $PATH from the listing, which implies these things
count as available commands.

Nevertheless, it is a good idea to make it more discoverable.

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

I would have expected that under Environment Variables > System,
next to HOME, we would add an entry for PATH that says something
like:

    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.


or something like that; I didn't expect us to add a dedicated
separate section for it.

Thanks.

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

[Omri Sarig]

Thank you for the reply and review - a fixed patch V2 is incoming shortly.

On Mon, Mar 2, 2026 at 11:56 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Omri Sarig via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > 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).
>
> Correct.
>
> > This feature was not documented in any of Git's user-facing
> > documentation.
>
> "Not documented in any" is a slight exaggeration.  See "git help
> git" and look at description of "--list-cmds" option; "all commands
> in $PATH that have git- prefix" is mentioned there.  Also "git help
> help" talks about "--no-external-commands" that excludes "git-*"
> commands found on $PATH from the listing, which implies these things
> count as available commands.
>
> Nevertheless, it is a good idea to make it more discoverable.
>
> > This commit adds a short documentation of this feature, making it easier
> > for users to discover and use.
>
> I would have expected that under Environment Variables > System,
> next to HOME, we would add an entry for PATH that says something
> like:
>
>     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.
>
>
> or something like that; I didn't expect us to add a dedicated
> separate section for it.

I've added this now as you suggest. I made it slightly more verbose (adding
information about the arguments for the commands, and about it taking
precedence over aliases). If you want it to be shorter again, let me know and
I'll remove this information.

>
> Thanks.
>

With Kind Regards,
Omri

[PATCH v2] doc: add information regarding external commands

[Omri Sarig via GitGitGadget]

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.
This commit adds a short documentation of this feature, making it easier
for users to discover and use.

Signed-off-by: Omri Sarig <omri.sarig13@gmail.com>
---
    doc: Add information regarding external commands

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v2
Pull-Request: https://github.com/git/git/pull/2220

Range-diff vs v1:

 1:  b7e2b586c1 < -:  ---------- doc: add information regarding external commands
 -:  ---------- > 1:  02841b66ea doc: add information regarding external commands


 Documentation/git.adoc | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index ce099e78b8..8bb3cb53f5 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
+    name are passed as-is to the runnable program. These commands precedes
+	alias expansion.
+
 The Git Repository
 ~~~~~~~~~~~~~~~~~~
 These environment variables apply to 'all' core Git commands. Nb: it

base-commit: 2cc71917514657b93014134350864f4849edfc83
-- 
gitgitgadget

[PATCH v3] doc: add information regarding external commands

[Omri Sarig via GitGitGadget]

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.
This commit adds a short documentation of this feature, making it easier
for users to discover and use.

Signed-off-by: Omri Sarig <omri.sarig13@gmail.com>
---
    doc: Add information regarding external commands
    
     * Patchset V2 have spaces instead of tabs in one of the lines, it is
       fixed in patchset V3.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v3
Pull-Request: https://github.com/git/git/pull/2220

Range-diff vs v2:

 1:  02841b66ea ! 1:  f90ad791d5 doc: add information regarding external commands
     @@ Documentation/git.adoc: System
      +	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
     -+    name are passed as-is to the runnable program. These commands precedes
     ++	name are passed as-is to the runnable program. These commands precedes
      +	alias expansion.
      +
       The Git Repository


 Documentation/git.adoc | 7 +++++++
 1 file changed, 7 insertions(+)

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
+	name are passed as-is to the runnable program. These commands precedes
+	alias expansion.
+
 The Git Repository
 ~~~~~~~~~~~~~~~~~~
 These environment variables apply to 'all' core Git commands. Nb: it

base-commit: 2cc71917514657b93014134350864f4849edfc83
-- 
gitgitgadget

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

[Junio C Hamano]

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

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

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

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

[D. Ben Knoble]

On Tue, Mar 3, 2026 at 1:40 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> 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)
>  -------------------------------

I very much like that, thanks.

-- 
D. Ben Knoble

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

[Omri Sarig]

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 <gitster@pobox.com> wrote:
>
> "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.

Understood, I'll fix accordingly.

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

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?

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

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

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

[Junio C Hamano]

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.

[PATCH v4] doc: add information regarding external commands

[Omri Sarig via GitGitGadget]

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.

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

Signed-off-by: Omri Sarig <omri.sarig13@gmail.com>
---
    doc: Add information regarding external commands
    
     * Patchset V2 have spaces instead of tabs in one of the lines, it is
       fixed in patchset V3.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v4
Pull-Request: https://github.com/git/git/pull/2220

Range-diff vs v3:

 1:  f90ad791d5 ! 1:  516ad65d8d doc: add information regarding external commands
     @@ Commit message
      
          This feature was not fully documented in Git's user-facing
          documentation.
     -    This commit adds a short documentation of this feature, making it easier
     -    for users to discover and use.
     +
     +    Add a short documentation to describe how PATH is used to find a custom
     +    subcommand.
      
          Signed-off-by: Omri Sarig <omri.sarig13@gmail.com>
      
     @@ Documentation/git.adoc: System
      +	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
     -+	name are passed as-is to the runnable program. These commands precedes
     -+	alias expansion.
     ++	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.
      +
       The Git Repository
       ~~~~~~~~~~~~~~~~~~


 Documentation/git.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index ce099e78b8..9c2a8978c7 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc
@@ -487,6 +487,14 @@ 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
+	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.
+
 The Git Repository
 ~~~~~~~~~~~~~~~~~~
 These environment variables apply to 'all' core Git commands. Nb: it

base-commit: 2cc71917514657b93014134350864f4849edfc83
-- 
gitgitgadget