diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 14:47:53 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 14:47:53 +0000 |
| commit | c8bae7493d2f2910b57f13ded012e86bdcfb0532 (patch) | |
| tree | 24e09d9f84dec336720cf393e156089ca2835791 /Documentation/git-cherry.txt | |
| parent | Initial commit. (diff) | |
| download | git-upstream.tar.xz git-upstream.zip | |
Adding upstream version 1:2.39.2.upstream/1%2.39.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 |