On Wed, Dec 09 2020, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes: > >> A lot of external guides and people's mental models of /usr/bin/git as a >> scriptable client reference the concept of plumbing & porcelain. Just >> one such example [1] prompted me to write this E-Mail. >> >> I've wondered if we shouldn't be updating this concept to reflect the >> reality on the ground in the git command ecosystem. > > The example tells me that they are trying to be a good ecosystem > citizen by sticking to the plumbing and refraining from using > Porcelain command when writing their script. The practice gives > them assurance that we won't unilaterally break them, and gives us > the freedom to improve Porcelain for human consumption. > >> I.e. if you look at "git help git"'s list of plumbing v.s. porcelain it >> makes no mention or distinction between those commands & functionalities >> that are truly transitory "porcelain". E.g. the specific error message a >> command might return, and those that are effectively plumbing. E.g. some >> "git config" functionality, "git init", the pretty formats in "git log" >> etc. >> >> I'm not quite sure what I'm proposing if anything, just putting out >> feelers to see if others think this documentary status quo has drifted >> from reality. >> >> One potential change would be to mostly/entirely remove the >> "porcelain/ancillary/plumbing" distinction in "git help git" (except >> maybe e.g. "hash-object") and instead make a mention of the status of >> the command at the top of its own manpage, which could then also >> (e.g. in the case of "git log") document the API reliability of its >> various sub-features. >> >> 1. https://gitlab.com/gitlab-org/gitaly/-/blob/afc90e3c2/doc/serverside_git_usage.md#L11-17 > > I am not sure what you want to propose as a solution, but even > before that, what problem you are perceiving. Are you wondering if > it may be a better general direction for us to tell "no, no, there > is no value in sticking to the plumbing because we will break you > anyway in the future" to those who wrote [1]? I was updating that documentation, and ended up going for: +#### Plumbing v.s. porcelain + `git(1)` is the default choice to access repositories for Gitaly. Not all -commands that are available should be used in the Gitaly code base. Git makes -a distinction between porcelain and plumbing commands. Porcelain commands are -intended for the end-user and are the user-interface of the default `git` -client, where plumbing commands are intended for scripted use or to build -another porcelain. Gitaly should only use plumbing commands. `man 1 git` -contains a section on the low level plumbing. +commands that are available should be used in the Gitaly code base. + +Git makes a distinction between porcelain and plumbing +commands. Porcelain commands are intended for the end-user and are the +user-interface of the default `git` client, where plumbing commands +are intended for scripted use or to build another porcelain. + +Generally speaking, Gitaly should only use plumbing commands. `man 1 +git` contains a section on the low level plumbing. However, a lot of +git's plumbing-like functionality is exposed as commands not marked as +plumbing, but whose API reliability can be considered the +same. E.g. `git log`'s `--pretty=` formats, `git config -l -z`, the +documented exit codes of `git remote` etc.. + +We should use good judgement when choosing what commands and command +functionality to use, with the aim of not having gitaly break due to +e.g. an error message being rephrased or functionality the upstream +`git` maintainers don't consider plumbing-like being removed or +altered. + +#### Executing Git commands I.e. the existing advice was to say "just use plumbing", now it takes a more nuanced view of e.g. pointing out that certin porcelain commands have "-z" options that can be considered as reliable as things explicitly marked as plumbing. It's widespread traditional wisdom when discussing git that there's plumbing and porcelain, but I think ever since all the builtins were shellscripts way-back-when this distinction has blurred. We now have some plumbing tools whole entire functionality is considered a stable API, some porcelain tools you shouldn't rely on at all for that, but a large set of tools that are in-between somewhere. E.g. maybe their output format(s) are "plumbing-like", or some options (such as "-z") but not others. I think updating our documentation to reflect this would be a good idea, and I'm willing to write those patches. Just thought I'd weather-balloon what others thought about it first. I think a good way forward there would be: 1. Keep the high-level/low-level list in "man git", but not mention plumbing/porcelain so prominently. Some of that's ... a bit suspect, e.g. "its low-level commands are sufficient to support development of alternative porcelains", but then git-config(1) is porcelain. These days you're not getting very far in developing your own alternate porcelain with just the plumbing commands. 2. Either inline at the bottom, or probably better in a new gitplumbing(5) (or gitapi(5) or something) explain the nuance, that some commads are pure-plumbing, some pure-porcelain, and some are hybrids. That you can follow some general rules (does it have "-z" output, can probably be relied on) to determine "plumbing-like", or porcelain-like (is it stdout/stderr output in English, does it change under i18n?), that not all manpages might explicitly call out plumbing / porcelain, and that when in doubt ask the list.
