Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 1 | git-cherry(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [diff] [blame] | 6 | git-cherry - Find commits yet to be applied to upstream |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
Martin von Zweigbergk | 7791a1d | 2011-07-01 22:38:26 -0400 | [diff] [blame] | 10 | [verse] |
Markus Heidelberg | 3bc52d7 | 2009-01-01 22:56:29 +0100 | [diff] [blame] | 11 | 'git cherry' [-v] [<upstream> [<head> [<limit>]]] |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [diff] [blame] | 15 | Determine whether there are commits in `<head>..<upstream>` that are |
| 16 | equivalent to those in the range `<limit>..<head>`. |
sean | 81ae43c | 2006-05-05 15:06:07 -0400 | [diff] [blame] | 17 | |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [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]. |
Rene Scharfe | a8ebdb9 | 2006-10-26 23:32:41 +0200 | [diff] [blame] | 22 | |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [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 | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 26 | |
| 27 | OPTIONS |
| 28 | ------- |
A Large Angry SCM | 52a22d1 | 2005-08-26 18:18:48 -0700 | [diff] [blame] | 29 | -v:: |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [diff] [blame] | 30 | Show the commit subjects next to the SHA1s. |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 31 | |
A Large Angry SCM | 52a22d1 | 2005-08-26 18:18:48 -0700 | [diff] [blame] | 32 | <upstream>:: |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [diff] [blame] | 33 | Upstream branch to search for equivalent commits. |
| 34 | Defaults to the upstream branch of HEAD. |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 35 | |
A Large Angry SCM | 52a22d1 | 2005-08-26 18:18:48 -0700 | [diff] [blame] | 36 | <head>:: |
| 37 | Working branch; defaults to HEAD. |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 38 | |
Luiz Fernando N. Capitulino | 6894f49 | 2007-06-11 09:56:56 -0300 | [diff] [blame] | 39 | <limit>:: |
| 40 | Do not report commits up to (and including) limit. |
| 41 | |
Thomas Rast | 7c801fb | 2013-11-22 17:29:16 +0100 | [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 | a7052d3 | 2008-05-28 17:03:46 -0700 | [diff] [blame] | 139 | SEE ALSO |
| 140 | -------- |
| 141 | linkgit:git-patch-id[1] |
| 142 | |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 143 | GIT |
| 144 | --- |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 145 | Part of the linkgit:git[1] suite |