Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Avoid using the three-dot and two-dot terminology in realtion to git diff #32224

Open
1 of 3 tasks
NadAlaba opened this issue Mar 26, 2024 · 5 comments
Open
1 of 3 tasks
Labels
content This issue or pull request belongs to the Docs Content team help wanted Anyone is welcome to open a pull request to fix this issue pull requests Content related to pull requests

Comments

@NadAlaba
Copy link

NadAlaba commented Mar 26, 2024

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.

@NadAlaba NadAlaba added the content This issue or pull request belongs to the Docs Content team label Mar 26, 2024
Copy link

welcome bot commented Mar 26, 2024

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.

@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Mar 26, 2024
@nguyenalex836 nguyenalex836 added waiting for review Issue/PR is waiting for a writer's review pull requests Content related to pull requests and removed triage Do not begin working on this issue until triaged by the team labels Mar 26, 2024
@nguyenalex836
Copy link
Contributor

@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
Copy link
Contributor

felicitymay commented May 31, 2024

@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.

@felicitymay felicitymay added help wanted Anyone is welcome to open a pull request to fix this issue and removed stale There is no recent activity on this issue or pull request waiting for review Issue/PR is waiting for a writer's review labels Jul 16, 2024
@github-actions github-actions bot added the stale There is no recent activity on this issue or pull request label Sep 16, 2024
@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Sep 24, 2024
@nguyenalex836 nguyenalex836 removed the stale There is no recent activity on this issue or pull request label Sep 24, 2024
@nguyenalex836 nguyenalex836 reopened this Sep 24, 2024
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Sep 24, 2024
@nguyenalex836 nguyenalex836 removed the triage Do not begin working on this issue until triaged by the team label Sep 24, 2024
@Mmm-bit

This comment was marked as spam.

@github-actions github-actions bot added the stale There is no recent activity on this issue or pull request label Dec 16, 2024
@nguyenalex836 nguyenalex836 removed the stale There is no recent activity on this issue or pull request label Dec 19, 2024
@github-actions github-actions bot added the stale There is no recent activity on this issue or pull request label Feb 18, 2025
@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Feb 26, 2025
@nguyenalex836 nguyenalex836 reopened this Feb 27, 2025
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Feb 27, 2025
@nguyenalex836 nguyenalex836 removed triage Do not begin working on this issue until triaged by the team stale There is no recent activity on this issue or pull request labels Feb 27, 2025
@Benjamin-Akpeh
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content This issue or pull request belongs to the Docs Content team help wanted Anyone is welcome to open a pull request to fix this issue pull requests Content related to pull requests
Projects
None yet
Development

No branches or pull requests

6 participants
@felicitymay @NadAlaba @Benjamin-Akpeh @nguyenalex836 @Mmm-bit and others