What does the term "porcelain" mean in Git?

Question

The term "porcelain" appears occasionally in the Git documentation. What does it mean?

Diffusion

Answer 1

"Porcelain" is the material from which toilets are usually made (and sometimes other fixtures such as washbasins). This is distinct from "plumbing" (the actual pipes and drains), where the porcelain provides a more user-friendly interface to the plumbing.

Git uses this terminology in analogy, to separate the low-level commands that users don't usually need to use directly (the "plumbing") from the more user-friendly high level commands (the "porcelain").

Cl

I think the answer makes sense to me, but then again, I'm assuming Linus was the one that coined the term, so I tend to adjust my brain to be a little more direct and crass when parsing his world. :) – Hoeve

Makes you wonder if Linus was imagining the potential streams of excrement his plumbing would be used to transport. Plumbing for open source code is a dirty job but someone's got to do it. – Mckellar

And a few of us feel that the actual git porcelain is more like a layer of paint over the plumbing. – Rusticate

This answer would be more useful with examples of which commands are the plumbing and which the porcelain. – Weaver

"user-friendly" toilet interface indeed! mark# git flush Did you mean this? push – Chiromancy

I've not a clue what Linus actually had in mind, but in french, "porcelaine" refers to something refined and precious like high quality thin dinner plates (fine china). What toilets are made of is called "faïence", although there are many stylish pieces of "faïence" as well. wikiwand.com/en/Limoges_porcelain . Anyway, it seems that it is trendy in America to shit on France best know-how and art nowadays – Clie

@Clie In Swedish (Linus' native language) #, porcelaine is used the same as in French. With the distinction that it could refer to toilets, but more in the sense what they are made of. It's not generelly used to refer to a toilet. (It would be valid, but quaint.) A valid but more normal use though could be "clean the porcelaine very carefully with this special detergent" when instructing someone on how to clean a bathroom. # - With the caveat that Linus' dialect of Swedish is from Finland, I may miss some nuance. – Somnambulate

Have I missed something, or is the analogy entirely the wrong way round, relative to the implementation? If "plumbing" is thought of as low-level/machine-y and "porcelain" is thought of as high-level/human-friendly (which is the way it is in bathroom fixtures), then why is it that adding the --porcelain option (let's say, to git status) removes the human-readable verbosity and makes the result more machine-readable? – Made

@jez: Because Git's command line interface is confusing and inconsistent. See Which are the plumbing and porcelain commands? for further discussion about what --porcelain means. – Cl

The jargon usage "porcelain" dates from Emacs libraries, which existed well before Git. The notion of it being a human interface to plumbing is the same. – Clance

In this specific case, I consider that the -- before porcelain means "remove the porcelain" ;-) – Iene

Answer 2

More importantly, the term "porcelain" applies to high-level commands, with output:

• meant to be readable by human
• not meant to be parsed
• susceptible to changes/evolutions

That is key: if you script, you should use if possible plumbing commands, with stable outputs. Not porcelain commands.

However, you can use the output of a porcelain command which has a --porcelain option in script (see below), like:

git status --porcelain
git push --porcelain
git blame --porcelain

Although git includes its own porcelain layer, its low-level commands are sufficient to support development of alternative porcelains.
The interface (input, output, set of options and the semantics) to these low-level commands are meant to be a lot more stable than Porcelain level commands because these commands are primarily for scripted use.
The interface to Porcelain commands, on the other hand, are subject to change to improve the end-user experience.

See "How do I programmatically determine if there are uncommitted changes?" as an example of using plumbing commands instead of porcelain ones.

---

Note: A porcelain command can have a --porcelain option.
For instance: git status --porcelain (Git mailing list), which designates an output meant to be parsed.

--porcelain

Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable across git versions and regardless of user configuration. See below for details.

The aforementioned thread from the Git mailing list included the following details:

This is my fault, to some degree.
The "short-status" form is meant for human eyeballs, and was designed by Junio.
Some people wanted a scriptable status output, too, so I slapped a "--porcelain" on the same format that turns off configurable features like relative pathnames and colorizing, and makes an implicit promise that we won't make further changes to the format.
The idea was to prevent people from scripting around --short because it was never intended to be stable.
So yeah, while --porcelain by itself is stable and scriptable, it is perhaps not the most friendly to parsers. The "-z --porcelain" format is much more so, and I would recommend it to anyone scripting around "git status"

That reflects the need, for git users, to use porcelain commands in their scripts!
But only with stable output (with --porcelain)

---

As commented by william-berg, the same goes for git push!

--porcelain

Produce machine-readable output.
The output status line for each ref will be tab-separated and sent to stdout instead of stderr.
The full symbolic names of the refs will be given.

---

As John Glassmyer proposes in the comments:

Perhaps the meaning of --porcelain here is "produce output suitable for consumption by porcelain scripts".

And that could be supported by the very first case of "--porcelain option" introduction
(before git status --porcelain, commit 6f15787, September 2009, git 1.7.0,
before git push --porcelain, commit 1965ff7, June 2009, git 1.6.4):

git blame --porcelain:

-p
--porcelain

Show in a format designed for machine consumption.

Commit b5c698d, October 2006, git 1.4.4

The new option makes the command's native output format to emit output that is easier to handle by Porcelain.

Underestimate

I notice git push has a similarly anomalous machine-readable --porcelain. – Berberidaceous

Perhaps the meaning of --porcelain here is "produce output suitable for consumption by porcelain scripts". – Fawcett

@JohnGlassmyer it is a very likely explanation indeed. See my edited answer (at the end) – Underestimate

Also git diff-tree --word-diff=porcelain – Hindbrain

So, --porcelain is an option which makes the output not porcelain? – Motteo

@PatrickSanan in a sense, yes. Their output can be parsed reliably with that option. – Underestimate

So when you add --porcelain, you make it behave like plumbing. Thanks, git! – Matthaus

"thread above" has no meaning on SO... because upvotes change the order... – Ragi

@Ragi I was referring (13 years ago) to the 4th link in that same answer, a thread from the Git mailing list, not another answer on this page. I have reworded the sentence to make that clearer. – Underestimate

Answer 3

The coinage and usage of the term "porcelain" in git was actually by Mike Taht, while otherwise losing a heated argument with Linus Torvalds.

https://web.archive.org/web/20190427113112/http://www.gelato.unsw.edu.au/archives/git/0504/0881.html

In fact, one of my hopes was that other SCM's could just use the git plumbing.
But then I'd really suggest that you use "git" itself, not any "libgit". Ie you take all the plumbing as real programs, and instead of trying to link against individual routines, you'd script it.

If you don't want it, I won't do it.
Still makes sense to separate the plumbing from the porcelain, though.

Minier

Interesting. +1. My own answer above is from using the product, but your link references what seems to be the origin of that term. – Underestimate

archive.org: http://www.gelato.unsw.edu.au/archives/git/0504/0881.html – Sorgo

Answer 4

Simple Explanation

• "Porcelain" commands: NOT for scripting because: they are likely to change; meant for humans, not machines. To help you remember think of a porcelain tap (or faucet) in your bathroom - you can easily replace them with a different colour. porcelain == easy_to_change.
• "Plumbing" commands can be used for scripting because: they are more stable / less likely to change). Plumbing refers to the pipes in your bathroom - PIPES are permanent and they cannot change very easily!

yeah, but what about the confusing --porcelain option!?

If you want to:

1. use a porcelain command (meant for humans, not parsing) AND
2. parse it reliably

....then you can add the --porcelain option and use the output for scripting.

Example: I may use git status --porcelain and use the output for scripting, no problem.

(It is easy to criticize, especially if no alternative is specified - with the utmost respect to the creators of git.)

Where does porcelain/plumbing terminology come from?

• If English is not your first language then Greg Hewgill explains it perfectly.
• For greater detail: checkout VonC's answer.

Landowska

What about the confusing --porcelain option? I address that in my answer: https://mcmap.net/q/12336/-what-does-the-term-quot-porcelain-quot-mean-in-git – Underestimate

agreed! I had added a link to your very answer above: For more detail, checkout VonC's answer. – Landowska

OK, at least using an option named --porcelain on already "porcelain" commands to achieve "pseudo-plumbing" functionality blends very nicely with the general UI design of Git... ;) – Bony

I don't get it why this option is called "porcelain". The entire command is already "porcelain". The option should be called --plumbing (since you're a plumber this time, not a regular "porcelain" user). – Sensillum

Thanks for your answer, @BKSpurgeon. VonC's answer may be more detailed, but I needed your acknowledgement that the --porcelain option is confusing, in order to understand properly. – Trail

Answer 5

Porcelain is cute name for programs and program suites depending on core git, presenting a high level access to core git. Porcelains expose more of a SCM interface than the "plumbing".

--Porcelain, Git Wiki

Phosphaturia

Answer 6

There are two distinct meanings of porcelain in git.

These two meanings, while it can be argued are not strictly contradictory, can appear contradictory.

A. Conceptual (plumbing vs porcelain)

The official Pro Git book:

But because Git was initially a toolkit for a version control system rather than a full user-friendly VCS, it has a number of subcommands that do low-level work and were designed to be chained together UNIX-style or called from scripts. These commands are generally referred to as Git’s “plumbing” commands, while the more user-friendly commands are called “porcelain” commands.

B. --porcelain / =porcelain options

Many git commands come with a --porcelain option which is meant for scripting.

git status' documentation:

--porcelain[=<version>]

Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable across Git versions and regardless of user configuration. See below for details.

git diff's documentation:

--word-diff[=<mode>]

porcelain

      Use a special line-based format intended for script consumption.

Roping

Answer 7

Porcelain commands are designed for human consumption, as opposed to commands whose output is easy for computers to parse. git status would be one example.

Kovach

"Porcelain"... "for human consumption"... I can eat glass. (just kidding / noting mixed metaphor for anyone who may be easily confused) – Pastiness

Porcelain commands are for human consumption, but when you use the --porcelain option, it is for machine consumption. – Knacker

git status --porcelain: Give the output in an easy-to-parse format for scripts. (...) but will remain stable across Git versions and regardless of user configuration. – Roping

Thanks for the downvote. 🙄 Yes, git status --porcelain has a stable format that can be parsed, but the status command itself is designed to be user-facing (as opposed to, for example, git ls-files). – Kovach

Answer 8

Greg Hewgill's answer is exactly correct. Note that there are alternative porcelains available for Git, including Easy Git, yap, pyrite, and vng. Each is intended to make Git easier to learn/use for some part of the community. Links to all of these projects is on the Easy Git page: http://people.gnome.org/~newren/eg/.

Bremsstrahlung

Answer 9

Porcelain is cute name for programs and program suites depending on core git, presenting a high level access to core git.

https://git.wiki.kernel.org/index.php/Porcelain

Penny