git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* RFC: Modernizing the contept of plumbing v.s. porcelain
@ 2020-12-09  8:17 Ævar Arnfjörð Bjarmason
  2020-12-09 19:38 ` Junio C Hamano
  2020-12-10  3:07 ` Felipe Contreras
  0 siblings, 2 replies; 5+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2020-12-09  8:17 UTC (permalink / raw)
  To: git

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.

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

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2020-12-14 22:51 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-09  8:17 RFC: Modernizing the contept of plumbing v.s. porcelain Ævar Arnfjörð Bjarmason
2020-12-09 19:38 ` Junio C Hamano
2020-12-10 14:14   ` Ævar Arnfjörð Bjarmason
2020-12-14 22:49     ` Junio C Hamano
2020-12-10  3:07 ` Felipe Contreras

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).