Re: [PATCH 3/3] Documentation: revisions: add note about 3dots usages as continuation indications

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 6, 2017, 04:34 UTC
Message-ID: <xmqqk1z4hvo0.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171105162730.31405-3-bedhanger@gmx.de>

Ann T Ropea <bedhanger@gmx.de> writes:

Show 36 quoted lines

> Also, fix typo: "three dot" ---> "three-dot" (align with "two-dot").
>
> Signed-off-by: Ann T Ropea <bedhanger@gmx.de>
> ---
>  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.