On Sat, Jun 12, 2021 at 8:44 PM Felipe Contreras
<felipe.contreras@xxxxxxxxx> wrote:
> The original explanation didn't seem clear enough to some people.
>
> Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx>
> ---
> 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/
