Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 78 ยท Inspecting History

Comparing Commits, Branches and Files

Compare anything in Git: git diff between commits and branches, two-dot vs three-dot, range-diff, diff --stat, show rev:path, --check and diff algorithms.

You already know git diff as the command that shows your uncommitted changes (see Status, Diff and Seeing Changes). But git diff is much more general: it compares any two snapshots that Git can name. Two commits, a branch and a tag, a commit and your working directory, a file in two versions, even two directories that are not in a repository. Whenever you ask "what changed between X and Y?", this is the tool.

This lesson covers the comparisons you will make in code review and release work: what a feature branch changes, what changed between two releases, what differs on a single file across history, and how to compare two versions of the same branch (before and after a rebase) with git range-diff. It also explains the two-dot versus three-dot difference that trips up almost everyone, and the diff algorithms that decide how a patch is presented.

The general form: git diff A B

git diff <A> <B> shows the changes needed to turn snapshot A into snapshot B. A line starting with - exists in A only; a line starting with + exists in B only. All the ways to name A and B from Revision Syntax work here.

Command Compares
git diff working directory with the index (unstaged changes)
git diff --staged index with HEAD (what the next commit will contain)
git diff HEAD working directory with HEAD (everything uncommitted)
git diff A B commit A with commit B
git diff A commit A with your working directory
git diff A..B same as git diff A B
git diff A...B merge base of A and B with B
git diff A B -- path only the named paths

Here is a small project with three commits so we can look at the output in different shapes: the full patch, a summary, and just the names.

Bash Diff two commits: patch, stat and file list

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Read a patch from the top. The header diff --git a/greet.py b/greet.py names the file in both snapshots (a/ is the left side, b/ the right). The index line shows abbreviated blob hashes. Lines --- and +++ repeat the file names. Each @@ -1,2 +1,5 @@ hunk header says "starting at line 1, two lines on the left became five on the right". Lines with a leading space are unchanged context. --stat is the quick overview used in pull request summaries. --name-status gives one letter per file, which is perfect for scripts.

Useful output options for any git diff:

  • --stat, --shortstat, --numstat (machine-readable counts), --dirstat (changes by directory);
  • --name-only, --name-status;
  • -U<n> or --unified=<n>: lines of context (default 3);
  • --word-diff and --color-words: highlight changed words instead of lines;
  • -w / --ignore-all-space, -b, --ignore-blank-lines: ignore whitespace noise;
  • --ignore-matching-lines=<regex>: skip hunks where every changed line matches;
  • -M and -C: detect renames and copies (rename detection is on by default; copy detection is not);
  • --exit-code and --quiet: exit status 1 when there are differences, for scripts.

Two dots versus three dots

For git log, A..B and A...B select sets of commits. For git diff, they are two ways of choosing the left side of the comparison.

TEXT
          X---Y---Z      topic
         /
   O---P---Q---R         main

   git diff main..topic    compares R   with Z   (two tips, directly)
   git diff main...topic   compares P   with Z   (P = merge base of main and topic)

git diff main..topic is exactly git diff main topic: it includes everything different between the two tips, which means the changes made on main since the branch point show up in reverse, because topic does not have them. That is rarely what you want when reviewing a feature branch.

git diff main...topic first finds the merge base (P) and compares it to topic. It shows only what the topic branch itself changed, ignoring main's progress. This is the right answer to "what would merging this branch bring in?" and it is what pull request views show.

Bash main..topic versus main...topic

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

With two dots, main.txt appears as deleted (D), because topic does not have it, which is misleading: nobody on the topic branch removed it. With three dots, only topic.txt is listed, which is what the branch really contributes.

The dots mean something different for git log. In log, A...B is the symmetric difference of two commit sets (see Revision Syntax), and A..B is "in B not in A". For diff, the dots only choose how the two comparison sides are picked. The same text can therefore do different things in the two commands.

One file through history

Often the question is about a single file. These commands answer it:

  • git show <rev>:<path> prints the file as it was in that revision (a blob), without touching your working directory. Redirect it to save an old version: git show v1.0:config.ini > config.old.
  • git diff <rev> -- <path> compares that old version with your working copy.
  • git log -p -- <path> lists every commit that touched the file, with its patch. Add --follow to continue through renames (more in blame, grep and Searching History).
  • git log -L :functionName:file or -L 10,20:file shows the history of a function or line range only.
  • git diff --no-index a.txt b.txt compares two files that are not in a repository at all.
Bash Show one file in the past and follow its history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git diff --no-index exits with 1 when the files differ, like the classic diff tool, which is why we print the exit code. Use --exit-code or --quiet with ordinary git diff to get the same behavior in scripts: git diff --quiet || echo "uncommitted changes".

Finding whitespace problems: --check

git diff --check warns about changes that introduce whitespace errors (trailing spaces, a space before a tab in indentation, conflict markers left in files). Many teams run it as a pre-commit or CI step because trailing whitespace creates noisy diffs later.

Bash diff --check and word-level diffs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

--check reports the line number and the problem; its exit status is non-zero, so it fails a script automatically. The word diff marks [-removed-] and added inside one line, which makes small edits in prose or long lines much easier to read than two full lines of - and +.

Diff algorithms: patience, histogram and friends

A diff is not unique. Many different sets of added and removed lines turn file A into file B, and the algorithm chooses one. The default is Myers, which finds a short edit script quickly but can produce confusing output when files contain many repeated lines (closing braces, blank lines). Alternatives:

  • --patience: matches unique lines first, then fills in the rest. It often yields more readable diffs when code was moved or surrounded by repeated lines.
  • --histogram: an improved patience that is also fast. It is a good all-round choice.
  • --minimal: spends extra time to find the smallest possible diff.

Set a permanent default with git config --global diff.algorithm histogram. The algorithm affects how changes are displayed and grouped; it never changes the content of commits.

Bash The same change under different algorithms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Here the code did two things: hello moved below square, and one string changed from "hello" to "hi". Myers matches the many repeated brace lines first, so it reports a confusing zigzag in which square and hello are interleaved line by line, and the real one-word edit is buried inside it. Patience and histogram anchor on the unique lines (the function headers), so they report the clean story: the hello block was removed from the top and added again below square with its changed line. In this case the two give identical output; on other files they can differ from each other, but both tend to beat Myers when repeated lines dominate.

Comparing two versions of a branch: range-diff

Suppose you opened a pull request, a reviewer asked for changes, and you rewrote the branch (amend, interactive rebase, rebase onto a newer main). The old and new versions share almost no commit hashes. How do you review what changed between the two versions? A normal diff between the two tips mixes your changes with everything that arrived from the new base.

git range-diff compares two series of commits. It pairs up commits by their patch content, then shows for each pair whether it is unchanged (=), changed (!), added (+), or removed (-), and for changed ones the diff of the diffs.

TEXT
git range-diff <old-base>..<old-tip> <new-base>..<new-tip>
git range-diff main topic@{1} topic        # three-argument form: base, old tip, new tip
git range-diff topic@{u} ...topic          # compare with the upstream version of the branch
Bash Review a rebased and amended branch with range-diff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Each line pairs an old commit (left) with a new commit (right). The first pair is marked =: the patch is identical, so Git matched the two commits even though the rebase gave them new hashes. The second pair is marked !: the patch changed, and the indented lines below are the diff of the two diffs, showing that the only difference is y = 2 becoming y = 20. Reviewers love this because they do not have to re-read the unchanged parts.

Diffs in review practice

A short checklist that experienced reviewers follow:

  1. git diff --stat main...topic first: how big is it, which files?
  2. git log --oneline main..topic to see the story in commit messages.
  3. Read each commit with git show <hash> when the commits are well formed, or the whole thing with git diff main...topic otherwise.
  4. Run git diff --check main...topic for whitespace problems.
  5. After changes arrive: git range-diff to see only what moved.

Use git diff --color-moved to highlight blocks that were moved rather than changed. Moved code appears in different colors from true additions and removals, so refactorings are far easier to review.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You are reviewing a feature branch and want to see only what it changed relative to the point where it left main. Which command is right?

    Three dots compare the merge base of the two branches with feature. Two dots compare the tips directly, so work that only exists on main shows up as removed lines.
  2. 2. What does git diff --name-status HEAD~3 HEAD print?

    --name-status lists the files that differ and a one-letter status: A added, M modified, D deleted, R renamed.
  3. 3. How do you print notes.txt exactly as it was two commits ago without changing your working directory?

    rev:path names the file as stored in that commit, and git show prints it. The other commands change files or branches.
  4. 4. Which tool compares two versions of the same series of commits, for example a branch before and after a rebase?

    range-diff pairs commits by patch content and shows what changed between the old and new versions, even though the hashes differ.
  5. 5. Which statement about --patience and --histogram is correct?

    The algorithm only affects how a diff is computed and displayed. The content of commits never changes.

Summary

  • git diff A B shows how to get from snapshot A to snapshot B; any revision name works, and -- path limits it.
  • Without arguments it compares working tree and index; --staged compares index and HEAD; HEAD compares everything uncommitted.
  • main..topic compares the tips; main...topic compares the merge base with topic and shows what the branch contributes.
  • Use --stat, --name-status, --word-diff, --color-moved and --check to read, summarize and lint changes.
  • git show rev:path, git log -p -- path and git log -L follow a file or function through history.
  • --patience and --histogram can produce clearer diffs than the default Myers algorithm; diff.algorithm sets a default.
  • git range-diff compares two versions of a branch after rewriting.

Next: blame, grep and Searching History