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

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

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