Git Course 0%

Compare branches

Intermediate Git CLI VS Code UI IntelliJ UI GitLab UI GitHub UI ≈ 8 min

Before this lesson

What you will learn

  • The commit range main..branch and what it excludes
  • The difference between two dots and three dots, and which one a merge request shows
  • How to summarize a branch's changes before asking for review

After this lesson you can

  • I can list exactly the commits and files my branch adds, before anyone reviews it

Why this matters

Before you ask for review, you should know exactly what you are asking someone to read. Comparing your branch with main answers that in two commands, and it catches the two classic surprises: a file you did not mean to change, and a commit from another branch that came along by accident.

The two-dot range: what the branch adds

Terminal
$ git log --oneline main..docs/12-windows-install-steps
510f1e0 docs: add Windows steps to installation guide (#12)

Read main..docs/12-… as "commits reachable from the branch but not from main". One commit, so this branch adds exactly one thing. Reverse the order to ask the opposite question, "what has main gained that my branch lacks", which is the same as "how far behind am I":

Terminal
$ git log --oneline docs/12-windows-install-steps..main

Empty output means the branch is up to date with main.

Summarizing the files

Terminal
$ git diff main..docs/12-windows-install-steps --stat
 docs/getting-started.md | 4 ++++
 1 file changed, 4 insertions(+)

One file, four added lines. That is the review you are about to request. Drop --stat for the full diff, or add a path to focus: git diff main..docs/12-… -- docs/.

Two dots and three dots

git diff accepts both, and they answer different questions:

Form Compares Answers
git diff main..branch the tip of main with the tip of the branch "How do the two versions differ right now?"
git diff main...branch the branch with the point where it left main "What did this branch change?"

While your branch is up to date with main, both give the same answer:

Terminal
$ git diff main...docs/12-windows-install-steps --stat
 docs/getting-started.md | 4 ++++
 1 file changed, 4 insertions(+)

They diverge once main moves ahead. Then two dots also shows main's new work as if you had removed it, which is confusing and almost never what you want. Three dots is what a merge request shows, and it is the safer habit for reviewing your own branch.

How to do it

Terminal
$ git log --oneline main..docs/12-windows-install-steps
$ git diff main...docs/12-windows-install-steps --stat

The first says which commits, the second which files. Run both before opening a merge request.

Common mistakes

  • Comparing with a stale main. Your local main may be days old. git fetch first, or compare against origin/main directly: git log --oneline origin/main..HEAD.
  • Using two dots in git diff after main moved. The output includes main's new work inverted. Use three dots.
  • Forgetting -- before a path that looks like a branch name.
  • Reading the file count as the review size. A one-line change to a lock file is not the same work as a one-line change to a paragraph; look at the diff, not only the count.

Try it yourself

Goal: describe your own branch the way a reviewer will see it.

  1. From an up-to-date main, create docs/practice-compare, make two commits touching two different files.
  2. Run git log --oneline main..docs/practice-compare.
  3. Run git diff main...docs/practice-compare --stat.
  4. Move main forward with one commit, then run both the two-dot and the three-dot diff and compare the output.

Expected result: step 2 lists your two commits; step 3 lists your two files; in step 4 the two-dot diff also mentions the file you changed on main, while the three-dot diff still shows only your two.

Show solution

The three-dot form compares your branch against the commit where it left main, so main's later work never appears. That is what a merge request shows, and why it is the honest answer to "what does my branch change?". Clean up with git switch main and git branch -D docs/practice-compare.

Check yourself

1. Which command lists the commits your branch adds to main?
2. Your branch is five commits behind main. Which diff shows only your own changes?
3. git log --oneline my-branch..main prints nothing. What does that tell you?

Key terms

Branch Diff Log Merge request (MR)

Related