summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/gitk.txt2
-rw-r--r--Documentation/gitrevisions.txt6
-rw-r--r--Documentation/pretty-formats.txt2
-rw-r--r--Documentation/rev-list-options.txt4
-rw-r--r--Documentation/revisions.txt125
5 files changed, 88 insertions, 51 deletions
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index a68d860fa3..e382dd96df 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -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.
diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index e903eb7860..27dec5b91d 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -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
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index b95d67ec01..a942d57f73 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -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
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index a779c9dfec..7e462d3841 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -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 `-`.
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index abae363983..4bed5b1ab7 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -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.
-
-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'.
-
-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 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.
+of commits, not just a single commit.
+
+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.
+
+A commit's reachable set is the commit itself and the commits in
+its ancestry chain.
+
+
+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.
+
+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'.
-To summarize:
+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:
-
- 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
+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
+ ^D B C E I J F B C
+ C I J F C
+ 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