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

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.

Answer 2

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 ecbffffd1, 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.

Answer 3

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)

Answer 4

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.