Merge branch 'avar/doc-plumbing' into 'master'

Docs: clarify "plumbing" v.s. "porcelain" in git(1) usage

See merge request gitlab-org/gitaly!2899

1 files changed, 23 insertions, 6 deletions

diff --git a/doc/serverside_git_usage.md b/doc/serverside_git_usage.md
index 3152311da..a3d36e7c7 100644
--- a/doc/serverside_git_usage.md
+++ b/doc/serverside_git_usage.md
@@ -8,13 +8,30 @@ Gitaly uses three implementations to read and write to Git repositories:
 
 ### Using Git
 
+#### Plumbing v.s. porcelain
+
 `git(1)` is the default choice to access repositories for Gitaly. Not all
-commands that are available should be used in the Gitaly code base. Git makes
-a distinction between porcelain and plumbing commands. Porcelain commands are
-intended for the end-user and are the user-interface of the default `git`
-client, where plumbing commands are intended for scripted use or to build
-another porcelain. Gitaly should only use plumbing commands. `man 1 git`
-contains a section on the low level plumbing.
+commands that are available should be used in the Gitaly code base.
+
+Git makes a distinction between porcelain and plumbing
+commands. Porcelain commands are intended for the end-user and are the
+user-interface of the default `git` client, where plumbing commands
+are intended for scripted use or to build another porcelain.
+
+Generally speaking, Gitaly should only use plumbing commands. `man 1
+git` contains a section on the low level plumbing. However, a lot of
+git's plumbing-like functionality is exposed as commands not marked as
+plumbing, but whose API reliability can be considered the
+same. E.g. `git log`'s `--pretty=` formats, `git config -l -z`, the
+documented exit codes of `git remote` etc..
+
+We should use good judgement when choosing what commands and command
+functionality to use, with the aim of not having gitaly break due to
+e.g. an error message being rephrased or functionality the upstream
+`git` maintainers don't consider plumbing-like being removed or
+altered.
+
+#### Executing Git commands
 
 When executing Git, developers should always use the `git.SafeCmd()` and sibling
 interfaces. These make sure Gitaly is protected against command injection, the