Re: [PATCH] doc: revisions: improve single range explanation

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jun 13, 2021, 03:32 UTC
Message-ID: <CAPig+cSE2h7A52drhELfZJLDEgQ1z+nEXoXhYMUSA00Z+S=OUA@mail.gmail.com>
In-Reply-To: <20210613004434.10278-1-felipe.contreras@gmail.com>

On Sat, Jun 12, 2021 at 8:44 PM Felipe Contreras <felipe.contreras@gmail.com> wrote:

Show 15 quoted lines

> The original explanation didn't seem clear enough to some people.
>
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> ---
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> @@ -299,22 +299,22 @@ empty range that is both reachable and unreachable from HEAD.
> +For example, if you have a linear history like this:
>
> +    ---A---B---C---D---E---F
>
> +Doing A..F will retrieve 5 commits, and doing B..E will retrieve 3
> +commits, but doing A..F B..E will not retrieve two revision ranges
> +totalling 8 commits. Instead the starting point A gets overriden by B,
> +and the ending point of E by F, effectively becoming B..F, a single
> +revision range.

s/overriden/overridden/

For what it's worth, as a person who is far from expert at revision ranges, I had to read this revised text five or six times and think about it quite a bit to understand what it is saying, whereas with Junio's original[1], I understood it on the first read with only a little thought.

Also, if this explanation is aimed at newcomers, then saying only "doing A..F will retrieve 5 commits" without actually saying _which_ commits those are is perhaps not so helpful. A newcomer might be helped more by enumerating the precise commits:

    The range A..F represents five commits B, C, D, E, F, and the
    range B..E represents three commits C, D, E, ...

[1]: https://lore.kernel.org/git/xmqqv97g2svd.fsf@gitster.g/