Re: [PATCH v2] Revamp git-cherry(1)
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:59:18
Thomas Rast [off-list ref] writes:
NAME ---- +git-cherry - Find commits not applied in upstream +Determine whether there are commits in `<head>..<upstream>` that are +equivalent to those in the range `<limit>..<head>`. +The equivalence test is based on the diff, after removing whitespace +and line numbers. git-cherry therefore detects when commits have been +"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or +linkgit:git-rebase[1]. +Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with +`-` for commits that have an equivalent in <upstream>, and `+` for +commits that do not.
Thanks, this reads really much better than tha original. We are listing those that need to be added to the upstream with "+", while listing those that can be dropped from yours if you rebase with "-". Hinting the rationale behind the choice of "+/-" somewhere may help as a mnemonic to the readers (see below).
+EXAMPLES +-------- + +Patch workflows +~~~~~~~~~~~~~~~ + +git-cherry is frequently used in patch-based workflows (see +linkgit:gitworkflows[7]) to determine if a series of patches has been +applied by the upstream maintainer. In such a workflow you might +create and send a topic branch like this: + +------------ +$ git checkout -b topic origin/master +# work and create some commits +$ git format-patch origin/master +$ git send-email ... 00* +------------ +Later, you can see whether your changes have been applied by saying +(still on `topic`):
Perhaps we want a blank line before "Later, ..." to be consistent with all the other displayed examples here (I'll squash it locally before queuing), even though AsciiDoc seems to format this just fine.
+ +------------ +$ git fetch # update your notion of origin/master +$ git cherry -v +------------ + +Concrete example +~~~~~~~~~~~~~~~~
"A concrete example", perhaps? I dunno.
+In a situation where topic consisted of three commits, and the +maintainer applied two of them, the situation might look like: + +------------ +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +|/ +o 1234567 branch point +------------ + +In such cases, git-cherry shows a concise summary of what has been +applied:
It shows a concise summary of "what has yet to be applied" (to be consistent with the one-line description in the NAME section).
+------------ +$ git cherry origin/master topic +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +------------
And the earlier "why +/-" could be done after this picture, perhaps like: Here, we see that the commits A and C (marked with `-`) can be dropped from your `topic` branch when you rebase it on top of `origin/master`, while the commit B (marked with `+`) still needs to be kept so that it will be sent to be applied to `origin/master`. or somesuch?