diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:49:36 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:49:36 +0000 |
commit | 5ec6074f0633939fd17d94111d10c6c6b062978c (patch) | |
tree | bfaa17b5a64abc66c918e9c70969e519d9e1df8e /Documentation/git-cherry.txt | |
parent | Initial commit. (diff) | |
download | git-upstream.tar.xz git-upstream.zip |
Adding upstream version 1:2.30.2.upstream/1%2.30.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'Documentation/git-cherry.txt')
-rw-r--r-- | Documentation/git-cherry.txt | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt new file mode 100644 index 0000000..0ea921a --- /dev/null +++ b/Documentation/git-cherry.txt @@ -0,0 +1,145 @@ +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 |