[PATCH] git(1): Define "porcelain commands"

[PATCH] git(1): Define "porcelain commands"

[Bagas Sanjaya]

The description before list of porcelain commands doesn't tell what
"porcelain" term is, nor the accurate categorization (because it only
says that such commands are divided into main and ancillary commands,
although there are also tools for interacting with others and trio
reset-restore-revert).

Define the term and say the proper categorization in the description
paragraph.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/git.txt | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 6dd241ef83..fb6d7d860d 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -221,8 +221,14 @@ We divide Git into high level ("porcelain") commands and low level
 High-level commands (porcelain)
 -------------------------------
 
-We separate the porcelain commands into the main commands and some
-ancillary user utilities.
+Porcelain commands are user-facing, high level command interface of
+Git. These are built from plumbing commands and expose SCM interface
+and human-friendly output. Most users run only porcelains unless they
+have absolute necessity for plumbing commands (e.g. scripting).
+
+The following description divides porcelain commands into main
+commands, ancillary utilities, tools for interacting with foreign SCM
+and email, and similarly-named commands for reverting changes.
 
 Main porcelain commands
 ~~~~~~~~~~~~~~~~~~~~~~~

base-commit: 99c99ed8259bf070cd8ae7b51a94904b7cf5c161
-- 
2.25.1

Re: [PATCH] git(1): Define "porcelain commands"

[Junio C Hamano]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> The description before list of porcelain commands doesn't tell what
> "porcelain" term is, nor the accurate categorization (because it only
> says that such commands are divided into main and ancillary commands,
> although there are also tools for interacting with others and trio
> reset-restore-revert).
>
> Define the term and say the proper categorization in the description
> paragraph.
>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/git.txt | 10 ++++++++--
>  1 file changed, 8 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 6dd241ef83..fb6d7d860d 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -221,8 +221,14 @@ We divide Git into high level ("porcelain") commands and low level
>  High-level commands (porcelain)
>  -------------------------------
>  
> -We separate the porcelain commands into the main commands and some
> -ancillary user utilities.
> +Porcelain commands are user-facing, high level command interface of
> +Git. These are built from plumbing commands and expose SCM interface
> +and human-friendly output. Most users run only porcelains unless they
> +have absolute necessity for plumbing commands (e.g. scripting).

Before this section, we briefly mention that we have two classes of
commands (high level "porcelain" and low level "plumbing").  It is
certainly a good idea to have additional clarification on what "high
level" and "low level" mean and how they differ, but most of the new
material should go to the preamble before this paragraph, I would
think.

Also, the phrasing to describe criteria to choose between them needs
careful rewriting.  These two classes of commands serve different
purposes.  The "high level" ones are meant for end-user interaction,
where DWIMmery and short-cuts for human convenience outweigh, while
the "low level" ones aim more for predictability to help their use
in scripts.  The choice certainly would *not* be "unless absolutely
necessary, use Porcelain even for scripting".  Porcelain commands
are designed for interactive use, plumbing are designed for
scripting.  It is more like "script with plumbing---you can use
Porcelain in your scripts when it is absolutely necessary, but be
prepared that future changes to Porcelain may break your scripts and
do not come back to us with complaints---Porcelain can change in a
way that will help human interactive users."

> +The following description divides porcelain commands into main
> +commands, ancillary utilities, tools for interacting with foreign SCM
> +and email, and similarly-named commands for reverting changes.

While a finer grained categorization like the above may not be a bad
idea, I have not formed an opinion if the above one is what we
want (especially I am not sure about singling out "reverting
changes", both as a category and as a characterization).

Thanks.