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

3 messages from 2008-09-01 to 2008-09-01. Participants: Paolo Ciarrocchi, Mikael Magnusson, Daniël Gressmann.
Thread: https://gitlist.dev/t/15320

## Paolo Ciarrocchi, 2008-09-01 12:43

Subject: [RFD] How to better document the "two and three dots" format
Message-ID: <4d8e3fd30809010543o1e1562c1s4466e191e782ddcc@mail.gmail.com>
URL: https://gitlist.dev/e/4d8e3fd30809010543o1e1562c1s4466e191e782ddcc%40mail.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?

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/

```

## Mikael Magnusson, 2008-09-01 12:49

Subject: Re: [RFD] How to better document the "two and three dots" format
Message-ID: <237967ef0809010549n72629d47gfdf3c483f1a9e369@mail.gmail.com>
URL: https://gitlist.dev/e/237967ef0809010549n72629d47gfdf3c483f1a9e369%40mail.gmail.com
In-Reply-To: <4d8e3fd30809010543o1e1562c1s4466e191e782ddcc@mail.gmail.com>

```
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

```

## Daniël Gressmann, 2008-09-01 13:01

Subject: Re: [RFD] How to better document the "two and three dots" format
Message-ID: <48BBE7B6.9070709@procura.nl>
URL: https://gitlist.dev/e/48BBE7B6.9070709%40procura.nl
In-Reply-To: <4d8e3fd30809010543o1e1562c1s4466e191e782ddcc@mail.gmail.com>

```
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
 

```