| Message ID | 20210925122228.1090901-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git(1): Define "porcelain commands" | expand |
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.
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 ~~~~~~~~~~~~~~~~~~~~~~~
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(-) base-commit: 99c99ed8259bf070cd8ae7b51a94904b7cf5c161