[thirdparty/git.git] / Documentation / git-cherry.txt

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
Commit	Line	Data
7fc9d69f JH	1	git-cherry(1)
	2	=============
	3
	4	NAME
	5	----
7c801fbc	6	git-cherry - Find commits yet to be applied to upstream
7fc9d69f JH	7
	8	SYNOPSIS
	9	--------
7791a1d9	10	[verse]
3bc52d7a	11	'git cherry' [-v] [<upstream> [<head> [<limit>]]]
7fc9d69f JH	12
	13	DESCRIPTION
	14	-----------
7c801fbc TR	15	Determine whether there are commits in `<head>..<upstream>` that are
7c801fbc TR	16	equivalent to those in the range `<limit>..<head>`.
81ae43cd	17
7c801fbc TR	18	The equivalence test is based on the diff, after removing whitespace
	19	and line numbers. git-cherry therefore detects when commits have been
	20	"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or
	21	linkgit:git-rebase[1].
81ae43cd	22
7c801fbc TR	23	Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with
	24	`-` for commits that have an equivalent in <upstream>, and `+` for
	25	commits that do not.
7fc9d69f JH	26
	27	OPTIONS
	28	-------
52a22d1e	29	-v::
7c801fbc	30	Show the commit subjects next to the SHA1s.
7fc9d69f	31
52a22d1e	32	<upstream>::
7c801fbc TR	33	Upstream branch to search for equivalent commits.
7c801fbc TR	34	Defaults to the upstream branch of HEAD.
7fc9d69f	35
52a22d1e LAS	36	<head>::
52a22d1e LAS	37	Working branch; defaults to HEAD.
7fc9d69f	38
6894f49f LFC	39	<limit>::
	40	Do not report commits up to (and including) limit.
	41
7c801fbc TR	42	EXAMPLES
	43	--------
	44
	45	Patch workflows
	46	~~~~~~~~~~~~~~~
	47
	48	git-cherry is frequently used in patch-based workflows (see
	49	linkgit:gitworkflows[7]) to determine if a series of patches has been
	50	applied by the upstream maintainer. In such a workflow you might
	51	create and send a topic branch like this:
	52
	53	------------
	54	$ git checkout -b topic origin/master
	55	# work and create some commits
	56	$ git format-patch origin/master
	57	$ git send-email ... 00*
	58	------------
	59
	60	Later, you can see whether your changes have been applied by saying
	61	(still on `topic`):
	62
	63	------------
	64	$ git fetch # update your notion of origin/master
	65	$ git cherry -v
	66	------------
	67
	68	Concrete example
	69	~~~~~~~~~~~~~~~~
	70
	71	In a situation where topic consisted of three commits, and the
	72	maintainer applied two of them, the situation might look like:
	73
	74	------------
	75	$ git log --graph --oneline --decorate --boundary origin/master...topic
	76	* 7654321 (origin/master) upstream tip commit
	77	[... snip some other commits ...]
	78	* cccc111 cherry-pick of C
	79	* aaaa111 cherry-pick of A
	80	[... snip a lot more that has happened ...]
	81	\| * cccc000 (topic) commit C
	82	\| * bbbb000 commit B
	83	\| * aaaa000 commit A
	84	\|/
	85	o 1234567 branch point
	86	------------
	87
	88	In such cases, git-cherry shows a concise summary of what has yet to
	89	be applied:
	90
	91	------------
	92	$ git cherry origin/master topic
	93	- cccc000... commit C
	94	+ bbbb000... commit B
	95	- aaaa000... commit A
	96	------------
	97
	98	Here, we see that the commits A and C (marked with `-`) can be
	99	dropped from your `topic` branch when you rebase it on top of
	100	`origin/master`, while the commit B (marked with `+`) still needs to
	101	be kept so that it will be sent to be applied to `origin/master`.
	102
	103
	104	Using a limit
	105	~~~~~~~~~~~~~
106
107	The optional <limit> is useful in cases where your topic is based on
108	other work that is not in upstream. Expanding on the previous
109	example, this might look like:
110
111	------------
112	$ git log --graph --oneline --decorate --boundary origin/master...topic
113	* 7654321 (origin/master) upstream tip commit
114	[... snip some other commits ...]
115	* cccc111 cherry-pick of C
116	* aaaa111 cherry-pick of A
117	[... snip a lot more that has happened ...]
118	\| * cccc000 (topic) commit C
119	\| * bbbb000 commit B
120	\| * aaaa000 commit A
121	\| * 0000fff (base) unpublished stuff F
122	[... snip ...]
123	\| * 0000aaa unpublished stuff A
124	\|/
125	o 1234567 merge-base between upstream and topic
126	------------
127
128	By specifying `base` as the limit, you can avoid listing commits
129	between `base` and `topic`:
130
131	------------
132	$ git cherry origin/master topic base
133	- cccc000... commit C
134	+ bbbb000... commit B
135	- aaaa000... commit A
136	------------
137
138
a7052d35 JH	139	SEE ALSO
	140	--------
	141	linkgit:git-patch-id[1]
	142
7fc9d69f JH	143	GIT
7fc9d69f JH	144	---
9e1f0a85	145	Part of the linkgit:git[1] suite