Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash Making a commit with plumbing only

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.

Bash Stable output for scripts

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-ancestor and git cat-file -e report only through their exit status, which makes them ideal in if statements (see Exit codes and scripting).
  • Prefer --porcelain and -z for parsing: git status --porcelain=v2 -z handles file names with spaces and newlines, and ignores user color and language settings.
  • ls-files, rev-list and for-each-ref are the reliable way to enumerate files, commits and refs. Parsing git log or git branch output breaks when users enable colors, decorations or aliases.
  • Locale. Set LC_ALL=C when 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 git explicitly.
  • Plumbing does not protect you. update-ref happily points a branch anywhere, and hash-object -w writes 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).