doc: add information regarding external commands

PATCH Superseded Omri Sarig via GitGitGadget 4 participants 10 messages Mar 2 – Mar 4 Documentation

lore

Share & tools

lore

Omri Sarig via GitGitGadget

author

2026-03-02 19:31 UTC #0 lore raw

PATCH 1/1 doc: add information regarding external commands

From: Omri Sarig <[email protected]>

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 <[email protected]>

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

Documentation/git.adoc +18 -0

index ce099e78b8..da7c1329da 100644
@@ -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

Signature · 1 line

gitgitgadget

Junio C Hamano

2026-03-02 22:56 UTC #1 lore raw

Quoted 4 lines · Omri Sarig via GitGitGadget

From: Omri Sarig <[email protected]>
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.

Quoted 2 lines

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.

Quoted 2 lines

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.

Omri Sarig

2026-03-03 17:07 UTC #2 lore raw

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

Quoted 29 lines · Junio C Hamano

Quoted 4 lines · Omri Sarig via GitGitGadget
From: Omri Sarig <[email protected]>
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.
Quoted 2 lines
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.
Quoted 2 lines
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:

Quoted 7 lines

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.

Quoted 3 lines

Thanks.

With Kind Regards,
Omri

Omri Sarig via GitGitGadget

author

2026-03-03 17:12 UTC #3 lore raw

PATCH v2 1/1 doc: add information regarding external commands

In reply to Omri Sarig via GitGitGadget

From: Omri Sarig <[email protected]>

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 <[email protected]>

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

Documentation/git.adoc +7 -0

index ce099e78b8..8bb3cb53f5 100644
@@ -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

Signature · 1 line

gitgitgadget

Omri Sarig via GitGitGadget

author

2026-03-03 17:43 UTC #4 lore raw

PATCH v3 1/1 doc: add information regarding external commands

From: Omri Sarig <[email protected]>

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 <[email protected]>

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

Documentation/git.adoc +7 -0

index ce099e78b8..903d11c530 100644
@@ -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

Signature · 1 line

gitgitgadget

Junio C Hamano

2026-03-03 18:40 UTC #5 lore raw

"Omri Sarig via GitGitGadget" <[email protected]> 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.

Quoted 7 lines

From: Omri Sarig <[email protected]>
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 2 lines

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

Signed-off-by Omri Sarig <[email protected]>
Documentation/git.adoc +0 -0
index ce099e78b8..903d11c530 100644

Documentation/git.adoc System · line 493

Quoted 7 lines

Documentation/git.adoc +4 -0

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

Documentation/git.adoc System · line 495

Quoted 2 lines

Documentation/git.adoc +2 -0

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

Documentation/git.adoc +4 -1

index ce099e78b8..fb5b477eda 100644
@@ -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)
 -------------------------------

D. Ben Knoble

2026-03-03 18:49 UTC #6 lore raw

Quoted 21 lines · Junio C Hamano

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(-)
Documentation/git.adoc +0 -0
index ce099e78b8..fb5b477eda 100644
@@ -235,7 +235,10 @@ GIT COMMANDS
 ------------

Documentation/git.adoc GIT COMMANDS · line 244

Quoted 10 lines

Documentation/git.adoc +4 -1

 
 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.

Signature · 1 line

D. Ben Knoble

Omri Sarig

2026-03-03 20:11 UTC #7 lore raw

In reply to Junio C Hamano

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.

Quoted 13 lines · Junio C Hamano

"Omri Sarig via GitGitGadget" <[email protected]> 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.

Quoted 7 lines

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

Quoted 8 lines
From: Omri Sarig <[email protected]>
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 2 lines
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 7 lines
Signed-off-by Omri Sarig <[email protected]>
Documentation/git.adoc +0 -0
index ce099e78b8..903d11c530 100644
Documentation/git.adoc System · line 493
Quoted 7 lines
Documentation/git.adoc +4 -0
@@ -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 5 lines

Documentation/git.adoc System · line 495
Quoted 2 lines
Documentation/git.adoc +2 -0
+     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.

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

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?

Quoted 20 lines

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(-)
Documentation/git.adoc +0 -0
index ce099e78b8..fb5b477eda 100644
@@ -235,7 +235,10 @@ GIT COMMANDS
 ------------

Documentation/git.adoc GIT COMMANDS · line 244

Quoted 10 lines

Documentation/git.adoc +4 -1

 
 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

Junio C Hamano

2026-03-03 20:36 UTC #8 lore raw

Quoted 5 lines · Omri Sarig

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

Quoted 7 lines

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.

Quoted 7 lines

We divide Git into high level ("porcelain") commands and low level

Documentation/git.adoc +4 -1

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

Quoted 6 lines

Quoted 2 lines
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.

Omri Sarig via GitGitGadget

author

2026-03-04 15:03 UTC #9 lore raw

PATCH v4 1/1 doc: add information regarding external commands

In reply to Omri Sarig via GitGitGadget

From: Omri Sarig <[email protected]>

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 <[email protected]>

---
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 <[email protected]>

@@ 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(+)

Documentation/git.adoc +8 -0

index ce099e78b8..9c2a8978c7 100644
@@ -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

Signature · 1 line

gitgitgadget