Which are the plumbing and porcelain commands?

Question

For git commands there is this distinction between "plumbing" and "porcelain" commands. How can I determine what would be classified as a plumbing one or a porcelain one? i.e. What is the border line that allows me to differentiate?

I'm not asking what a porcelain or plumbing command is, but rather how, given a command, I can say which type it is.

Latoyialatreece

@TimBiegeleisen absolutely not. I know what they are, I ask how can I say if git status is a porcelain or not, for example – Latoyialatreece

For reference on what the OP is referring to: stackoverflow.com/questions/6976473/… – Annmaria

Maybe you could include some info on why you need to know this distinction, e.g. you're building a plugin, you have performance concerns, etc. – Annmaria

@TimBiegeleisen I would like to know only for theoretical purpose. – Latoyialatreece

Answer 1

As blue112 noted, the dividing line is fuzzy. The very first documentation page, however, has an explicit list (and as R.M. notes below, one primary criterion is, or at least is supposed to be, stability of interface—for which some nominally-porcelain commands have --porcelain¹ to force a more stable and/or more machine-readable output). You can choose to use their list, or decide that some commands are too high level to be low level, or too low level to be high level. For instance you might disagree that git apply is a plumbing command, yet the Git page says it is. Or, you might consider things like git fast-import to be something you would only use inside a script.

Edit, 31 May 2020: The Git documentation has changed since 2016 to reassign commands to new sections; the data below are now out of date. Consult the documentation for your own Git version (via git help git for instance) to see what your own system says. See also VonC's answer with a link to a 2018 change to the documentation.

The list below is simply extracted from the documentation, with descriptions and additional classifications stripped to leave only "porcelain" vs "plumbing". (Sub-classifications remain visible as inversions in the alphabetic sort order. I did not construct links for each entry, as this would be considerably more difficult with StackOverflow markdown—this just needed a simple <pre>...</pre> wrapper.)

porcelain

git-add                 git-rebase              git-cherry
git-am                  git-reset               git-count-objects
git-archive             git-revert              git-difftool
git-bisect              git-rm                  git-fsck
git-branch              git-shortlog            git-get-tar-commit-id
git-bundle              git-show                git-help
git-checkout            git-stash               git-instaweb
git-cherry-pick         git-status              git-merge-tree
git-citool              git-submodule           git-rerere
git-clean               git-tag                 git-rev-parse
git-clone               git-worktree            git-show-branch
git-commit              gitk                    git-verify-commit
git-describe            git-config              git-verify-tag
git-diff                git-fast-export         git-whatchanged
git-fetch               git-fast-import         gitweb
git-format-patch        git-filter-branch       git-archimport
git-gc                  git-mergetool           git-cvsexportcommit
git-grep                git-pack-refs           git-cvsimport
git-gui                 git-prune               git-cvsserver
git-init                git-reflog              git-imap-send
git-log                 git-relink              git-p4
git-merge               git-remote              git-quiltimport
git-mv                  git-repack              git-request-pull
git-notes               git-replace             git-send-email
git-pull                git-annotate            git-svn
git-push                git-blame

plumbing

git-apply               git-for-each-ref        git-receive-pack
git-checkout-index      git-ls-files            git-shell
git-commit-tree         git-ls-remote           git-upload-archive
git-hash-object         git-ls-tree             git-upload-pack
git-index-pack          git-merge-base          git-check-attr
git-merge-file          git-name-rev            git-check-ignore
git-merge-index         git-pack-redundant      git-check-mailmap
git-mktag               git-rev-list            git-check-ref-format
git-mktree              git-show-index          git-column
git-pack-objects        git-show-ref            git-credential
git-prune-packed        git-unpack-file         git-credential-cache
git-read-tree           git-var                 git-credential-store
git-symbolic-ref        git-verify-pack         git-fmt-merge-msg
git-unpack-objects      git-daemon              git-interpret-trailers
git-update-index        git-fetch-pack          git-mailinfo
git-update-ref          git-http-backend        git-mailsplit
git-write-tree          git-send-pack           git-merge-one-file
git-cat-file            git-update-server-info  git-patch-id
git-diff-files          git-http-fetch          git-sh-i18n
git-diff-index          git-http-push           git-sh-setup
git-diff-tree           git-parse-remote        git-stripspace

---

¹It would seem more logical to call this --plumbing, but as VonC notes in this answer to a related question, one can view this instead as a request: "I am implementing porcelain so please give me plumbing-style output." The flaw in this argument is that you might be implementing complex plumbing, and want to use simple plumbing to do it: now there's no porcelain in sight, and yet, your complex plumbing passes --porcelain to some simple plumbing.

Ninebark

This answer and the documentation you link indicates that the primary dividing line between porcelain and plumbing commands - from the git maintainers' perspective - is the stability of the interface/output. Porcelain commands are intended for direct human interaction, and may not have stably formatted output (that is, minor formatting changes between versions could break post-processing scripts). The output from plumbing commands is intended to be parsed by automated scripts, so will be more stable version-to-version. – Liddle

@R.M.: good point, I'll edit that into the answer here as well. – Ninebark

Thanks for the list! Why is git-rev-parse considered porcelain? – Basidium

@PiQuer: I don't really know: git rev-parse is very plumbing-ish. The lists above are straight from the documentation as of October 2016. Since then the documentation has been revised: it now has more sub-categories. git rev-parse has been moved into the "plumbing" section under "interrogation commands". – Ninebark

Oof, can we please run the lists through an alphabetical sort? That would make it so much easier for readers to quickly visually "query" the list. I had to break out my browser's text search feature just to find which list git-show-ref was in. :( – Rhamnaceous

@mtraceur: that might not be a bad idea. Also, the list has changed since I posted it: as noted in a comment, git rev-parse moved to plumbing, and there are new commands, such as git switch, that are not in the original list. But the way to search these is to go to your own Git's documentation, since it's ultimately dynamic due to Git evolution. – Ninebark

Yes, git switch and git restore are missing - I would add it but don't want to mess with this formatted list. – Audition

Answer 2

I think there is no straight line between commands.

Commands that you use from day to day are porcelain (think about status, diff, commit...), less used commands, which give less formated outputs are plumbing (think about diff-index, hash-object or send-pack).

You can have a full list of git commands using git help -a. It's pretty easy to tell here which command belongs more to porcelain or plumbering.

Looking at the manual of git send-pack you can see the following line

Usually you would want to use git push, which is a higher-level wrapper of this command, instead.

This is what's telling you that it more a plumbing command.

Handley

"I think there is no straight line between commands." seems to be contradicted by "It's pretty easy to tell here which command is which.". – Footwear

Thanks for the fix! :) However, honestly I still fail to understand whether you consider this matter easy or not. Perhaps a matter of taste on this level of detail ;) – Footwear

Answer 3

The actual command listing plumbing commands (and the other commands, in their own sections) was:

git help -av

This comes from git/git/command-list.txt.

And this changes with Git 2.20 (Q4 2018), considering "git help -a" and "git help -av" give different pieces of information, and generally the "verbose" version is more friendly to the new users.

"git help -a" by default now uses the more verbose output (with "--no-verbose", you can go back to the original).

See commit 26c7d06 (29 Sep 2018) by Nguyễn Thái Ngọc Duy (pclouds).
^{(Merged by Junio C Hamano -- gitster -- in commit 54e564e, 19 Oct 2018)}

help -a: improve and make --verbose default

When you type "git help" (or just "git") you are greeted with a list with commonly used commands and their short description and are suggested to use "git help -a" or "git help -g" for more details.

"git help -av" would be more friendly and inline with what is shown with "git help" since it shows list of commands with description as well, and commands are properly grouped.

"help -av" does not show everything "help -a" shows though.
Add external command section in "help -av" for this. While at there, add a section for aliases as well (until now aliases have no UI, just "git config").

A simple git help -a (with Git 2.20+) will now return:

vonc@VONC D:\git\git
> git help -a
Main Porcelain Commands
   add                  Add file contents to the index
   am                   Apply a series of patches from a mailbox
   archive              Create an archive of files from a named tree
   bisect               Use binary search to find the commit that introduced a bug
...

---

With Git 2.25 (Q1 2020), the list of commands is more complete.

See commit 762d5b4 (28 Oct 2019) by Philippe Blain (phil-blain).
^{(Merged by Junio C Hamano -- gitster -- in commit ecbddd1, 01 Dec 2019)}

help: add gitsubmodules to the list of guides

^{Signed-off-by: Philippe Blain
Reviewed-by: Jonathan Nieder}

The guide "gitsubmodules" was added in d480345 ("submodules: overhaul documentation", 2017-06-22, Git v2.14.0-rc0 -- merge listed in batch #0), but it was not added to command-list.txt when commit 1b81d8c ("help: use command-list.txt for the source of guides", 2018-05-20, Git v2.18.0-rc1 -- merge) taught "git help" to obtain the guide list from this file.

Add it now, and capitalize the first word of the description of gitsubmodules, as was done in 1b81d8c ("help: use command-list.txt for the source of guides", 2018-05-20, Git v2.18.0-rc1 -- merge) for the other guides.

---

With Git 2.36 (Q2 2022):

• git help -a --no-external-commands will not list an git-xxx executable found in the PATH,
• git help -a --no-aliases will not list any git xxx defined as alias.

Lisabeth

Answer 4

One idea is to visit the Git documentation page and see if the command you want to use is listed under High-level commands (porcelain) or Low-level commands (plumbing)

Bullock