{"thread":{"id":"56587","subject":"[PATCH] git(1): Define \"porcelain commands\"","startedAt":"2021-09-25T12:22:58Z","lastAt":"2021-09-25T16:37:05Z","messageCount":2,"participants":["Bagas Sanjaya","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"437071","messageId":"20210925122228.1090901-1-bagasdotme@gmail.com","threadId":"56587","inReplyTo":null,"subject":"[PATCH] git(1): Define \"porcelain commands\"","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-25T12:22:29Z","receivedAt":"2021-09-25T12:22:58Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"The description before list of porcelain commands doesn't tell what\n\"porcelain\" term is, nor the accurate categorization (because it only\nsays that such commands are divided into main and ancillary commands,\nalthough there are also tools for interacting with others and trio\nreset-restore-revert).\n\nDefine the term and say the proper categorization in the description\nparagraph.\n\nSigned-off-by: Bagas Sanjaya \n---\n Documentation/git.txt | 10 ++++++++--\n 1 file changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 6dd241ef83..fb6d7d860d 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -221,8 +221,14 @@ We divide Git into high level (\"porcelain\") commands and low level\n High-level commands (porcelain)\n -------------------------------\n \n-We separate the porcelain commands into the main commands and some\n-ancillary user utilities.\n+Porcelain commands are user-facing, high level command interface of\n+Git. These are built from plumbing commands and expose SCM interface\n+and human-friendly output. Most users run only porcelains unless they\n+have absolute necessity for plumbing commands (e.g. scripting).\n+\n+The following description divides porcelain commands into main\n+commands, ancillary utilities, tools for interacting with foreign SCM\n+and email, and similarly-named commands for reverting changes.\n \n Main porcelain commands\n ~~~~~~~~~~~~~~~~~~~~~~~\n\nbase-commit: 99c99ed8259bf070cd8ae7b51a94904b7cf5c161\n-- \n2.25.1\n\n"},{"id":"437073","messageId":"xmqqtui8r4r8.fsf@gitster.g","threadId":"56587","inReplyTo":"20210925122228.1090901-1-bagasdotme@gmail.com","subject":"Re: [PATCH] git(1): Define \"porcelain commands\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-25T16:36:59Z","receivedAt":"2021-09-25T16:37:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> The description before list of porcelain commands doesn't tell what\n> \"porcelain\" term is, nor the accurate categorization (because it only\n> says that such commands are divided into main and ancillary commands,\n> although there are also tools for interacting with others and trio\n> reset-restore-revert).\n>\n> Define the term and say the proper categorization in the description\n> paragraph.\n>\n> Signed-off-by: Bagas Sanjaya \n> ---\n> Documentation/git.txt | 10 ++++++++--\n> 1 file changed, 8 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index 6dd241ef83..fb6d7d860d 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -221,8 +221,14 @@ We divide Git into high level (\"porcelain\") commands and low level\n> High-level commands (porcelain)\n> -------------------------------\n> \n> -We separate the porcelain commands into the main commands and some\n> -ancillary user utilities.\n> +Porcelain commands are user-facing, high level command interface of\n> +Git. These are built from plumbing commands and expose SCM interface\n> +and human-friendly output. Most users run only porcelains unless they\n> +have absolute necessity for plumbing commands (e.g. scripting).\n\nBefore this section, we briefly mention that we have two classes of\ncommands (high level \"porcelain\" and low level \"plumbing\"). It is\ncertainly a good idea to have additional clarification on what \"high\nlevel\" and \"low level\" mean and how they differ, but most of the new\nmaterial should go to the preamble before this paragraph, I would\nthink.\n\nAlso, the phrasing to describe criteria to choose between them needs\ncareful rewriting. These two classes of commands serve different\npurposes. The \"high level\" ones are meant for end-user interaction,\nwhere DWIMmery and short-cuts for human convenience outweigh, while\nthe \"low level\" ones aim more for predictability to help their use\nin scripts. The choice certainly would *not* be \"unless absolutely\nnecessary, use Porcelain even for scripting\". Porcelain commands\nare designed for interactive use, plumbing are designed for\nscripting. It is more like \"script with plumbing---you can use\nPorcelain in your scripts when it is absolutely necessary, but be\nprepared that future changes to Porcelain may break your scripts and\ndo not come back to us with complaints---Porcelain can change in a\nway that will help human interactive users.\"\n\n> +The following description divides porcelain commands into main\n> +commands, ancillary utilities, tools for interacting with foreign SCM\n> +and email, and similarly-named commands for reverting changes.\n\nWhile a finer grained categorization like the above may not be a bad\nidea, I have not formed an opinion if the above one is what we\nwant (especially I am not sure about singling out \"reverting\nchanges\", both as a category and as a characterization).\n\nThanks.\n"}]}