Re: [PATCH v2] Revert "doc: move git-cherry to plumbing"

[Junio C Hamano <gitster@pobox.com>]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> This reverts commit 61018fe9e005a54e18184481927519d64035220a.
>
> git-cherry(1) is a high level command for checking what commits have and
> have not been applied to some other branch.  Or at least as high level
> as the git(1) suite offers.  In other words:
>
> • it is a useful interrogator for a particular workflow; and
> • there are no higher level commands on offer.
>
> By contrast its use for scripting is somewhat narrow since it only
> prints the patch application status and the hashes of the downstream
> branch (not also the upstream branch equivalents).  git-patch-id(1)
> gives a fuller picture by printing each hash and its corresponding
> patch id.
>
> Now this command is not nearly as convenient for the purpose of deleting
> a *merged* branch as:
>
>     git branch -d <branch>
>
> Since that command will refuse to delete the branch if the commits are
> not in the configured upstream ref.  But again it is the most convenient
> command for the patch workflow.
>
> This command might only be considered plumbing by way of the plumbing
> contract that says that plumbing commands have stable output.  But
> hopefully listing this command as Porcelain does not give the impression
> that the output is not stable.  Output stability was in any case not the
> motivation for moving this command to plumbing.

I do not follow the above reasoning at all.

It is not like it is a crime to intarctively make use of a plumbing
command, or we intentionally try to hide plumbing command from them
by making it deliberately less accessible.  "git cat-file commit X"
may be handier than "git show -s X" for some people and that is not
to be frowned upon.

And what you call "might only be" is really the crucial thing to
consider.  If we want to keep a tool's output stable and machine
readable, we need to mark it as "meant for Porcelain writers", and
classifying the tool as plumbing is a pretty much established way to
do so.