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

[Junio C Hamano <gitster@pobox.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.

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