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

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

[kristofferhaugsbakk]

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.

Users who need this interrogator should not have to look down in the
plumbing section in order to find it.

This also reverts its removal from Bash completion which Duy Nguyen
reported as a regression.[1]  The correct change for that plumbing move
would apparently have been to remove the `complete` category.

[1]: https://lore.kernel.org/git/CACsJy8AVGbS_NTZsUj_hD9D+t4YV1_S4KTD25Kda85syvoowyg@mail.gmail.com/

Reported-by: Duy Nguyen <pclouds@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    The `---` comment on the patch:
    
    > Up to discussion whether cherry should be considered plumbing.
    > I lean towards considering it a rarely-used porcelain command, but
    > a case could be made either way so let's see what the list thinks.
    
    I don’t know why rarely-used is relevant.  This change now lists
    git-cherry(1) down in the (Porcelain) Interrogators section, along with
    commands such as:
    
    • git-bugreport(1)
    • git-count-objects(1)
    • git-diagnose(1)
    • git-whatchanged(1)
    
    Not everyday tools.  And that’s okay.

 command-list.txt                       |  2 +-
 contrib/completion/git-completion.bash | 11 +++++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/command-list.txt b/command-list.txt
index e0bb87b3b5c..d73c8f59e63 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -72,7 +72,7 @@ git-check-mailmap                       purehelpers
 git-check-ref-format                    purehelpers
 git-checkout                            mainporcelain
 git-checkout-index                      plumbingmanipulators
-git-cherry                              plumbinginterrogators          complete
+git-cherry                              ancillaryinterrogators          complete
 git-cherry-pick                         mainporcelain
 git-citool                              mainporcelain
 git-clean                               mainporcelain
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 3d4dff3185c..5026ef595cd 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1746,6 +1746,17 @@ _git_checkout ()
 
 __git_sequencer_inprogress_options="--continue --quit --abort --skip"
 
+_git_cherry ()
+{
+	case "$cur" in
+	--*)
+		__gitcomp_builtin cherry
+		return
+	esac
+
+	__git_complete_refs
+}
+
 __git_cherry_pick_inprogress_options=$__git_sequencer_inprogress_options
 
 _git_cherry_pick ()

base-commit: cc01bad4a9f566cf4453c7edd6b433851b0835e2
-- 
2.47.0