[PATCH v4] doc: add information regarding external commands

From: Omri Sarig via GitGitGadget <gitgitgadget@gmail.com>
Date: Mar 4, 2026, 15:03 UTC
Message-ID: <pull.2220.v4.git.git.1772636614850.gitgitgadget@gmail.com>
In-Reply-To: <pull.2220.v3.git.git.1772559813151.gitgitgadget@gmail.com>

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