mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: revisions: give headings for the two and three dot notations

Browse Source 
While there, also break out the other shorthand notations and
add a title for the revision range summary (which also appears
in git-rev-parse, so keep it mixed case).

We do not quote the notation within the headings as the asciidoc ->
docbook -> groff man viewer toolchain, particularly the docbook-groff
step, does not cope with two font changes, failing to return the heading
font to bold after the quotation of the notation.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Philip Oakley
2016-08-12 08:07:41 +01:00
committed by Junio C Hamano
parent c6eff44d0d
commit 391a3c70c3
1 changed files with 33 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
Documentation/revisions.txt
View File

@ -241,35 +241,49 @@ specifying a single revision with the notation described in the
previous section means the set of commits reachable from that previous section means the set of commits reachable from that
commit, following the commit ancestry chain. commit, following the commit ancestry chain.
To exclude commits reachable from a commit, a prefix '{caret}' Commit Exclusions
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 '{caret}<rev>' (caret) Notation::
for it. When you have two commits 'r1' and 'r2' (named according To exclude commits reachable from a commit, a prefix '{caret}'
to the syntax explained in SPECIFYING REVISIONS above), you can ask notation is used. E.g. '{caret}r1 r2' means commits reachable
for commits that are reachable from r2 excluding those that are reachable from 'r2' but exclude the ones reachable from 'r1'.
from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
A similar notation 'r1\...r2' is called symmetric difference Dotted Range Notations
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 shorthands, you can omit one end and let it default to HEAD. 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'.
'r1{caret}!' includes commit 'r1' but excludes all of its parents.
Revision Range Summary
----------------------
'<rev>':: '<rev>'::
Include commits that are reachable from (i.e. ancestors of) Include commits that are reachable from (i.e. ancestors of)