undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'tr/doc-git-cherry'

Browse Source 
* tr/doc-git-cherry:
  Documentation: revamp git-cherry(1)
This commit is contained in:
Junio C Hamano 2013-12-12 14:18:23 -08:00
commit 71fe59f880
1 changed files with 110 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
Documentation/git-cherry.txt
View File

@ -3,7 +3,7 @@ git-cherry(1)
NAME NAME
---- ----
git-cherry - Find commits not merged upstream git-cherry - Find commits yet to be applied to upstream
SYNOPSIS SYNOPSIS
-------- --------
@ -12,46 +12,26 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
----------- -----------
The changeset (or "diff") of each commit between the fork-point and <head> Determine whether there are commits in `<head>..<upstream>` that are
is compared against each commit between the fork-point and <upstream>. equivalent to those in the range `<limit>..<head>`.
The diffs are compared after removing any whitespace and line numbers.
Every commit that doesn't exist in the <upstream> branch The equivalence test is based on the diff, after removing whitespace
has its id (sha1) reported, prefixed by a symbol. The ones that have and line numbers. git-cherry therefore detects when commits have been
equivalent change already "copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or
in the <upstream> branch are prefixed with a minus (-) sign, and those linkgit:git-rebase[1].
that only exist in the <head> branch are prefixed with a plus (+) symbol:
__*__*__*__*__> <upstream>
/
fork-point
\__+__+__-__+__+__-__+__> <head>
If a <limit> has been given then the commits along the <head> branch up
to and including <limit> are not reported:
__*__*__*__*__> <upstream>
/
fork-point
\__*__*__<limit>__-__+__> <head>
Because 'git cherry' compares the changeset rather than the commit id
(sha1), you can use 'git cherry' to find out if a commit you made locally
has been applied <upstream> under a different commit id. For example,
this will happen if you're feeding patches <upstream> via email rather
than pushing or pulling commits directly.
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 OPTIONS
------- -------
-v:: -v::
Verbose. Show the commit subjects next to the SHA1s.
<upstream>:: <upstream>::
Upstream branch to compare against. Upstream branch to search for equivalent commits.
Defaults to the first tracked remote branch, if available. Defaults to the upstream branch of HEAD.
<head>:: <head>::
Working branch; defaults to HEAD. Working branch; defaults to HEAD.
@ -59,6 +39,103 @@ OPTIONS
<limit>:: <limit>::
Do not report commits up to (and including) 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 SEE ALSO
-------- --------
linkgit:git-patch-id[1] linkgit:git-patch-id[1]