logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-cherry.1 (5269B)

    

  1. '\" t
  2. .\"     Title: git-cherry
  3. .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\"      Date: 2025-03-14
  6. .\"    Manual: Git Manual
  7. .\"    Source: Git 2.49.0
  8. .\"  Language: English
  9. .\"
  10. .TH "GIT\-CHERRY" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el       .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. git-cherry \- Find commits yet to be applied to upstream
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. \fIgit cherry\fR [\-v] [<upstream> [<head> [<limit>]]]
  36. .fi
  37. .SH "DESCRIPTION"
  38. .sp
  39. Determine whether there are commits in \fI<head>\fR\fB\&.\&.\fR\fI<upstream>\fR that are equivalent to those in the range \fI<limit>\fR\fB\&.\&.\fR\fI<head>\fR\&.
  40. .sp
  41. 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 \fBgit-cherry-pick\fR(1), \fBgit-am\fR(1) or \fBgit-rebase\fR(1)\&.
  42. .sp
  43. Outputs the SHA1 of every commit in \fI<limit>\fR\fB\&.\&.\fR\fI<head>\fR, prefixed with \fB\-\fR for commits that have an equivalent in <upstream>, and \fB+\fR for commits that do not\&.
  44. .SH "OPTIONS"
  45. .PP
  46. \-v
  47. .RS 4
  48. Show the commit subjects next to the SHA1s\&.
  49. .RE
  50. .PP
  51. <upstream>
  52. .RS 4
  53. Upstream branch to search for equivalent commits\&. Defaults to the upstream branch of HEAD\&.
  54. .RE
  55. .PP
  56. <head>
  57. .RS 4
  58. Working branch; defaults to HEAD\&.
  59. .RE
  60. .PP
  61. <limit>
  62. .RS 4
  63. Do not report commits up to (and including) limit\&.
  64. .RE
  65. .SH "EXAMPLES"
  66. .SS "Patch workflows"
  67. .sp
  68. git\-cherry is frequently used in patch\-based workflows (see \fBgitworkflows\fR(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:
  69. .sp
  70. .if n \{\
  71. .RS 4
  72. .\}
  73. .nf
  74. $ git checkout \-b topic origin/master
  75. # work and create some commits
  76. $ git format\-patch origin/master
  77. $ git send\-email \&.\&.\&. 00*
  78. .fi
  79. .if n \{\
  80. .RE
  81. .\}
  82. .sp
  83. Later, you can see whether your changes have been applied by saying (still on \fBtopic\fR):
  84. .sp
  85. .if n \{\
  86. .RS 4
  87. .\}
  88. .nf
  89. $ git fetch  # update your notion of origin/master
  90. $ git cherry \-v
  91. .fi
  92. .if n \{\
  93. .RE
  94. .\}
  95. .SS "Concrete example"
  96. .sp
  97. In a situation where topic consisted of three commits, and the maintainer applied two of them, the situation might look like:
  98. .sp
  99. .if n \{\
  100. .RS 4
  101. .\}
  102. .nf
  103. $ git log \-\-graph \-\-oneline \-\-decorate \-\-boundary origin/master\&.\&.\&.topic
  104. * 7654321 (origin/master) upstream tip commit
  105. [\&.\&.\&. snip some other commits \&.\&.\&.]
  106. * cccc111 cherry\-pick of C
  107. * aaaa111 cherry\-pick of A
  108. [\&.\&.\&. snip a lot more that has happened \&.\&.\&.]
  109. | * cccc000 (topic) commit C
  110. | * bbbb000 commit B
  111. | * aaaa000 commit A
  112. |/
  113. o 1234567 branch point
  114. .fi
  115. .if n \{\
  116. .RE
  117. .\}
  118. .sp
  119. In such cases, git\-cherry shows a concise summary of what has yet to be applied:
  120. .sp
  121. .if n \{\
  122. .RS 4
  123. .\}
  124. .nf
  125. $ git cherry origin/master topic
  126. \- cccc000\&.\&.\&. commit C
  127. + bbbb000\&.\&.\&. commit B
  128. \- aaaa000\&.\&.\&. commit A
  129. .fi
  130. .if n \{\
  131. .RE
  132. .\}
  133. .sp
  134. Here, we see that the commits A and C (marked with \fB\-\fR) can be dropped from your \fBtopic\fR branch when you rebase it on top of \fBorigin/master\fR, while the commit B (marked with \fB+\fR) still needs to be kept so that it will be sent to be applied to \fBorigin/master\fR\&.
  135. .SS "Using a limit"
  136. .sp
  137. 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:
  138. .sp
  139. .if n \{\
  140. .RS 4
  141. .\}
  142. .nf
  143. $ git log \-\-graph \-\-oneline \-\-decorate \-\-boundary origin/master\&.\&.\&.topic
  144. * 7654321 (origin/master) upstream tip commit
  145. [\&.\&.\&. snip some other commits \&.\&.\&.]
  146. * cccc111 cherry\-pick of C
  147. * aaaa111 cherry\-pick of A
  148. [\&.\&.\&. snip a lot more that has happened \&.\&.\&.]
  149. | * cccc000 (topic) commit C
  150. | * bbbb000 commit B
  151. | * aaaa000 commit A
  152. | * 0000fff (base) unpublished stuff F
  153. [\&.\&.\&. snip \&.\&.\&.]
  154. | * 0000aaa unpublished stuff A
  155. |/
  156. o 1234567 merge\-base between upstream and topic
  157. .fi
  158. .if n \{\
  159. .RE
  160. .\}
  161. .sp
  162. By specifying \fBbase\fR as the limit, you can avoid listing commits between \fBbase\fR and \fBtopic\fR:
  163. .sp
  164. .if n \{\
  165. .RS 4
  166. .\}
  167. .nf
  168. $ git cherry origin/master topic base
  169. \- cccc000\&.\&.\&. commit C
  170. + bbbb000\&.\&.\&. commit B
  171. \- aaaa000\&.\&.\&. commit A
  172. .fi
  173. .if n \{\
  174. .RE
  175. .\}
  176. .SH "SEE ALSO"
  177. .sp
  178. \fBgit-patch-id\fR(1)
  179. .SH "GIT"
  180. .sp
  181. Part of the \fBgit\fR(1) suite