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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 13, 2025, 16:56 UTC
Message-ID: <xmqqv7uiac0m.fsf@gitster.g>
In-Reply-To: <e5b20f9ceb437a82c422136cb81b05a0521cab07.1736682716.git.code@khaugsbakk.name>

kristofferhaugsbakk@fastmail.com writes:

Show 31 quoted lines

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