[RFD] How to better document the "two and three dots" format

[RFD] How to better document the "two and three dots" format

[Paolo Ciarrocchi]

Hi all,
I'm looking in the existing documentation about some example and
clarification about
the two and three dots formats applied to git diff.

The git-diff.txt file includes the following:

---8<---
Comparing branches::
+
------------
$ git diff topic master    <1>
$ git diff topic..master   <2>
$ git diff topic...master  <3>
------------
+
<1> Changes between the tips of the topic and the master branches.
<2> Same as above.
<3> Changes that occurred on the master branch since when the topic
branch was started off it.
---8<---

I think <3> should be changed in something like:
<3> Changes between the tips of the topic and the master branch that
occurred since when the topic
branch was started off it.

What do you think?

I would like to add some graphical representation of <2> and <3> but
I'm a bit loss
with <3> (and I guess lot of newbies are not really understanding that point).
Can anybody come up with some ASCII art?

Thanks.

Ciao,
-- 
Paolo
http://paolo.ciarrocchi.googlepages.com/

Re: [RFD] How to better document the "two and three dots" format

[Mikael Magnusson]

2008/9/1 Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>:
> Hi all,
> I'm looking in the existing documentation about some example and
> clarification about
> the two and three dots formats applied to git diff.
>
> The git-diff.txt file includes the following:
>
> ---8<---
> Comparing branches::
> +
> ------------
> $ git diff topic master    <1>
> $ git diff topic..master   <2>
> $ git diff topic...master  <3>
> ------------
> +
> <1> Changes between the tips of the topic and the master branches.
> <2> Same as above.
> <3> Changes that occurred on the master branch since when the topic
> branch was started off it.
> ---8<---
>
> I think <3> should be changed in something like:
> <3> Changes between the tips of the topic and the master branch that
> occurred since when the topic
> branch was started off it.
>
> What do you think?

Your proposed sentence is incorrect, the diff doesn't involve the tip
of topic at all. It shows the diff between the merge-base and the tip
of master. Ie, the combined diff of all the commits in the rev-list
range topic..master.

> I would like to add some graphical representation of <2> and <3> but
> I'm a bit loss
> with <3> (and I guess lot of newbies are not really understanding that point).
> Can anybody come up with some ASCII art?
>
> Thanks.
>
> Ciao,

-- 
Mikael Magnusson

Re: [RFD] How to better document the "two and three dots" format

[Daniël Gressmann]

Paolo Ciarrocchi wrote:
> I think <3> should be changed in something like:
> <3> Changes between the tips of the topic and the master branch that
> occurred since when the topic
> branch was started off it.
I think it's a step in the proper direction. My take, as a newbie ;), at 
it would be more like:

<3> Changes between the current tip of the topic and the tip of master 
branch at the moment the topic branched off.

I think the ASCII art explains why I think that way.
> Can anybody come up with some ASCII art?
>   
ASCII art <1> or <2>:
--o--x
   \
    -x

ASCII art <3>:

--x---
   \
    -x

where the x marks the changes to be diffed

-- 
PROCURA B.V.

Tel: (072) 571 25 05
Fax: (072) 571 71 02

Email: daniel@procura.nl

PROCURA B.V. (statutair gevestigd in Heerhugowaard),
Handelsregister Kamer van Koophandel Noordwest-Holland: 37140650