{"thread":{"id":"62793","subject":"[PATCH v2] Revert \"doc: move git-cherry to plumbing\"","startedAt":"2025-01-12T11:54:44Z","lastAt":"2025-01-14T17:35:11Z","messageCount":5,"participants":["kristofferhaugsbakk@fastmail.com","Kristoffer Haugsbakk","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"510380","messageId":"e5b20f9ceb437a82c422136cb81b05a0521cab07.1736682716.git.code@khaugsbakk.name","threadId":"62793","inReplyTo":null,"subject":"[PATCH v2] Revert \"doc: move git-cherry to plumbing\"","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-01-12T11:54:28Z","receivedAt":"2025-01-12T11:54:44Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nThis reverts commit 61018fe9e005a54e18184481927519d64035220a.\n\ngit-cherry(1) is a high level command for checking what commits have and\nhave not been applied to some other branch. Or at least as high level\nas the git(1) suite offers. In other words:\n\n• it is a useful interrogator for a particular workflow; and\n• there are no higher level commands on offer.\n\nBy contrast its use for scripting is somewhat narrow since it only\nprints the patch application status and the hashes of the downstream\nbranch (not also the upstream branch equivalents). git-patch-id(1)\ngives a fuller picture by printing each hash and its corresponding\npatch id.\n\nNow this command is not nearly as convenient for the purpose of deleting\na *merged* branch as:\n\n git branch -d \n\nSince that command will refuse to delete the branch if the commits are\nnot in the configured upstream ref. But again it is the most convenient\ncommand for the patch workflow.\n\nThis command might only be considered plumbing by way of the plumbing\ncontract that says that plumbing commands have stable output. But\nhopefully listing this command as Porcelain does not give the impression\nthat the output is not stable. Output stability was in any case not the\nmotivation for moving this command to plumbing.\n\nUsers who need this interrogator should not have to look down in the\nplumbing section in order to find it.\n\nThis also reverts its removal from Bash completion which Duy Nguyen\nreported as a regression.[1] The correct change for that plumbing move\nwould apparently have been to remove the `complete` category.\n\n[1]: https://lore.kernel.org/git/CACsJy8AVGbS_NTZsUj_hD9D+t4YV1_S4KTD25Kda85syvoowyg@mail.gmail.com/\n\nReported-by: Duy Nguyen \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n § v1\n \n Resend with CC dropped. Neither of the two seem to have been active\n for years.\n \n § v2\n \n The `---` comment on the patch:\n \n > Up to discussion whether cherry should be considered plumbing.\n > I lean towards considering it a rarely-used porcelain command, but\n > a case could be made either way so let's see what the list thinks.\n \n I don’t know why rarely-used is relevant. This change now lists\n git-cherry(1) down in the (Porcelain) Interrogators section, along with\n commands such as:\n \n • git-bugreport(1)\n • git-count-objects(1)\n • git-diagnose(1)\n • git-whatchanged(1)\n \n Not everyday tools. And that’s okay.\n\n command-list.txt | 2 +-\n contrib/completion/git-completion.bash | 11 +++++++++++\n 2 files changed, 12 insertions(+), 1 deletion(-)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex e0bb87b3b5c..d73c8f59e63 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -72,7 +72,7 @@ git-check-mailmap purehelpers\n git-check-ref-format purehelpers\n git-checkout mainporcelain\n git-checkout-index plumbingmanipulators\n-git-cherry plumbinginterrogators complete\n+git-cherry ancillaryinterrogators complete\n git-cherry-pick mainporcelain\n git-citool mainporcelain\n git-clean mainporcelain\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 3d4dff3185c..5026ef595cd 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -1746,6 +1746,17 @@ _git_checkout ()\n \n __git_sequencer_inprogress_options=\"--continue --quit --abort --skip\"\n \n+_git_cherry ()\n+{\n+\tcase \"$cur\" in\n+\t--*)\n+\t\t__gitcomp_builtin cherry\n+\t\treturn\n+\tesac\n+\n+\t__git_complete_refs\n+}\n+\n __git_cherry_pick_inprogress_options=$__git_sequencer_inprogress_options\n \n _git_cherry_pick ()\n\nbase-commit: cc01bad4a9f566cf4453c7edd6b433851b0835e2\n-- \n2.48.0\n\n"},{"id":"510381","messageId":"64913dd3-f336-4e65-8694-2392fa7a049c@app.fastmail.com","threadId":"62793","inReplyTo":"e5b20f9ceb437a82c422136cb81b05a0521cab07.1736682716.git.code@khaugsbakk.name","subject":"Re: [PATCH v2] Revert \"doc: move git-cherry to plumbing\"","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-01-12T12:30:28Z","receivedAt":"2025-01-12T12:30:50Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"I forgot in-reply-to:\n\n\n\n-- \nKristoffer\n"},{"id":"510432","messageId":"xmqqv7uiac0m.fsf@gitster.g","threadId":"62793","inReplyTo":"e5b20f9ceb437a82c422136cb81b05a0521cab07.1736682716.git.code@khaugsbakk.name","subject":"Re: [PATCH v2] Revert \"doc: move git-cherry to plumbing\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-13T16:56:09Z","receivedAt":"2025-01-13T16:56:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> This reverts commit 61018fe9e005a54e18184481927519d64035220a.\n>\n> git-cherry(1) is a high level command for checking what commits have and\n> have not been applied to some other branch. Or at least as high level\n> as the git(1) suite offers. In other words:\n>\n> • it is a useful interrogator for a particular workflow; and\n> • there are no higher level commands on offer.\n>\n> By contrast its use for scripting is somewhat narrow since it only\n> prints the patch application status and the hashes of the downstream\n> branch (not also the upstream branch equivalents). git-patch-id(1)\n> gives a fuller picture by printing each hash and its corresponding\n> patch id.\n>\n> Now this command is not nearly as convenient for the purpose of deleting\n> a *merged* branch as:\n>\n> git branch -d \n>\n> Since that command will refuse to delete the branch if the commits are\n> not in the configured upstream ref. But again it is the most convenient\n> command for the patch workflow.\n>\n> This command might only be considered plumbing by way of the plumbing\n> contract that says that plumbing commands have stable output. But\n> hopefully listing this command as Porcelain does not give the impression\n> that the output is not stable. Output stability was in any case not the\n> motivation for moving this command to plumbing.\n\nI do not follow the above reasoning at all.\n\nIt is not like it is a crime to intarctively make use of a plumbing\ncommand, or we intentionally try to hide plumbing command from them\nby making it deliberately less accessible. \"git cat-file commit X\"\nmay be handier than \"git show -s X\" for some people and that is not\nto be frowned upon.\n\nAnd what you call \"might only be\" is really the crucial thing to\nconsider. If we want to keep a tool's output stable and machine\nreadable, we need to mark it as \"meant for Porcelain writers\", and\nclassifying the tool as plumbing is a pretty much established way to\ndo so.\n"},{"id":"510489","messageId":"b0a3889a-9d7f-4663-bb00-b1b457931fcb@app.fastmail.com","threadId":"62793","inReplyTo":"xmqqv7uiac0m.fsf@gitster.g","subject":"Re: [PATCH v2] Revert \"doc: move git-cherry to plumbing\"","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-01-14T10:24:53Z","receivedAt":"2025-01-14T10:25:15Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Mon, Jan 13, 2025, at 17:56, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>> This command might only be considered plumbing by way of the plumbing\n>> contract that says that plumbing commands have stable output. But\n>> hopefully listing this command as Porcelain does not give the impression\n>> that the output is not stable. Output stability was in any case not the\n>> motivation for moving this command to plumbing.\n>\n> I do not follow the above reasoning at all.\n>\n> It is not like it is a crime to intarctively make use of a plumbing\n> command, or we intentionally try to hide plumbing command from them\n> by making it deliberately less accessible. \"git cat-file commit X\"\n> may be handier than \"git show -s X\" for some people and that is not\n> to be frowned upon.\n>\n> And what you call \"might only be\" is really the crucial thing to\n> consider. If we want to keep a tool's output stable and machine\n> readable, we need to mark it as \"meant for Porcelain writers\", and\n> classifying the tool as plumbing is a pretty much established way to\n> do so.\n\nOkay. I understand now.\n\n-- \nKristoffer\n"},{"id":"510527","messageId":"xmqqwmex47ub.fsf@gitster.g","threadId":"62793","inReplyTo":"b0a3889a-9d7f-4663-bb00-b1b457931fcb@app.fastmail.com","subject":"Re: [PATCH v2] Revert \"doc: move git-cherry to plumbing\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-14T17:35:08Z","receivedAt":"2025-01-14T17:35:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Mon, Jan 13, 2025, at 17:56, Junio C Hamano wrote:\n>\n>> It is not like it is a crime to intarctively make use of a plumbing\n>> command, or we intentionally try to hide plumbing command from them\n>> by making it deliberately less accessible. \"git cat-file commit X\"\n>> may be handier than \"git show -s X\" for some people and that is not\n>> to be frowned upon.\n>>\n>> And what you call \"might only be\" is really the crucial thing to\n>> consider. If we want to keep a tool's output stable and machine\n>> readable, we need to mark it as \"meant for Porcelain writers\", and\n>> classifying the tool as plumbing is a pretty much established way to\n>> do so.\n>\n> Okay. I understand now.\n\nI forgot to mention one thing worth addressing in your message,\nthough. Making the tool more discoverable. It is a valuable\nconsideration.\n\nBut I somehow think moving a tool between plumbing and Porcelain\nboundary is not the way to do so.\n\nThere is a collection of \"howto\" articles in Documentation/howto/\nthat is meant to be the place to learn how to go from workflow and\nobjective to tools. If you have a success story that your use of\n\"git cherry\" helped greatly what you wanted to achieve, it may be a\ngood place to share it.\n\nThanks.\n"}]}