From 27ac83718cc9ebc98a31eb7f17c0646d78909032 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Wed, 20 Jul 2016 22:10:00 +0100 Subject: doc: use 'symmetric difference' consistently Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/gitk.txt | 2 +- Documentation/rev-list-options.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 6ade00217..6c3eb1582 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/rev-list-options.txt b/Documentation/rev-list-options.txt index f1c52208f..f7645cc72 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`. + @@ -757,7 +757,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 `-`. -- cgit v1.2.1 From b3d3ea0672777e1ce3baf4a8a571a09704eb067e Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Wed, 20 Jul 2016 22:10:01 +0100 Subject: doc: revisions - name the left and right sides The terms left and right side originate from the symmetric difference. Name them there. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index d85e30336..9fcad8a44 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -255,7 +255,7 @@ 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. +'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. For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What -- cgit v1.2.1 From c6eff44d0d6620e06e7b2ffb09e4c0dfe5c687a4 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Wed, 20 Jul 2016 22:10:02 +0100 Subject: doc: show the actual left, right, and boundary marks Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 671cebd95..f4cb0f30b 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -166,7 +166,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 -- cgit v1.2.1 From 391a3c70c3a9597d30b59e32489774f299555bb6 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Fri, 12 Aug 2016 08:07:41 +0100 Subject: doc: revisions: give headings for the two and three dot notations 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 Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 58 ++++++++++++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 22 deletions(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 9fcad8a44..1d1593fbf 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -241,35 +241,49 @@ 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' (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. +Commit Exclusions +~~~~~~~~~~~~~~~~~ + +'{caret}' (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'. + +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 {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'. + +'r1{caret}!' includes commit 'r1' but excludes all of its parents. + +Revision Range Summary +---------------------- '':: Include commits that are reachable from (i.e. ancestors of) -- cgit v1.2.1 From 59841a3900a5670084f30b8ab2bb49042938fee6 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 13 Aug 2016 00:45:19 +0100 Subject: doc: revisions: extra clarification of ^! notation effects Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 1d1593fbf..64bc83eaa 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -280,7 +280,8 @@ for naming a set that is formed by a commit and its parent commits. The 'r1{caret}@' notation means all parents of 'r1'. -'r1{caret}!' includes commit 'r1' but excludes all of its parents. +The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. +By itself, this notation denotes the single commit 'r1'. Revision Range Summary ---------------------- -- cgit v1.2.1 From 39b4d85e5be4b8ab1352d4a24e8fceffb2b5e405 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 13 Aug 2016 00:45:20 +0100 Subject: doc: revisions: single vs multi-parent notation comparison Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 64bc83eaa..f3a53a662 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -283,6 +283,10 @@ 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 '{caret}' 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 ---------------------- -- cgit v1.2.1 From 6cb4f785ae007e0689ba5ce83a9250ebfaea89c2 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Fri, 12 Aug 2016 08:07:44 +0100 Subject: doc: gitrevisions - use 'reachable' in page description Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/gitrevisions.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt index e903eb786..33039c622 100644 --- a/Documentation/gitrevisions.txt +++ b/Documentation/gitrevisions.txt @@ -15,8 +15,8 @@ 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 +walk the revision graph (such as linkgit:git-log[1]), all commits which are +reachable from that commit. In the latter case one can also specify a range of revisions explicitly. In addition, some Git commands (such as linkgit:git-show[1]) also take -- cgit v1.2.1 From 8cf5739426637e43b881aed2a0e9a9fd18e9b245 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Fri, 12 Aug 2016 08:07:45 +0100 Subject: doc: gitrevisions - clarify 'latter case' is revision walk The prior sentence has too many clauses for easy parsing. Replace 'the latter case' with a direct quote. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/gitrevisions.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt index 33039c622..27dec5b91 100644 --- a/Documentation/gitrevisions.txt +++ b/Documentation/gitrevisions.txt @@ -16,8 +16,8 @@ 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 are -reachable from that commit. In the latter case one can also specify a -range of revisions explicitly. +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 -- cgit v1.2.1 From 0b451248b398240c92bc2d48e96d7c3838c12349 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Fri, 12 Aug 2016 08:07:46 +0100 Subject: doc: revisions - define `reachable` Do not self-define `reachable`, which can lead to misunderstanding. Instead define `reachability` explictly. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index f3a53a662..f223a1cc4 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -236,10 +236,16 @@ 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. + +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 ~~~~~~~~~~~~~~~~~ -- cgit v1.2.1 From 1afe13b98a9865c012daffca5d0ac56aced318fb Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Fri, 12 Aug 2016 08:07:47 +0100 Subject: doc: revisions - clarify reachability examples For the r1..r2 case, the exclusion of r1, rather than inclusion of r2, would be the unexpected case in natural language for a simple linear development, i.e. start..end excludes start. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index f223a1cc4..e8120c0a0 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -253,7 +253,8 @@ Commit Exclusions '{caret}' (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'. + from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and + its ancestors). Dotted Range Notations ~~~~~~~~~~~~~~~~~~~~~~ @@ -297,12 +298,12 @@ Revision Range Summary ---------------------- '':: - Include commits that are reachable from (i.e. ancestors of) - . + Include commits that are reachable from (i.e. and its + ancestors). '{caret}':: - Exclude commits that are reachable from (i.e. ancestors of) - . + Exclude commits that are reachable from (i.e. and its + ancestors). '..':: Include commits that are reachable from but exclude -- cgit v1.2.1 From 7a5370e612ca6d5e2f5a3b6835ec7439fb04bd6c Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 13 Aug 2016 00:45:21 +0100 Subject: doc: revisions: show revision expansion in examples The revisions examples show the revison arguments and the selected commits, but do not show the intermediate step of the expansion of the special 'range' notations. Extend the examples, including an all-parents multi-parent merge commit example. Sort the examples and fix the alignment for those unaffected in the next commit. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index e8120c0a0..728bd0959 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -325,16 +325,27 @@ Revision Range Summary as giving commit '' 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 + B..C = ^B C C + B...C = B ^F 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 + 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 -- cgit v1.2.1 From a117be4d34d7b8b13fd6c40791ba78eabecd884b Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Sat, 13 Aug 2016 00:45:22 +0100 Subject: doc: revisions: sort examples and fix alignment of the unchanged The previous commit adjusted the column alignment for revision examples which show expansion. Fix the unchanged examples and sort those that show expansions to the end of the list. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 728bd0959..a7fbcd72c 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -330,14 +330,14 @@ 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 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 - ^D B C E I J F B C - C I J F C C^@ = C^1 = F I J F B^@ = B^1 B^2 B^3 -- cgit v1.2.1