Re: [PATCH 3/3] Documentation: revisions: add note about 3dots usages as continuation indications
From: Junio C Hamano <hidden>
Date: 2017-11-06 04:35:03
Ann T Ropea [off-list ref] writes:
quoted hunk
Also, fix typo: "three dot" ---> "three-dot" (align with "two-dot"). Signed-off-by: Ann T Ropea <redacted> --- Documentation/revisions.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-)diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 61277469c874..d1b126427177 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt@@ -271,7 +271,7 @@ The '..' (two-dot) Range Notation:: 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:: +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)'.@@ -285,6 +285,15 @@ 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. +However, there are instances where '<sha1>...' is *not* +equivalent to '<sha1>...HEAD'. See the "RAW OUTPUT FORMAT" +section of linkgit:git-diff[1]: the three-dot notations used +there are simply continuation indications for the abbreviated +SHA-1 values. The ones encountered there are usually +associated with file/index/tree contents rather than with commit +objects, and the range operators described above are only +applicable to commit objects (i.e., 'r1' and 'r2'). + Other <rev>{caret} Parent Shorthand Notations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Three other shorthands exist, particularly useful for merge commits,
I actually have a mild suspicion that this is going in a wrong direction. In very early days of Git, we wanted to make sure that people can tell if a long hex string is a truncated object name or a full one (mostly because some lower-level commands insisted to be fed only full object name). These days, everybody knows when they see 79ec0be62a that it is *not* a full object name and will no longer be confused unlike early days and there is no strong reason to waste six output columns of "git diff --raw" output by using these three dots. I wonder if we can come up with a solution in line with the patch 1/3 in this series, which got rid of the "..." that indicated that the hexstring was not a full object name.