145 lines
3.5 KiB
Text
145 lines
3.5 KiB
Text
git-cherry(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
git-cherry - Find commits yet to be applied to upstream
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git cherry' [-v] [<upstream> [<head> [<limit>]]]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
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.
|
|
|
|
OPTIONS
|
|
-------
|
|
-v::
|
|
Show the commit subjects next to the SHA1s.
|
|
|
|
<upstream>::
|
|
Upstream branch to search for equivalent commits.
|
|
Defaults to the upstream branch of HEAD.
|
|
|
|
<head>::
|
|
Working branch; defaults to HEAD.
|
|
|
|
<limit>::
|
|
Do not report commits up to (and including) limit.
|
|
|
|
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`):
|
|
|
|
------------
|
|
$ git fetch # update your notion of origin/master
|
|
$ git cherry -v
|
|
------------
|
|
|
|
Concrete example
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
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 yet to
|
|
be applied:
|
|
|
|
------------
|
|
$ git cherry origin/master topic
|
|
- cccc000... commit C
|
|
+ bbbb000... commit B
|
|
- aaaa000... commit A
|
|
------------
|
|
|
|
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`.
|
|
|
|
|
|
Using a limit
|
|
~~~~~~~~~~~~~
|
|
|
|
The optional <limit> is useful in cases where your topic is based on
|
|
other work that is not in upstream. Expanding on the previous
|
|
example, this 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
|
|
| * 0000fff (base) unpublished stuff F
|
|
[... snip ...]
|
|
| * 0000aaa unpublished stuff A
|
|
|/
|
|
o 1234567 merge-base between upstream and topic
|
|
------------
|
|
|
|
By specifying `base` as the limit, you can avoid listing commits
|
|
between `base` and `topic`:
|
|
|
|
------------
|
|
$ git cherry origin/master topic base
|
|
- cccc000... commit C
|
|
+ bbbb000... commit B
|
|
- aaaa000... commit A
|
|
------------
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-patch-id[1]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|