How to Use Git Diff: A Beginner's Guide

What Is Git Diff?

git diff is a command that shows you what changed between two states in a Git repository. It's one of the most frequently used Git commands, yet many developers only know its most basic form. This guide covers everything from the basics to the flags that make git diff a power tool.

The Four Basic Use Cases

# 1. Working tree vs index (unstaged changes)
git diff

# 2. Index vs HEAD (staged changes ready to commit)
git diff --cached

# 3. Working tree vs HEAD (everything not in the last commit)
git diff HEAD

# 4. Between two commits or branches
git diff main..feature/auth

The most common confusion: git diff alone only shows unstaged changes. If you've run git add, those changes disappear from git diff. Use git diff --cached to see what you've staged.

Reading the Output

diff --git a/src/auth.ts b/src/auth.ts
index a1b2c3d..e4f5g6h 100644
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -15,6 +15,8 @@ export function login(email: string) {
   const user = findUser(email)
-  return user
+  if (!user) throw new Error('Not found')
+  return user.withToken()

• Lines starting with - were removed
• Lines starting with + were added
• Lines with a space are unchanged context
• The @@ -15,6 +15,8 @@ header means: old file starts at line 15 for 6 lines; new file starts at line 15 for 8 lines

Useful Flags

# Word-level diff (great for prose and variable renames)
git diff --word-diff

# Show only file names that changed
git diff --name-only

# Show names with change type (M=modified, A=added, D=deleted)
git diff --name-status

# Summary of additions/deletions per file
git diff --stat

# Ignore whitespace changes
git diff -w

# Control context lines (default 3, set to 0 for minimal)
git diff -U0

# Compare a specific file only
git diff HEAD -- src/api.ts

Comparing Branches

# What changed on feature/auth compared to main?
git diff main..feature/auth

# Two-dot vs three-dot: an important distinction
git diff main..feature   # diff between tips of both branches
git diff main...feature  # diff of feature since it diverged from main (usually what you want)

The three-dot form (main...feature) is typically more useful for PR review because it shows only the changes introduced by the feature branch, excluding anything that happened on main since the branch was created.

Comparing Specific Files Across Commits

# How did this file look 5 commits ago vs now?
git diff HEAD~5 HEAD -- src/config.ts

# Compare between two specific commits
git diff abc1234 def5678 -- package.json

# What changed between two tags?
git diff v1.0.0 v1.1.0

Git Diff in Practice: A Pre-Commit Ritual

Before every commit, run this sequence:

1. git diff — review unstaged changes one more time
2. git add -p — interactively stage only what you mean to commit
3. git diff --cached — confirm exactly what's going into the commit
4. git commit -m "..."

This habit catches accidental debug statements and unintended changes before they're committed. For a visual version of step 3, paste the output of git diff --cached into DiffChecker Pro.

Exporting Diffs as Patches

# Save diff to a file
git diff HEAD~1 HEAD > my-changes.patch

# Format as a proper patch (with commit metadata)
git format-patch HEAD~1

# Apply a patch
git apply my-changes.patch