Documentation/git-cherry.txt - git - Git at Google

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