{"thread":{"id":"65123","subject":"[PATCH] doc: add information regarding external commands","startedAt":"2026-03-02T19:31:49Z","lastAt":"2026-03-04T15:03:37Z","messageCount":10,"participants":["Omri Sarig via GitGitGadget","Junio C Hamano","Omri Sarig","D. Ben Knoble"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"537594","messageId":"pull.2220.git.git.1772479907062.gitgitgadget@gmail.com","threadId":"65123","inReplyTo":null,"subject":"[PATCH] doc: add information regarding external commands","fromName":"Omri Sarig via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-03-02T19:31:47Z","receivedAt":"2026-03-02T19:31:49Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"From: Omri Sarig \n\nGit supports running external commands in the user's PATH as if they\nwere built-in commands (see execv_dashed_external in git.c).\n\nThis feature was not documented in any of Git's user-facing\ndocumentation.\nThis commit adds a short documentation of this feature, making it easier\nfor users to discover and use.\n\nSigned-off-by: Omri Sarig \n---\n doc: Add information regarding external commands\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v1\nPull-Request: https://github.com/git/git/pull/2220\n\n Documentation/git.adoc | 18 ++++++++++++++++++\n 1 file changed, 18 insertions(+)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..da7c1329da 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -345,6 +345,24 @@ users typically do not use them directly.\n \n include::{build_dir}/cmds-purehelpers.adoc[]\n \n+External commands\n+-----------------\n+\n+In addition to the commands implemented by Git, Git will execute any executable\n+with the prefix \"git-\" in the user path as if it is a Git command.\n+\n+All parameters of the invocation are passed to the script, making running \"git\n+foo arg1 arg2\" equivalent to running \"git-foo arg1 arg2\". When running \"git\n+help\" with the command name, Git will invoke the man page for the given\n+command, making running \"git help foo\" equivalent to running \"man git-foo\".\n+\n+This makes it possible to extend Git with custom commands, without the need to\n+change its source code.\n+\n+Git looks for external commands after looking for built-in commands, but before\n+looking for aliases. Therefore, if an external command have the same name as an\n+alias, it'll run instead of the alias.\n+\n Guides\n ------\n \n\nbase-commit: 2cc71917514657b93014134350864f4849edfc83\n-- \ngitgitgadget\n"},{"id":"537627","messageId":"xmqqqzq1x2lp.fsf@gitster.g","threadId":"65123","inReplyTo":"pull.2220.git.git.1772479907062.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add information regarding external commands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-02T22:56:18Z","receivedAt":"2026-03-02T22:56:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Omri Sarig via GitGitGadget\" writes:\n\n> From: Omri Sarig \n>\n> Git supports running external commands in the user's PATH as if they\n> were built-in commands (see execv_dashed_external in git.c).\n\nCorrect.\n\n> This feature was not documented in any of Git's user-facing\n> documentation.\n\n\"Not documented in any\" is a slight exaggeration. See \"git help\ngit\" and look at description of \"--list-cmds\" option; \"all commands\nin $PATH that have git- prefix\" is mentioned there. Also \"git help\nhelp\" talks about \"--no-external-commands\" that excludes \"git-*\"\ncommands found on $PATH from the listing, which implies these things\ncount as available commands.\n\nNevertheless, it is a good idea to make it more discoverable.\n\n> This commit adds a short documentation of this feature, making it easier\n> for users to discover and use.\n\nI would have expected that under Environment Variables > System,\nnext to HOME, we would add an entry for PATH that says something\nlike:\n\n When a user runs 'git ' that is not part of the core\n Git programs (installed in GIT_EXEC_PATH), 'git-' that\n is runnable by the user in a directory on `$PATH` is invoked.\n\n\nor something like that; I didn't expect us to add a dedicated\nseparate section for it.\n\nThanks.\n\n"},{"id":"537697","messageId":"CAP9es6vwDccuY_NC+q=ua7u-cwORV4-eLhPf3dPDrBf+JkAT0Q@mail.gmail.com","threadId":"65123","inReplyTo":"xmqqqzq1x2lp.fsf@gitster.g","subject":"Re: [PATCH] doc: add information regarding external commands","fromName":"Omri Sarig","fromEmail":"omri.sarig13@gmail.com","sentAt":"2026-03-03T17:07:20Z","receivedAt":"2026-03-03T17:07:33Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"Thank you for the reply and review - a fixed patch V2 is incoming shortly.\n\nOn Mon, Mar 2, 2026 at 11:56 PM Junio C Hamano wrote:\n>\n> \"Omri Sarig via GitGitGadget\" writes:\n>\n> > From: Omri Sarig \n> >\n> > Git supports running external commands in the user's PATH as if they\n> > were built-in commands (see execv_dashed_external in git.c).\n>\n> Correct.\n>\n> > This feature was not documented in any of Git's user-facing\n> > documentation.\n>\n> \"Not documented in any\" is a slight exaggeration. See \"git help\n> git\" and look at description of \"--list-cmds\" option; \"all commands\n> in $PATH that have git- prefix\" is mentioned there. Also \"git help\n> help\" talks about \"--no-external-commands\" that excludes \"git-*\"\n> commands found on $PATH from the listing, which implies these things\n> count as available commands.\n>\n> Nevertheless, it is a good idea to make it more discoverable.\n>\n> > This commit adds a short documentation of this feature, making it easier\n> > for users to discover and use.\n>\n> I would have expected that under Environment Variables > System,\n> next to HOME, we would add an entry for PATH that says something\n> like:\n>\n> When a user runs 'git ' that is not part of the core\n> Git programs (installed in GIT_EXEC_PATH), 'git-' that\n> is runnable by the user in a directory on `$PATH` is invoked.\n>\n>\n> or something like that; I didn't expect us to add a dedicated\n> separate section for it.\n\nI've added this now as you suggest. I made it slightly more verbose (adding\ninformation about the arguments for the commands, and about it taking\nprecedence over aliases). If you want it to be shorter again, let me know and\nI'll remove this information.\n\n>\n> Thanks.\n>\n\nWith Kind Regards,\nOmri\n"},{"id":"537698","messageId":"pull.2220.v2.git.git.1772557925670.gitgitgadget@gmail.com","threadId":"65123","inReplyTo":"pull.2220.git.git.1772479907062.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: add information regarding external commands","fromName":"Omri Sarig via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-03-03T17:12:05Z","receivedAt":"2026-03-03T17:12:08Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"From: Omri Sarig \n\nGit supports running external commands in the user's PATH as if they\nwere built-in commands (see execv_dashed_external in git.c).\n\nThis feature was not fully documented in Git's user-facing\ndocumentation.\nThis commit adds a short documentation of this feature, making it easier\nfor users to discover and use.\n\nSigned-off-by: Omri Sarig \n---\n doc: Add information regarding external commands\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v2\nPull-Request: https://github.com/git/git/pull/2220\n\nRange-diff vs v1:\n\n 1: b7e2b586c1 < -: ---------- doc: add information regarding external commands\n -: ---------- > 1: 02841b66ea doc: add information regarding external commands\n\n\n Documentation/git.adoc | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..8bb3cb53f5 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -487,6 +487,13 @@ System\n \t`$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist;\n \totherwise `$USERPROFILE` if `$USERPROFILE` exists.\n \n+`PATH`::\n+\tWhen a user runs 'git ' that is not part of the core Git programs\n+\t(installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n+\tin a directory on `$PATH` is invoked. Argument passed after the command\n+ name are passed as-is to the runnable program. These commands precedes\n+\talias expansion.\n+\n The Git Repository\n ~~~~~~~~~~~~~~~~~~\n These environment variables apply to 'all' core Git commands. Nb: it\n\nbase-commit: 2cc71917514657b93014134350864f4849edfc83\n-- \ngitgitgadget\n"},{"id":"537705","messageId":"pull.2220.v3.git.git.1772559813151.gitgitgadget@gmail.com","threadId":"65123","inReplyTo":"pull.2220.v2.git.git.1772557925670.gitgitgadget@gmail.com","subject":"[PATCH v3] doc: add information regarding external commands","fromName":"Omri Sarig via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-03-03T17:43:33Z","receivedAt":"2026-03-03T17:43:37Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"From: Omri Sarig \n\nGit supports running external commands in the user's PATH as if they\nwere built-in commands (see execv_dashed_external in git.c).\n\nThis feature was not fully documented in Git's user-facing\ndocumentation.\nThis commit adds a short documentation of this feature, making it easier\nfor users to discover and use.\n\nSigned-off-by: Omri Sarig \n---\n doc: Add information regarding external commands\n \n * Patchset V2 have spaces instead of tabs in one of the lines, it is\n fixed in patchset V3.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v3\nPull-Request: https://github.com/git/git/pull/2220\n\nRange-diff vs v2:\n\n 1: 02841b66ea ! 1: f90ad791d5 doc: add information regarding external commands\n @@ Documentation/git.adoc: System\n +\tWhen a user runs 'git ' that is not part of the core Git programs\n +\t(installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n +\tin a directory on `$PATH` is invoked. Argument passed after the command\n -+ name are passed as-is to the runnable program. These commands precedes\n ++\tname are passed as-is to the runnable program. These commands precedes\n +\talias expansion.\n +\n The Git Repository\n\n\n Documentation/git.adoc | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..903d11c530 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -487,6 +487,13 @@ System\n \t`$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist;\n \totherwise `$USERPROFILE` if `$USERPROFILE` exists.\n \n+`PATH`::\n+\tWhen a user runs 'git ' that is not part of the core Git programs\n+\t(installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n+\tin a directory on `$PATH` is invoked. Argument passed after the command\n+\tname are passed as-is to the runnable program. These commands precedes\n+\talias expansion.\n+\n The Git Repository\n ~~~~~~~~~~~~~~~~~~\n These environment variables apply to 'all' core Git commands. Nb: it\n\nbase-commit: 2cc71917514657b93014134350864f4849edfc83\n-- \ngitgitgadget\n"},{"id":"537714","messageId":"xmqqh5qwdaeh.fsf@gitster.g","threadId":"65123","inReplyTo":"pull.2220.v3.git.git.1772559813151.gitgitgadget@gmail.com","subject":"Re: [PATCH v3] doc: add information regarding external commands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-03T18:40:22Z","receivedAt":"2026-03-03T18:40:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Omri Sarig via GitGitGadget\" writes:\n\nThanks. Almost there.\n\nThe usual way to compose a log message of this project is to\n\n - Give an observation on how the current system works in the\n present tense (so no need to say \"Currently X is Y\", or\n \"Previously X was Y\" to describe the state before your change;\n just \"X is Y\" is enough), and discuss what you perceive as a\n problem in it.\n\n - Propose a solution (optional---often, problem description\n trivially leads to an obvious solution in reader's minds).\n\n - Give commands to somebody editing the codebase to \"make it so\",\n instead of saying \"This commit does X\".\n\nin this order.\n\n> From: Omri Sarig \n>\n> Git supports running external commands in the user's PATH as if they\n> were built-in commands (see execv_dashed_external in git.c).\n>\n> This feature was not fully documented in Git's user-facing\n> documentation.\n\nYour description of the problem above is excellent.\n\n> This commit adds a short documentation of this feature, making it easier\n> for users to discover and use.\n\nThere is nothing incorrect in the above, but we would write it more\nlike\n\n Add a short documentation to describe how PATH is used to find a\n custom subcommand.\n\n> Signed-off-by: Omri Sarig \n\n> diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n> index ce099e78b8..903d11c530 100644\n> --- a/Documentation/git.adoc\n> +++ b/Documentation/git.adoc\n> @@ -487,6 +487,13 @@ System\n> \t`$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist;\n> \totherwise `$USERPROFILE` if `$USERPROFILE` exists.\n> \n> +`PATH`::\n> +\tWhen a user runs 'git ' that is not part of the core Git programs\n> +\t(installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n> +\tin a directory on `$PATH` is invoked. Argument passed after the command\n\nOK.\n\n> +\tname are passed as-is to the runnable program. These commands precedes\n> +\talias expansion.\n\nWe are not going to try running a program that is not runnable\nanyway, so \"the runnable program\" -> \"the program\", probably?\n\nI am not sure what the last sentence wants to say, especially the\n\"alias expansion\" part. Do you mean that your \"git foo\" alias (not\njust its expansion but its presence as a whole) is ignored if you\nhave a \"git-foo\" program on your $PATH?\n\nSpeaking of \"alias\", I have always felt that it was suboptimal to\nmake users refer to \"git help config\" to find out about it. I\nwonder if \"git help git\" should be the first place users would look\nfor a help about them?\n\nWe have \"GIT COMMANDS\" section in \"git help git\" that says \"We\ndivide GIt into porcelain and plumbing\" and then have two\nsubsections there that list commands that belong to these two\ncategories. Perhaps leaving some breadcrumbs to redirect them would\nbe a good start, something like this?\n\n Documentation/git.adoc | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git c/Documentation/git.adoc w/Documentation/git.adoc\nindex ce099e78b8..fb5b477eda 100644\n--- c/Documentation/git.adoc\n+++ w/Documentation/git.adoc\n@@ -235,7 +235,10 @@ GIT COMMANDS\n ------------\n \n We divide Git into high level (\"porcelain\") commands and low level\n-(\"plumbing\") commands.\n+(\"plumbing\") commands. For defining command aliases, see\n+linkgit:gitconfig[1] and look for descriptions of `alias.*`.\n+For installing custom \"git\" subcommands, see the description for\n+the 'PATH' environment variable in this manual.\n \n High-level commands (porcelain)\n -------------------------------\n"},{"id":"537719","messageId":"CALnO6CASi3eyf_Zn1RS_Atjm6hj6Vnq0nNNyV8JJFCAK7hz0rg@mail.gmail.com","threadId":"65123","inReplyTo":"xmqqh5qwdaeh.fsf@gitster.g","subject":"Re: [PATCH v3] doc: add information regarding external commands","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-03-03T18:48:54Z","receivedAt":"2026-03-03T18:49:06Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Mar 3, 2026 at 1:40 PM Junio C Hamano wrote:\n>\n> Speaking of \"alias\", I have always felt that it was suboptimal to\n> make users refer to \"git help config\" to find out about it. I\n> wonder if \"git help git\" should be the first place users would look\n> for a help about them?\n>\n> We have \"GIT COMMANDS\" section in \"git help git\" that says \"We\n> divide GIt into porcelain and plumbing\" and then have two\n> subsections there that list commands that belong to these two\n> categories. Perhaps leaving some breadcrumbs to redirect them would\n> be a good start, something like this?\n>\n> Documentation/git.adoc | 5 ++++-\n> 1 file changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git c/Documentation/git.adoc w/Documentation/git.adoc\n> index ce099e78b8..fb5b477eda 100644\n> --- c/Documentation/git.adoc\n> +++ w/Documentation/git.adoc\n> @@ -235,7 +235,10 @@ GIT COMMANDS\n> ------------\n>\n> We divide Git into high level (\"porcelain\") commands and low level\n> -(\"plumbing\") commands.\n> +(\"plumbing\") commands. For defining command aliases, see\n> +linkgit:gitconfig[1] and look for descriptions of `alias.*`.\n> +For installing custom \"git\" subcommands, see the description for\n> +the 'PATH' environment variable in this manual.\n>\n> High-level commands (porcelain)\n> -------------------------------\n\nI very much like that, thanks.\n\n-- \nD. Ben Knoble\n"},{"id":"537728","messageId":"CAP9es6uT4xE2+h6mCXgYVcibutVOah1xKyS8cKaV1u=VHBpLZw@mail.gmail.com","threadId":"65123","inReplyTo":"xmqqh5qwdaeh.fsf@gitster.g","subject":"Re: [PATCH v3] doc: add information regarding external commands","fromName":"Omri Sarig","fromEmail":"omri.sarig13@gmail.com","sentAt":"2026-03-03T20:11:13Z","receivedAt":"2026-03-03T20:11:25Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"Thanks for the help!\n\nI fully understand this is something you can just do in a few minutes, so I\nreally appreciate the support and the welcoming attitude.\n\nOn Tue, Mar 3, 2026 at 7:40 PM Junio C Hamano wrote:\n>\n> \"Omri Sarig via GitGitGadget\" writes:\n>\n> Thanks. Almost there.\n>\n> The usual way to compose a log message of this project is to\n>\n> - Give an observation on how the current system works in the\n> present tense (so no need to say \"Currently X is Y\", or\n> \"Previously X was Y\" to describe the state before your change;\n> just \"X is Y\" is enough), and discuss what you perceive as a\n> problem in it.\n>\n> - Propose a solution (optional---often, problem description\n> trivially leads to an obvious solution in reader's minds).\n>\n> - Give commands to somebody editing the codebase to \"make it so\",\n> instead of saying \"This commit does X\".\n>\n> in this order.\n\nUnderstood, I'll fix accordingly.\n\n>\n> > From: Omri Sarig \n> >\n> > Git supports running external commands in the user's PATH as if they\n> > were built-in commands (see execv_dashed_external in git.c).\n> >\n> > This feature was not fully documented in Git's user-facing\n> > documentation.\n>\n> Your description of the problem above is excellent.\n>\n> > This commit adds a short documentation of this feature, making it easier\n> > for users to discover and use.\n>\n> There is nothing incorrect in the above, but we would write it more\n> like\n>\n> Add a short documentation to describe how PATH is used to find a\n> custom subcommand.\n>\n> > Signed-off-by: Omri Sarig \n>\n> > diff --git a/Documentation/git.adoc b/Documentation/git.adoc\n> > index ce099e78b8..903d11c530 100644\n> > --- a/Documentation/git.adoc\n> > +++ b/Documentation/git.adoc\n> > @@ -487,6 +487,13 @@ System\n> > `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist;\n> > otherwise `$USERPROFILE` if `$USERPROFILE` exists.\n> >\n> > +`PATH`::\n> > + When a user runs 'git ' that is not part of the core Git programs\n> > + (installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n> > + in a directory on `$PATH` is invoked. Argument passed after the command\n>\n> OK.\n>\n> > + name are passed as-is to the runnable program. These commands precedes\n> > + alias expansion.\n>\n> We are not going to try running a program that is not runnable\n> anyway, so \"the runnable program\" -> \"the program\", probably?\n\nCompletely agree, will fix.\n\n> I am not sure what the last sentence wants to say, especially the\n> \"alias expansion\" part. Do you mean that your \"git foo\" alias (not\n> just its expansion but its presence as a whole) is ignored if you\n> have a \"git-foo\" program on your $PATH?\n\nThis is exactly what I tried to write there.\nPersonally, I had expected aliases to take precedence over external commands,\nso I was surprised to see that it is reversed (so the program \"git-foo\" runs\nbefore Git looks for the alias \"git foo\"). I thought it'll make sense to\nmention in the documentation, to save possible headaches for future developers.\n\nI'm not sure it's too much information, or should just be described better?\n\nMaybe adding a second paragraph with something like this can be clearer:\n\n External commands precedes aliases. For example, running \"git foo\" will\n execute \"git-foo\" from PATH; only if \"git-foo\" does not exist, will Git\n look for the alias \"foo\".\n\nWhat do you think?\n\n> Speaking of \"alias\", I have always felt that it was suboptimal to\n> make users refer to \"git help config\" to find out about it. I\n> wonder if \"git help git\" should be the first place users would look\n> for a help about them?\n>\n> We have \"GIT COMMANDS\" section in \"git help git\" that says \"We\n> divide GIt into porcelain and plumbing\" and then have two\n> subsections there that list commands that belong to these two\n> categories. Perhaps leaving some breadcrumbs to redirect them would\n> be a good start, something like this?\n>\n> Documentation/git.adoc | 5 ++++-\n> 1 file changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git c/Documentation/git.adoc w/Documentation/git.adoc\n> index ce099e78b8..fb5b477eda 100644\n> --- c/Documentation/git.adoc\n> +++ w/Documentation/git.adoc\n> @@ -235,7 +235,10 @@ GIT COMMANDS\n> ------------\n>\n> We divide Git into high level (\"porcelain\") commands and low level\n> -(\"plumbing\") commands.\n> +(\"plumbing\") commands. For defining command aliases, see\n> +linkgit:gitconfig[1] and look for descriptions of `alias.*`.\n> +For installing custom \"git\" subcommands, see the description for\n> +the 'PATH' environment variable in this manual.\n>\n> High-level commands (porcelain)\n> -------------------------------\n\nI agree - that makes good sense to me too.\n\nDo you see it as belonging in the same commit, or in a subsequent commit? I'm\nnot fully clear about the rules for splitting such commits in the repo.\n\nThanks,\nWith Kind Regards,\nOmri\n"},{"id":"537729","messageId":"xmqqy0k8bqgs.fsf@gitster.g","threadId":"65123","inReplyTo":"CAP9es6uT4xE2+h6mCXgYVcibutVOah1xKyS8cKaV1u=VHBpLZw@mail.gmail.com","subject":"Re: [PATCH v3] doc: add information regarding external commands","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-03T20:36:19Z","receivedAt":"2026-03-03T20:36:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Omri Sarig writes:\n\n>> I am not sure what the last sentence wants to say, especially the\n>> \"alias expansion\" part. Do you mean that your \"git foo\" alias (not\n>> just its expansion but its presence as a whole) is ignored if you\n>> have a \"git-foo\" program on your $PATH?\n>\n> This is exactly what I tried to write there.\n> Personally, I had expected aliases to take precedence over external commands,\n> so I was surprised to see that it is reversed (so the program \"git-foo\" runs\n> before Git looks for the alias \"git foo\"). I thought it'll make sense to\n> mention in the documentation, to save possible headaches for future developers.\n>\n> I'm not sure it's too much information, or should just be described better?\n\nThe latter.\n\nWe hear \"X takes precedence over Y\" more often when we describe the\nrelationship between commands and aliases. I do not think we use\nverb \"X precedes Y\" in our documentation to indicate that\nrelationship. We do see the verb used for \"X comes before Y\" in\nmany places in our documentation, though.\n\nHere is my attempt.\n\n ... Argument passed after the command name are passed as-is to\n the program. To execute `git `, `git` finds command\n `` (either a core Git program found in 'GIT_EXEC_PATH', or\n a custom one in a directory on 'PATH'), before trying `foo` as\n an alias.\n\n>> We divide Git into high level (\"porcelain\") commands and low level\n>> -(\"plumbing\") commands.\n>> +(\"plumbing\") commands. For defining command aliases, see\n>> +linkgit:gitconfig[1] and look for descriptions of `alias.*`.\n>> +For installing custom \"git\" subcommands, see the description for\n>> +the 'PATH' environment variable in this manual.\n>>\n>> High-level commands (porcelain)\n>> -------------------------------\n>\n> I agree - that makes good sense to me too.\n>\n> Do you see it as belonging in the same commit, or in a subsequent commit?\n\nTotally outside of your topic. Let's concentrate on the PATH thing\nand finish it first.\n\nThanks.\n\n"},{"id":"537784","messageId":"pull.2220.v4.git.git.1772636614850.gitgitgadget@gmail.com","threadId":"65123","inReplyTo":"pull.2220.v3.git.git.1772559813151.gitgitgadget@gmail.com","subject":"[PATCH v4] doc: add information regarding external commands","fromName":"Omri Sarig via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-03-04T15:03:34Z","receivedAt":"2026-03-04T15:03:37Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"From: Omri Sarig \n\nGit supports running external commands in the user's PATH as if they\nwere built-in commands (see execv_dashed_external in git.c).\n\nThis feature was not fully documented in Git's user-facing\ndocumentation.\n\nAdd a short documentation to describe how PATH is used to find a custom\nsubcommand.\n\nSigned-off-by: Omri Sarig \n---\n doc: Add information regarding external commands\n \n * Patchset V2 have spaces instead of tabs in one of the lines, it is\n fixed in patchset V3.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2220%2Fomrisarig13%2Fexternal-commands-documentation-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2220/omrisarig13/external-commands-documentation-v4\nPull-Request: https://github.com/git/git/pull/2220\n\nRange-diff vs v3:\n\n 1: f90ad791d5 ! 1: 516ad65d8d doc: add information regarding external commands\n @@ Commit message\n \n This feature was not fully documented in Git's user-facing\n documentation.\n - This commit adds a short documentation of this feature, making it easier\n - for users to discover and use.\n +\n + Add a short documentation to describe how PATH is used to find a custom\n + subcommand.\n \n Signed-off-by: Omri Sarig \n \n @@ Documentation/git.adoc: System\n +\tWhen a user runs 'git ' that is not part of the core Git programs\n +\t(installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n +\tin a directory on `$PATH` is invoked. Argument passed after the command\n -+\tname are passed as-is to the runnable program. These commands precedes\n -+\talias expansion.\n ++\tname are passed as-is to the program. To execute `git `, `git` finds\n ++\tcommand `` (either a core Git program found in 'GIT_EXEC_PATH', or a\n ++\tcustom one in a directory on 'PATH'), before trying `foo` as an alias.\n +\n The Git Repository\n ~~~~~~~~~~~~~~~~~~\n\n\n Documentation/git.adoc | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex ce099e78b8..9c2a8978c7 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -487,6 +487,14 @@ System\n \t`$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist;\n \totherwise `$USERPROFILE` if `$USERPROFILE` exists.\n \n+`PATH`::\n+\tWhen a user runs 'git ' that is not part of the core Git programs\n+\t(installed in GIT_EXEC_PATH), 'git-' that is runnable by the user\n+\tin a directory on `$PATH` is invoked. Argument passed after the command\n+\tname are passed as-is to the program. To execute `git `, `git` finds\n+\tcommand `` (either a core Git program found in 'GIT_EXEC_PATH', or a\n+\tcustom one in a directory on 'PATH'), before trying `foo` as an alias.\n+\n The Git Repository\n ~~~~~~~~~~~~~~~~~~\n These environment variables apply to 'all' core Git commands. Nb: it\n\nbase-commit: 2cc71917514657b93014134350864f4849edfc83\n-- \ngitgitgadget\n"}]}