Merge branch 'po/range-doc' into maint
Clarify various ways to specify the "revision ranges" in the documentation. * po/range-doc: doc: revisions: sort examples and fix alignment of the unchanged doc: revisions: show revision expansion in examples doc: revisions - clarify reachability examples doc: revisions - define `reachable` doc: gitrevisions - clarify 'latter case' is revision walk doc: gitrevisions - use 'reachable' in page description doc: revisions: single vs multi-parent notation comparison doc: revisions: extra clarification of <rev>^! notation effects doc: revisions: give headings for the two and three dot notations doc: show the actual left, right, and boundary marks doc: revisions - name the left and right sides doc: use 'symmetric difference' consistently
This commit is contained in:
Junio C Hamano
commit
f0b2db228b
@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
|
||||
|
||||
--left-right::
|
||||
|
||||
Mark which side of a symmetric diff a commit is reachable
|
||||
Mark which side of a symmetric difference a commit is reachable
|
||||
from. Commits from the left side are prefixed with a `<`
|
||||
symbol and those from the right with a `>` symbol.
|
||||
|
||||
|
||||
@ -15,9 +15,9 @@ DESCRIPTION
|
||||
|
||||
Many Git commands take revision parameters as arguments. Depending on
|
||||
the command, they denote a specific commit or, for commands which
|
||||
walk the revision graph (such as linkgit:git-log[1]), all commits which can
|
||||
be reached from that commit. In the latter case one can also specify a
|
||||
range of revisions explicitly.
|
||||
walk the revision graph (such as linkgit:git-log[1]), all commits which are
|
||||
reachable from that commit. For commands that walk the revision graph one can
|
||||
also specify a range of revisions explicitly.
|
||||
|
||||
In addition, some Git commands (such as linkgit:git-show[1]) also take
|
||||
revision parameters which denote other objects than commits, e.g. blobs
|
||||
|
||||
@ -172,7 +172,7 @@ endif::git-rev-list[]
|
||||
respecting the `auto` settings of the former if we are going to a
|
||||
terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
|
||||
on the next placeholders until the color is switched again.
|
||||
- '%m': left, right or boundary mark
|
||||
- '%m': left (`<`), right (`>`) or boundary (`-`) mark
|
||||
- '%n': newline
|
||||
- '%%': a raw '%'
|
||||
- '%x00': print a byte from a hex code
|
||||
|
||||
@ -225,7 +225,7 @@ excluded from the output.
|
||||
|
||||
--left-only::
|
||||
--right-only::
|
||||
List only commits on the respective side of a symmetric range,
|
||||
List only commits on the respective side of a symmetric difference,
|
||||
i.e. only those which would be marked `<` resp. `>` by
|
||||
`--left-right`.
|
||||
+
|
||||
@ -796,7 +796,7 @@ ifdef::git-rev-list[]
|
||||
endif::git-rev-list[]
|
||||
|
||||
--left-right::
|
||||
Mark which side of a symmetric diff a commit is reachable from.
|
||||
Mark which side of a symmetric difference a commit is reachable from.
|
||||
Commits from the left side are prefixed with `<` and those from
|
||||
the right with `>`. If combined with `--boundary`, those
|
||||
commits are prefixed with `-`.
|
||||
|
||||
@ -237,48 +237,74 @@ SPECIFYING RANGES
|
||||
-----------------
|
||||
|
||||
History traversing commands such as `git log` operate on a set
|
||||
of commits, not just a single commit. To these commands,
|
||||
specifying a single revision with the notation described in the
|
||||
previous section means the set of commits reachable from that
|
||||
commit, following the commit ancestry chain.
|
||||
of commits, not just a single commit.
|
||||
|
||||
To exclude commits reachable from a commit, a prefix '{caret}'
|
||||
notation is used. E.g. '{caret}r1 r2' means commits reachable
|
||||
from 'r2' but exclude the ones reachable from 'r1'.
|
||||
For these commands,
|
||||
specifying a single revision, using the notation described in the
|
||||
previous section, means the set of commits `reachable` from the given
|
||||
commit.
|
||||
|
||||
This set operation appears so often that there is a shorthand
|
||||
for it. When you have two commits 'r1' and 'r2' (named according
|
||||
to the syntax explained in SPECIFYING REVISIONS above), you can ask
|
||||
for commits that are reachable from r2 excluding those that are reachable
|
||||
from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
|
||||
A commit's reachable set is the commit itself and the commits in
|
||||
its ancestry chain.
|
||||
|
||||
A similar notation 'r1\...r2' is called symmetric difference
|
||||
of 'r1' and 'r2' and is defined as
|
||||
'r1 r2 --not $(git merge-base --all r1 r2)'.
|
||||
It is the set of commits that are reachable from either one of
|
||||
'r1' or 'r2' but not from both.
|
||||
|
||||
In these two shorthands, you can omit one end and let it default to HEAD.
|
||||
Commit Exclusions
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
'{caret}<rev>' (caret) Notation::
|
||||
To exclude commits reachable from a commit, a prefix '{caret}'
|
||||
notation is used. E.g. '{caret}r1 r2' means commits reachable
|
||||
from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and
|
||||
its ancestors).
|
||||
|
||||
Dotted Range Notations
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The '..' (two-dot) Range Notation::
|
||||
The '{caret}r1 r2' set operation appears so often that there is a shorthand
|
||||
for it. When you have two commits 'r1' and 'r2' (named according
|
||||
to the syntax explained in SPECIFYING REVISIONS above), you can ask
|
||||
for commits that are reachable from r2 excluding those that are reachable
|
||||
from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
|
||||
|
||||
The '...' (three dot) Symmetric Difference Notation::
|
||||
A similar notation 'r1\...r2' is called symmetric difference
|
||||
of 'r1' and 'r2' and is defined as
|
||||
'r1 r2 --not $(git merge-base --all r1 r2)'.
|
||||
It is the set of commits that are reachable from either one of
|
||||
'r1' (left side) or 'r2' (right side) but not from both.
|
||||
|
||||
In these two shorthand notations, you can omit one end and let it default to HEAD.
|
||||
For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
|
||||
did I do since I forked from the origin branch?" Similarly, '..origin'
|
||||
is a shorthand for 'HEAD..origin' and asks "What did the origin do since
|
||||
I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an
|
||||
empty range that is both reachable and unreachable from HEAD.
|
||||
|
||||
Two other shorthands for naming a set that is formed by a commit
|
||||
and its parent commits exist. The 'r1{caret}@' notation means all
|
||||
parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes
|
||||
all of its parents.
|
||||
Other <rev>{caret} Parent Shorthand Notations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Two other shorthands exist, particularly useful for merge commits,
|
||||
for naming a set that is formed by a commit and its parent commits.
|
||||
|
||||
To summarize:
|
||||
The 'r1{caret}@' notation means all parents of 'r1'.
|
||||
|
||||
The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
|
||||
By itself, this notation denotes the single commit 'r1'.
|
||||
|
||||
While '<rev>{caret}<n>' was about specifying a single commit parent, these
|
||||
two notations consider all its parents. For example you can say
|
||||
'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.
|
||||
|
||||
Revision Range Summary
|
||||
----------------------
|
||||
|
||||
'<rev>'::
|
||||
Include commits that are reachable from (i.e. ancestors of)
|
||||
<rev>.
|
||||
Include commits that are reachable from <rev> (i.e. <rev> and its
|
||||
ancestors).
|
||||
|
||||
'{caret}<rev>'::
|
||||
Exclude commits that are reachable from (i.e. ancestors of)
|
||||
<rev>.
|
||||
Exclude commits that are reachable from <rev> (i.e. <rev> and its
|
||||
ancestors).
|
||||
|
||||
'<rev1>..<rev2>'::
|
||||
Include commits that are reachable from <rev2> but exclude
|
||||
@ -300,16 +326,27 @@ To summarize:
|
||||
as giving commit '<rev>' and then all its parents prefixed with
|
||||
'{caret}' to exclude them (and their ancestors).
|
||||
|
||||
Here are a handful of examples:
|
||||
Here are a handful of examples using the Loeliger illustration above,
|
||||
with each step in the notation's expansion and selection carefully
|
||||
spelt out:
|
||||
|
||||
Args Expanded arguments Selected commits
|
||||
D G H D
|
||||
D F G H I J D F
|
||||
^G D H D
|
||||
^D B E I J F B
|
||||
B..C C
|
||||
B...C G H D E B C
|
||||
^D B C E I J F B C
|
||||
C I J F C
|
||||
C^@ I J F
|
||||
C^! C
|
||||
F^! D G H D F
|
||||
B..C = ^B C C
|
||||
B...C = B ^F C G H D E B C
|
||||
C^@ = C^1
|
||||
= F I J F
|
||||
B^@ = B^1 B^2 B^3
|
||||
= D E F D G H E F I J
|
||||
C^! = C ^C^@
|
||||
= C ^C^1
|
||||
= C ^F C
|
||||
B^! = B ^B^@
|
||||
= B ^B^1 ^B^2 ^B^3
|
||||
= B ^D ^E ^F B
|
||||
F^! D = F ^I ^J D G H D F
|
||||
|
||||
Loading…
Reference in New Issue
Block a user