Git Diff Explained with Examples (Command, Usage, Syntax, Scenarios)

git diff is one of the most essential Git commands used to compare changes between files, commits, branches, and the staging area. It helps developers understand what has changed before committing code using git commit, making it a critical tool for debugging, reviewing, and tracking modifications.

Whether you want to check unstaged changes, verify staged files, compare commits, or review differences between branches, git diff provides a flexible way to inspect code changes in detail.

In this guide, we will cover how git diff works, its syntax, and real-world scenarios with practical examples ...so you can confidently use it in your daily workflow as part of an efficient Git workflow.

git diff shows the differences between two states in a Git repository such as working directory, staging area (index), or commits.

Git Diff Cheat Sheet (Quick Reference Table)

Tip:
Use git diff before every commit to review changes and avoid mistakes.

What is git diff

git diff is a core Git command used to compare differences between various states of a repository such as the working directory, staging area (index), commits, and branches. It helps developers review what has changed in their code before committing or merging.

Unlike commands like git status, which only show which files changed, git diff shows exact line-by-line changes, making it extremely useful for debugging and code review.

Quick Answer:
git diff displays differences between two states in Git, such as working directory vs staging area, staging vs last commit, or between commits.

What git diff actually compares (Working tree vs Index vs HEAD)

To understand git diff, you must know the three main areas in Git:

• Working Directory (Working Tree) → Your current files on disk
• Staging Area (Index) → Files prepared for the next commit
• HEAD → Last committed state

Common comparisons:

• git diff → Working Directory vs Index (unstaged changes)
• git diff --staged → Index vs HEAD (staged changes)
• git diff HEAD → Working Directory vs HEAD (all changes)

Why git diff is important in daily Git workflow

• Helps review code before committing
• Prevents accidental commits of unwanted changes
• Assists in debugging issues by identifying exact modifications
• Useful during code reviews and collaboration
• Enables comparison across branches and commits

Git Diff Syntax and How It Works

Basic git diff syntax explained

git diff
git diff <file>
git diff HEAD
git diff --staged
git diff <commit1> <commit2>
git diff <branch1> <branch2>

General syntax:

git diff [options] [<commit>] [--] [<path>...]

Understanding git diff output (+, -, @@ symbols)

Typical output:

diff --git a/file.txt b/file.txt
index e69de29..4b825dc 100644
--- a/file.txt
+++ b/file.txt
@@ -1,2 +1,3 @@
 line1
-line2
+line2 updated
+line3

Explanation:

• - → Line removed
• + → Line added
• @@ -1,2 +1,3 @@ → Shows line numbers and context
• a/file.txt → Old version
• b/file.txt → New version

What is Git index in git diff

The Git index (staging area) is an intermediate layer between your working directory and the repository.

Workflow:

1. Modify files → working directory
2. Stage files → index using git add
3. Commit → saved in repository using git commit

git diff uses index to compare:

• Unstaged changes → working directory vs index
• Staged changes → index vs HEAD

Check Changes Before Staging

Compare working directory vs staging area (git diff)

To see what changes are made but not yet staged using git diff:

git diff

This shows:

• Modified files not added to staging
• Exact line-by-line changes

Example:

echo "new line" >> app.py
git diff

View changes for a specific file

To check changes in a single file:

git diff app.py

This is useful when:

• You are working on large projects
• You only want to review specific file changes

Compare Staged Changes Before Commit

Use git diff --staged (or --cached)

To view staged changes (ready for commit before using git commit):

git diff --staged

or

git diff --cached

Both commands are equivalent.

Example:

git add app.py
git diff --staged

Verify what will go into the next commit

This step is critical before committing:

git diff --staged

It helps you:

• Ensure correct files are staged
• Avoid committing unintended changes
• Review final changes before commit

Pro Tip:
Always run git diff --staged before git commit to avoid mistakes.

Compare with Last Commit (HEAD)

Use git diff HEAD

To compare your current working directory with the last committed state (HEAD created using git commit), use:

git diff HEAD

This command shows:

• All changes (both staged and unstaged)
• Difference between current files and last commit

Example:

echo "new change" >> app.py
git diff HEAD

This is useful when you want a complete view of all modifications since the last commit.

Difference between git diff and git diff HEAD

Key Insight:

• Use git diff → when checking what is NOT staged
• Use git diff HEAD → when checking ALL changes

Compare Between Commits

Use git diff commit1 commit2

To compare two commits:

git diff <commit1> <commit2>

Example:

git diff a1b2c3 d4e5f6

This shows:

• What changed between two points in history (you can inspect individual commits using git show)
• Useful for debugging or reviewing past changes

Compare specific file between commits

To compare changes for a specific file:

git diff <commit1> <commit2> -- app.py

Example:

git diff HEAD~1 HEAD -- app.py

This helps:

• Focus only on one file
• Avoid clutter from large diffs

Compare Between Branches

Use git diff branch1 branch2

To compare two branches created using git branch:

git diff main feature

This shows:

• Changes present in feature but not in main

Use git diff main..feature vs main...feature

git diff main..feature
git diff main...feature

Difference:

• main..feature
  → Direct comparison between two branch tips

• main...feature
  → Compares changes from common ancestor (merge-base)

Quick Tip:

• Use .. → when you want direct difference
• Use ... → when preparing for merge or pull request using git merge

Track File History and Changes

Use git diff for a single file

To check changes in a specific file:

git diff app.py

To compare file across commits:

git diff HEAD~1 HEAD -- app.py

Useful when:

• Debugging file-specific issues
• Reviewing targeted changes

Use git log -p vs git diff

Example:

git log -p app.py

This shows:

• Full history of changes for the file
• Each commit with its diff output

Get Summary Instead of Full Diff

Use git diff --stat

To get a summary view:

git diff --stat

Example output:

 app.py   | 5 +++--
 index.js | 2 +-
 2 files changed, 4 insertions(+), 3 deletions(-)

This shows:

• Number of files changed
• Insertions and deletions

Use git diff --name-only

To list only changed file names:

git diff --name-only

Output:

app.py
index.js

Useful when:

• You only want file names
• Working with scripts or automation

Improve Readability of Output

Use --color and --word-diff

By default, Git shows colored output, but you can explicitly enable it:

git diff --color

To highlight changes at the word level instead of line level, use:

git diff --word-diff

Example:

git diff --word-diff app.py

This helps:

• Identify small changes quickly
• Improve readability for large files

Ignore whitespace changes

Sometimes whitespace changes (spaces, tabs, indentation) create noise.

To ignore them:

git diff -w

or

git diff --ignore-space-change

Useful when:

• Formatting changes are not important
• You only want logical/code changes

Common Git Diff Mistakes

Why git diff shows nothing

If git diff shows no output, verify file state using git status or review commit history using git log command:

• No unstaged changes exist
• All changes are already staged

Check using git status:

git status

If changes are staged, use:

git diff --staged

Difference between staged vs unstaged confusion

Many users misunderstand this when working with git add and git commit:

• Unstaged changes → Modified but not added

  bash Copy

  git diff

• Staged changes → Added but not committed

  bash Copy

  git diff --staged

Tip:
Always check both before committing:

git diff
git diff --staged

Misunderstanding HEAD and index

• HEAD → Last committed version
• Index (staging area) → Next commit snapshot

Comparison summary:

• git diff → Working vs Index
• git diff --staged → Index vs HEAD
• git diff HEAD → Working vs HEAD

Understanding this avoids confusion when reviewing changes.

Summary

git diff is a powerful command used to compare changes in a Git repository at different stages of a proper Git workflow such as working directory, staging area, commits, and branches.

In this guide, you learned:

• What git diff is and how it works
• How to compare working directory, staging area, and commits
• How to compare branches and specific files
• How to interpret diff output
• How to use summary and readability options
• Common mistakes and how to avoid them

Official Documentation

• Git Diff Official Documentation
• Git Log Documentation
• Git Add Documentation