diff options
author | Ævar Arnfjörð Bjarmason <avarab@gmail.com> | 2020-12-09 11:21:32 +0300 |
---|---|---|
committer | Ævar Arnfjörð Bjarmason <avarab@gmail.com> | 2020-12-09 18:33:45 +0300 |
commit | d600c79417b106cb5178f258a7613f547802c4c0 (patch) | |
tree | 3bad93abccf5c0e1dc8d140c159c14fa118687af | |
parent | 75bef2886edd4e3b1e622058584a70a3f7752b41 (diff) |
docs: clarify "plumbing" v.s. "porcelain" in git(1) usage
Clarify the recently added documentation in 2cbfe50d7 (docs: Explain
how to interact with Git in Gitaly, 2020-09-23) to not draw a hard
line on using non-plumbing. As the change being made here argues this
doesn't reflect reality on the ground.
As a practical matter we make plenty of use of non-plumbing,
e.g. "gc", "bundle", "log", "remote", "config", "worktree" etc. What
we actually care about is the sort of command use I altered in
61b9b30a5 (git.Remote: use "git remote" exit code instead of parsing
stderr, 2020-11-10). Let's try to make the docs reflect that.
I also sent a note to the git ML about the general issue:
https://public-inbox.org/git/878sa7xujm.fsf@evledraar.gmail.com/T/
-rw-r--r-- | doc/serverside_git_usage.md | 14 |
1 files changed, 12 insertions, 2 deletions
diff --git a/doc/serverside_git_usage.md b/doc/serverside_git_usage.md index 9a4d464da..a3d36e7c7 100644 --- a/doc/serverside_git_usage.md +++ b/doc/serverside_git_usage.md @@ -18,8 +18,18 @@ 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. +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 |