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

Merge branch 'po/range-doc' into maint

Browse Source 
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 2016-09-19 13:51:37 -07:00
commit f0b2db228b
5 changed files with 83 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/gitk.txt
View File

@ -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.

6
Documentation/gitrevisions.txt
View File

@ -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

2
Documentation/pretty-formats.txt
View File

@ -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

4
Documentation/rev-list-options.txt
View File

@ -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 `-`.

115
Documentation/revisions.txt
View File

@ -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:
D G H D Args Expanded arguments Selected commits
D F G H I J D F D G H D
^G D H D D F G H I J D F
^D B E I J F B ^G D H D
B..C C ^D B E I J F B
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 B..C = ^B C C
C^@ I J F B...C = B ^F C G H D E B C
C^! C C^@ = C^1
F^! D G H D F = 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