Git Reference ยท Concepts
Plumbing and porcelain commands
Learn the difference between Git porcelain (user-facing) and plumbing (low-level) commands, which are stable for scripts, and see how a commit is built by hand.
Git's commands fall into two layers. Porcelain commands are the friendly ones you type every day: add, commit, switch, merge, log, status. Plumbing commands are small, low-level tools that do one precise job: hash-object, cat-file, update-index, write-tree, commit-tree, rev-parse, for-each-ref, update-ref. Porcelain is built from plumbing, the way git commit is essentially write-tree + commit-tree + update-ref.
The distinction matters most for scripts. Porcelain output is meant for people and may change between versions (wording, colors, hints, defaults from your config). Plumbing output and options are documented as stable, so scripts should prefer them or the machine-readable modes of porcelain commands.
git status --porcelain=v1 # stable, script-friendly status git rev-parse --show-toplevel # plumbing: repository root git for-each-ref --format='%(refname:short)' refs/heads
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Concepts
The usual plumbing groups are:
| Group | Examples |
|---|---|
| Manipulation | hash-object, update-index, write-tree, read-tree, commit-tree, update-ref, symbolic-ref, mktag |
| Interrogation | cat-file, ls-files, ls-tree, rev-parse, rev-list, for-each-ref, diff-tree, diff-index, merge-base, show-ref, name-rev |
| Sync | fetch-pack, send-pack, upload-pack, receive-pack |
| Internal helpers | check-ref-format, stripspace, var, sh-i18n, credential-* |
Usage notes
- Exit codes are part of the contract.
git diff --quiet,git merge-base --is-ancestorandgit cat-file -ereport only through their exit status, which makes them ideal inifstatements (see Exit codes and scripting). - Prefer
--porcelainand-zfor parsing:git status --porcelain=v2 -zhandles file names with spaces and newlines, and ignores user color and language settings. ls-files,rev-listandfor-each-refare the reliable way to enumerate files, commits and refs. Parsinggit logorgit branchoutput breaks when users enable colors, decorations or aliases.- Locale. Set
LC_ALL=Cwhen you must match on messages from porcelain commands, though parsing human text is a last resort. - Aliases can shadow nothing. Git never lets an alias override a built-in command, but your shell function might. Scripts should call
gitexplicitly. - Plumbing does not protect you.
update-refhappily points a branch anywhere, andhash-object -wwrites whatever you give it. There are no hints or confirmations. - Learning tool. Rebuilding a commit by hand, as above, is the fastest way to understand the object model (see Objects).