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--shortbecause it was never intended to be stable.
So yeah, while--porcelainby 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 tostdoutinstead ofstderr.
The full symbolic names of the refs will be given.
As John Glassmyer proposes in the comments:
Perhaps the meaning of
--porcelainhere 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):
-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.