Take the 2-minute tour ×

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

share|improve this question

7 Answers 7

up vote 151 down vote accepted

"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").

share|improve this answer
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. :) –  Nick Klauer Oct 21 '11 at 4:16
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. –  Evan Plaice Feb 18 '14 at 22:02
And a few of us feel that the actual git porcelain is more like a layer of paint over the plumbing. –  hemflit Sep 20 '14 at 0:11

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 in script the output of a porcelain command which has a --porcelain option (see below), like:

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


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

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



The thread mentioned above 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 using porcelain commands in their scripts!
But only with stable output (with --porcelain)

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


Produce machine-readable output.
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:


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.

share|improve this answer
+1 Nice answer, in particular for pointing out the oddity with git status --porcelain! –  Mark Longair Aug 8 '11 at 8:41
@Mark: yes, that one kind of boggles my mind... –  VonC Aug 8 '11 at 9:16
@Tobias: thank you for the edits :) –  VonC Mar 20 '12 at 16:42
I notice git push has a similarly anomalous machine-readable --porcelain. –  william.berg May 1 '13 at 11:15
Perhaps the meaning of --porcelain here is "produce output suitable for consumption by porcelain scripts". –  John Glassmyer Dec 5 '13 at 20:48

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


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.

share|improve this answer
Interesting. +1. My own answer above is from using the product, but your link references what seems to be the origin of that term. –  VonC Dec 8 '13 at 9:38

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

share|improve this answer



share|improve this answer

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.

share|improve this answer
"Porcelain"... "for human consumption"... I can eat glass. (just kidding / noting mixed metaphor for anyone who may be easily confused) –  ajm475du Apr 6 '14 at 15:20

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/.

share|improve this answer

Your Answer


