Avoid using the three-dot and two-dot terminology in relation to git diff

[NadAlaba]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests#three-dot-and-two-dot-git-diff-comparisons

What part(s) of the article would you like to see updated?

The use of A...B and A..B when using git diff is not recommended by the developers of git, since this terminology refers to ranges, and git diff doesn't work with ranges, but works with endpoints.

What makes this use even more confusing is that git diff A..B compares A and B, whereas git log A..B compares merge base of A and B, with B, and vice versa, git diff A...B compares merge base of A and B, with B, whereas git log A...B compares A and B.

This answer on stackoverflow explains this issue better than me, and quotes the developers of git.

I suggest replacing the use of "three-dot git diff" with git diff --merge-base base-branch topic-branch, and "two-dot git diff" git diff base-branch topic-branch.

Additional information

No response

---

Added by a maintainer

Content changes suggested to resolve this issue

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests#three-dot-and-two-dot-git-diff-comparisons

I think the best solution is to update the introductions to the two sections "Three-dot Git diff comparison" and "Two-dot diff comparison" to include the definitions that you've included in the issue summary. That is:

In the "Three-dot Git diff comparison" section

• Explain that what we're referring to as a three-dot git comparison is equivalent to: git diff --merge-base base-branch topic-branch

In the "Two-dot diff comparison" section

• Explain that what we're referring to as a two-dot git comparison is equivalent to: git diff base-branch topic-branch

Any larger changes would need to wait on changes to the user interface.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@NadAlaba Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[felicitymay]

@NadAlaba - thanks for flagging this concern and the advice from git developers. It's helpful to have such clear information. 💖

✋🏻 Comment edited after further exploration of the user interface and docs

Given that GitHub uses the three and two-dot notation throughout the user interface as well as the docs, it's likely to confuse users if we make a large change to this article (the user interface is unlikely to be updated in the medium term).

I think the best solution is to update the introductions to the two sections "Three-dot Git diff comparison" and "Two-dot diff comparison" to include the definitions that you've included in the issue summary. That is:

"Three-dot Git diff comparison"

• Explain that what we're referring to as a three-dot git comparison is equivalent to: git diff --merge-base base-branch topic-branch

"Two-dot diff comparison"

• Explain that what we're referring to as a two-dot git comparison is equivalent to: git diff base-branch topic-branch

Any larger changes would need to wait on changes to the user interface.

[Benjamin-Akpeh]

There's a typo in the heading. It should be "relation" not realtion.