mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
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:
commit
f0b2db228b
|
@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
|
||||||
|
|
||||||
--left-right::
|
--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 `<`
|
from. Commits from the left side are prefixed with a `<`
|
||||||
symbol and those from the right with a `>` symbol.
|
symbol and those from the right with a `>` symbol.
|
||||||
|
|
||||||
|
|
|
@ -15,9 +15,9 @@ DESCRIPTION
|
||||||
|
|
||||||
Many Git commands take revision parameters as arguments. Depending on
|
Many Git commands take revision parameters as arguments. Depending on
|
||||||
the command, they denote a specific commit or, for commands which
|
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
|
walk the revision graph (such as linkgit:git-log[1]), all commits which are
|
||||||
be reached from that commit. In the latter case one can also specify a
|
reachable from that commit. For commands that walk the revision graph one can
|
||||||
range of revisions explicitly.
|
also specify a range of revisions explicitly.
|
||||||
|
|
||||||
In addition, some Git commands (such as linkgit:git-show[1]) also take
|
In addition, some Git commands (such as linkgit:git-show[1]) also take
|
||||||
revision parameters which denote other objects than commits, e.g. blobs
|
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
|
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
|
terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
|
||||||
on the next placeholders until the color is switched again.
|
on the next placeholders until the color is switched again.
|
||||||
- '%m': left, right or boundary mark
|
- '%m': left (`<`), right (`>`) or boundary (`-`) mark
|
||||||
- '%n': newline
|
- '%n': newline
|
||||||
- '%%': a raw '%'
|
- '%%': a raw '%'
|
||||||
- '%x00': print a byte from a hex code
|
- '%x00': print a byte from a hex code
|
||||||
|
|
|
@ -225,7 +225,7 @@ excluded from the output.
|
||||||
|
|
||||||
--left-only::
|
--left-only::
|
||||||
--right-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
|
i.e. only those which would be marked `<` resp. `>` by
|
||||||
`--left-right`.
|
`--left-right`.
|
||||||
+
|
+
|
||||||
|
@ -796,7 +796,7 @@ ifdef::git-rev-list[]
|
||||||
endif::git-rev-list[]
|
endif::git-rev-list[]
|
||||||
|
|
||||||
--left-right::
|
--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
|
Commits from the left side are prefixed with `<` and those from
|
||||||
the right with `>`. If combined with `--boundary`, those
|
the right with `>`. If combined with `--boundary`, those
|
||||||
commits are prefixed with `-`.
|
commits are prefixed with `-`.
|
||||||
|
|
|
@ -237,48 +237,74 @@ SPECIFYING RANGES
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
History traversing commands such as `git log` operate on a set
|
History traversing commands such as `git log` operate on a set
|
||||||
of commits, not just a single commit. To these commands,
|
of commits, not just a single commit.
|
||||||
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.
|
|
||||||
|
|
||||||
To exclude commits reachable from a commit, a prefix '{caret}'
|
For these commands,
|
||||||
notation is used. E.g. '{caret}r1 r2' means commits reachable
|
specifying a single revision, using the notation described in the
|
||||||
from 'r2' but exclude the ones reachable from 'r1'.
|
previous section, means the set of commits `reachable` from the given
|
||||||
|
commit.
|
||||||
|
|
||||||
This set operation appears so often that there is a shorthand
|
A commit's reachable set is the commit itself and the commits in
|
||||||
for it. When you have two commits 'r1' and 'r2' (named according
|
its ancestry chain.
|
||||||
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 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
|
For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
|
||||||
did I do since I forked from the origin branch?" Similarly, '..origin'
|
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
|
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
|
I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an
|
||||||
empty range that is both reachable and unreachable from HEAD.
|
empty range that is both reachable and unreachable from HEAD.
|
||||||
|
|
||||||
Two other shorthands for naming a set that is formed by a commit
|
Other <rev>{caret} Parent Shorthand Notations
|
||||||
and its parent commits exist. The 'r1{caret}@' notation means all
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes
|
Two other shorthands exist, particularly useful for merge commits,
|
||||||
all of its parents.
|
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>'::
|
'<rev>'::
|
||||||
Include commits that are reachable from (i.e. ancestors of)
|
Include commits that are reachable from <rev> (i.e. <rev> and its
|
||||||
<rev>.
|
ancestors).
|
||||||
|
|
||||||
'{caret}<rev>'::
|
'{caret}<rev>'::
|
||||||
Exclude commits that are reachable from (i.e. ancestors of)
|
Exclude commits that are reachable from <rev> (i.e. <rev> and its
|
||||||
<rev>.
|
ancestors).
|
||||||
|
|
||||||
'<rev1>..<rev2>'::
|
'<rev1>..<rev2>'::
|
||||||
Include commits that are reachable from <rev2> but exclude
|
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
|
as giving commit '<rev>' and then all its parents prefixed with
|
||||||
'{caret}' to exclude them (and their ancestors).
|
'{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 G H D
|
||||||
D F G H I J D F
|
D F G H I J D F
|
||||||
^G D H D
|
^G D H D
|
||||||
^D B E I J F B
|
^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
|
^D B C E I J F B C
|
||||||
C I J F C
|
C I J F C
|
||||||
C^@ I J F
|
B..C = ^B C C
|
||||||
C^! C
|
B...C = B ^F C G H D E B C
|
||||||
F^! D G H D F
|
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 a new issue