{"thread":{"id":"54804","subject":"RFC: Modernizing the contept of plumbing v.s. porcelain","startedAt":"2020-12-09T08:18:18Z","lastAt":"2020-12-14T22:51:02Z","messageCount":5,"participants":["Ævar Arnfjörð Bjarmason","Junio C Hamano","Felipe Contreras"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"411828","messageId":"878sa7xujm.fsf@evledraar.gmail.com","threadId":"54804","inReplyTo":null,"subject":"RFC: Modernizing the contept of plumbing v.s. porcelain","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2020-12-09T08:17:33Z","receivedAt":"2020-12-09T08:18:18Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"A lot of external guides and people's mental models of /usr/bin/git as a\nscriptable client reference the concept of plumbing & porcelain. Just\none such example [1] prompted me to write this E-Mail.\n\nI've wondered if we shouldn't be updating this concept to reflect the\nreality on the ground in the git command ecosystem.\n\nI.e. if you look at \"git help git\"'s list of plumbing v.s. porcelain it\nmakes no mention or distinction between those commands & functionalities\nthat are truly transitory \"porcelain\". E.g. the specific error message a\ncommand might return, and those that are effectively plumbing. E.g. some\n\"git config\" functionality, \"git init\", the pretty formats in \"git log\"\netc.\n\nI'm not quite sure what I'm proposing if anything, just putting out\nfeelers to see if others think this documentary status quo has drifted\nfrom reality.\n\nOne potential change would be to mostly/entirely remove the\n\"porcelain/ancillary/plumbing\" distinction in \"git help git\" (except\nmaybe e.g. \"hash-object\") and instead make a mention of the status of\nthe command at the top of its own manpage, which could then also\n(e.g. in the case of \"git log\") document the API reliability of its\nvarious sub-features.\n\n1. https://gitlab.com/gitlab-org/gitaly/-/blob/afc90e3c2/doc/serverside_git_usage.md#L11-17\n"},{"id":"411902","messageId":"xmqqczzi3h3a.fsf@gitster.c.googlers.com","threadId":"54804","inReplyTo":"878sa7xujm.fsf@evledraar.gmail.com","subject":"Re: RFC: Modernizing the contept of plumbing v.s. porcelain","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-09T19:38:33Z","receivedAt":"2020-12-09T19:40:51Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> A lot of external guides and people's mental models of /usr/bin/git as a\n> scriptable client reference the concept of plumbing & porcelain. Just\n> one such example [1] prompted me to write this E-Mail.\n>\n> I've wondered if we shouldn't be updating this concept to reflect the\n> reality on the ground in the git command ecosystem.\n\nThe example tells me that they are trying to be a good ecosystem\ncitizen by sticking to the plumbing and refraining from using\nPorcelain command when writing their script.  The practice gives\nthem assurance that we won't unilaterally break them, and gives us\nthe freedom to improve Porcelain for human consumption.\n\n> I.e. if you look at \"git help git\"'s list of plumbing v.s. porcelain it\n> makes no mention or distinction between those commands & functionalities\n> that are truly transitory \"porcelain\". E.g. the specific error message a\n> command might return, and those that are effectively plumbing. E.g. some\n> \"git config\" functionality, \"git init\", the pretty formats in \"git log\"\n> etc.\n>\n> I'm not quite sure what I'm proposing if anything, just putting out\n> feelers to see if others think this documentary status quo has drifted\n> from reality.\n>\n> One potential change would be to mostly/entirely remove the\n> \"porcelain/ancillary/plumbing\" distinction in \"git help git\" (except\n> maybe e.g. \"hash-object\") and instead make a mention of the status of\n> the command at the top of its own manpage, which could then also\n> (e.g. in the case of \"git log\") document the API reliability of its\n> various sub-features.\n>\n> 1. https://gitlab.com/gitlab-org/gitaly/-/blob/afc90e3c2/doc/serverside_git_usage.md#L11-17\n\nI am not sure what you want to propose as a solution, but even\nbefore that, what problem you are perceiving.  Are you wondering if\nit may be a better general direction for us to tell \"no, no, there\nis no value in sticking to the plumbing because we will break you\nanyway in the future\" to those who wrote [1]?\n\n"},{"id":"411977","messageId":"CAMP44s1bemXUC2wR-2X2-Pp+=OU-=UrMsSroCwqu5jZ0krAy0A@mail.gmail.com","threadId":"54804","inReplyTo":"878sa7xujm.fsf@evledraar.gmail.com","subject":"Re: RFC: Modernizing the contept of plumbing v.s. porcelain","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2020-12-10T03:07:06Z","receivedAt":"2020-12-10T03:08:20Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Dec 9, 2020 at 5:02 PM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:\n>\n> A lot of external guides and people's mental models of /usr/bin/git as a\n> scriptable client reference the concept of plumbing & porcelain. Just\n> one such example [1] prompted me to write this E-Mail.\n>\n> I've wondered if we shouldn't be updating this concept to reflect the\n> reality on the ground in the git command ecosystem.\n>\n> I.e. if you look at \"git help git\"'s list of plumbing v.s. porcelain it\n> makes no mention or distinction between those commands & functionalities\n> that are truly transitory \"porcelain\". E.g. the specific error message a\n> command might return, and those that are effectively plumbing. E.g. some\n> \"git config\" functionality, \"git init\", the pretty formats in \"git log\"\n> etc.\n>\n> I'm not quite sure what I'm proposing if anything, just putting out\n> feelers to see if others think this documentary status quo has drifted\n> from reality.\n\nOne option would be to split git into two binaries: \"git\" and\n\"git-tool\". Obviously the latter would be plumbing.\n\nWe could slowly move the documentation to git-tool and by doing so we\ncould see that if a porcelain man page has too many links to git-tool\ndocumentation, that's some area of opportunity.\n\nEvery time you access a git-tool command inside git, it still would\nwork, but you will get a warning: \"you are using a plumbing command,\nuse git-tool instead\". Scripts could enable GIT_TOOL_MODE=1 if they\nare going to access many of these commands and don't want to\ns/git/git-tool/.\n\nI would be a ton of work, but it's something I see value in doing.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"411994","messageId":"87v9d9wxwd.fsf@evledraar.gmail.com","threadId":"54804","inReplyTo":"xmqqczzi3h3a.fsf@gitster.c.googlers.com","subject":"Re: RFC: Modernizing the contept of plumbing v.s. porcelain","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2020-12-10T14:14:58Z","receivedAt":"2020-12-10T14:16:00Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Dec 09 2020, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n>\n>> A lot of external guides and people's mental models of /usr/bin/git as a\n>> scriptable client reference the concept of plumbing & porcelain. Just\n>> one such example [1] prompted me to write this E-Mail.\n>>\n>> I've wondered if we shouldn't be updating this concept to reflect the\n>> reality on the ground in the git command ecosystem.\n>\n> The example tells me that they are trying to be a good ecosystem\n> citizen by sticking to the plumbing and refraining from using\n> Porcelain command when writing their script.  The practice gives\n> them assurance that we won't unilaterally break them, and gives us\n> the freedom to improve Porcelain for human consumption.\n>\n>> I.e. if you look at \"git help git\"'s list of plumbing v.s. porcelain it\n>> makes no mention or distinction between those commands & functionalities\n>> that are truly transitory \"porcelain\". E.g. the specific error message a\n>> command might return, and those that are effectively plumbing. E.g. some\n>> \"git config\" functionality, \"git init\", the pretty formats in \"git log\"\n>> etc.\n>>\n>> I'm not quite sure what I'm proposing if anything, just putting out\n>> feelers to see if others think this documentary status quo has drifted\n>> from reality.\n>>\n>> One potential change would be to mostly/entirely remove the\n>> \"porcelain/ancillary/plumbing\" distinction in \"git help git\" (except\n>> maybe e.g. \"hash-object\") and instead make a mention of the status of\n>> the command at the top of its own manpage, which could then also\n>> (e.g. in the case of \"git log\") document the API reliability of its\n>> various sub-features.\n>>\n>> 1. https://gitlab.com/gitlab-org/gitaly/-/blob/afc90e3c2/doc/serverside_git_usage.md#L11-17\n>\n> I am not sure what you want to propose as a solution, but even\n> before that, what problem you are perceiving.  Are you wondering if\n> it may be a better general direction for us to tell \"no, no, there\n> is no value in sticking to the plumbing because we will break you\n> anyway in the future\" to those who wrote [1]?\n\nI was updating that documentation, and ended up going for:\n\n    +#### Plumbing v.s. porcelain\n    +\n     `git(1)` is the default choice to access repositories for Gitaly. Not all\n    -commands that are available should be used in the Gitaly code base. Git makes\n    -a distinction between porcelain and plumbing commands. Porcelain commands are\n    -intended for the end-user and are the user-interface of the default `git`\n    -client, where plumbing commands are intended for scripted use or to build\n    -another porcelain. Gitaly should only use plumbing commands. `man 1 git`\n    -contains a section on the low level plumbing.\n    +commands that are available should be used in the Gitaly code base.\n    +\n    +Git makes a distinction between porcelain and plumbing\n    +commands. Porcelain commands are intended for the end-user and are the\n    +user-interface of the default `git` client, where plumbing commands\n    +are intended for scripted use or to build another porcelain.\n    +\n    +Generally speaking, Gitaly should only use plumbing commands. `man 1\n    +git` contains a section on the low level plumbing. However, a lot of\n    +git's plumbing-like functionality is exposed as commands not marked as\n    +plumbing, but whose API reliability can be considered the\n    +same. E.g. `git log`'s `--pretty=` formats, `git config -l -z`, the\n    +documented exit codes of `git remote` etc..\n    +\n    +We should use good judgement when choosing what commands and command\n    +functionality to use, with the aim of not having gitaly break due to\n    +e.g. an error message being rephrased or functionality the upstream\n    +`git` maintainers don't consider plumbing-like being removed or\n    +altered.\n    +\n    +#### Executing Git commands\n\nI.e. the existing advice was to say \"just use plumbing\", now it takes a\nmore nuanced view of e.g. pointing out that certin porcelain commands\nhave \"-z\" options that can be considered as reliable as things\nexplicitly marked as plumbing.\n\nIt's widespread traditional wisdom when discussing git that there's\nplumbing and porcelain, but I think ever since all the builtins were\nshellscripts way-back-when this distinction has blurred.\n\nWe now have some plumbing tools whole entire functionality is considered\na stable API, some porcelain tools you shouldn't rely on at all for\nthat, but a large set of tools that are in-between somewhere. E.g. maybe\ntheir output format(s) are \"plumbing-like\", or some options (such as\n\"-z\") but not others.\n\nI think updating our documentation to reflect this would be a good idea,\nand I'm willing to write those patches. Just thought I'd weather-balloon\nwhat others thought about it first.\n\nI think a good way forward there would be:\n\n 1. Keep the high-level/low-level list in \"man git\", but not mention\n    plumbing/porcelain so prominently.\n\n    Some of that's ... a bit suspect, e.g. \"its low-level commands are\n    sufficient to support development of alternative porcelains\", but\n    then git-config(1) is porcelain. These days you're not getting very\n    far in developing your own alternate porcelain with just the\n    plumbing commands.\n\n 2. Either inline at the bottom, or probably better in a new\n    gitplumbing(5) (or gitapi(5) or something) explain the nuance, that\n    some commads are pure-plumbing, some pure-porcelain, and some are\n    hybrids.\n\n    That you can follow some general rules (does it have \"-z\" output,\n    can probably be relied on) to determine \"plumbing-like\", or\n    porcelain-like (is it stdout/stderr output in English, does it\n    change under i18n?), that not all manpages might explicitly call out\n    plumbing / porcelain, and that when in doubt ask the list.\n\n"},{"id":"412213","messageId":"xmqq8sa0atpz.fsf@gitster.c.googlers.com","threadId":"54804","inReplyTo":"87v9d9wxwd.fsf@evledraar.gmail.com","subject":"Re: RFC: Modernizing the contept of plumbing v.s. porcelain","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-14T22:49:44Z","receivedAt":"2020-12-14T22:51:02Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> I.e. the existing advice was to say \"just use plumbing\", now it takes a\n> more nuanced view of e.g. pointing out that certin porcelain commands\n> have \"-z\" options that can be considered as reliable as things\n> explicitly marked as plumbing.\n\nYup, and we have --porcelain option to some commands that are meant\nto help Porcelain writers.\n\n> It's widespread traditional wisdom when discussing git that there's\n> plumbing and porcelain, but I think ever since all the builtins were\n> shellscripts way-back-when this distinction has blurred.\n\nYeah, it is somewhat unfortunate that it is human nature to be\nexcited by shiny new toys that are end results; some of the newer\nfeatures we added and only available at the Porcelain level may be\nbetter made available to the plumbing, but that is one of the\neasiest corners authors can cut.\n\n>  2. Either inline at the bottom, or probably better in a new\n>     gitplumbing(5) (or gitapi(5) or something) explain the nuance, that\n>     some commads are pure-plumbing, some pure-porcelain, and some are\n>     hybrids.\n>\n>     That you can follow some general rules (does it have \"-z\" output,\n>     can probably be relied on) to determine \"plumbing-like\", or\n>     porcelain-like (is it stdout/stderr output in English, does it\n>     change under i18n?), that not all manpages might explicitly call out\n>     plumbing / porcelain, and that when in doubt ask the list.\n\nOK.\n"}]}