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

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,

2008/9/1 Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>:

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.

Paolo Ciarrocchi wrote:

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.

ASCII art <1> or <2>:
--o--x
   \
    -x

ASCII art <3>:

--x---
   \
    -x

where the x marks the changes to be diffed