Blame - git-cherry.txt - external/gitster/git-htmldocs

blob: 0ea921a5931647f21f74a44a80622c3d3c16827c [file] [log] [blame]

Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	1	git-cherry(1)
				2	=============
				3
				4	NAME
				5	----
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	6	git-cherry - Find commits yet to be applied to upstream
Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	7
				8	SYNOPSIS
				9	--------
Junio C Hamano	15567bc	2011-07-23 00:51:59	[diff] [blame]	10	[verse]
Junio C Hamano	a3148f5	2009-01-14 08:49:57	[diff] [blame]	11	'git cherry' [-v] [<upstream> [<head> [<limit>]]]
Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	12
				13	DESCRIPTION
				14	-----------
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	15	Determine whether there are commits in `<head>..<upstream>` that are
				16	equivalent to those in the range `<limit>..<head>`.
Junio C Hamano	1bb569e	2006-05-05 23:14:25	[diff] [blame]	17
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	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].
Junio C Hamano	a053d54	2006-10-27 09:29:13	[diff] [blame]	22
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	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.
Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	26
				27	OPTIONS
				28	-------
				29	-v::
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	30	Show the commit subjects next to the SHA1s.
Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	31
				32	<upstream>::
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	33	Upstream branch to search for equivalent commits.
				34	Defaults to the upstream branch of HEAD.
Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	35
				36	<head>::
				37	Working branch; defaults to HEAD.
				38
Junio C Hamano	16f9887	2007-06-12 16:09:14	[diff] [blame]	39	<limit>::
				40	Do not report commits up to (and including) limit.
				41
Junio C Hamano	4c8f2d9	2013-12-13 00:55:42	[diff] [blame]	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
Junio C Hamano	9049d91	2008-05-29 02:09:50	[diff] [blame]	139	SEE ALSO
				140	--------
				141	linkgit:git-patch-id[1]
				142
Junio C Hamano	1a4e841	2005-12-27 08:17:23	[diff] [blame]	143	GIT
				144	---
Junio C Hamano	f7c042d	2008-06-06 22:50:53	[diff] [blame]	145	Part of the linkgit:git[1] suite