Introduction

git diff output looks noisy at first, but it is built from a small number of repeated parts. Once you know what the file header, hunk header, and line markers mean, you can read a diff quickly and focus on the code change itself instead of the formatting around it.

Start with the File Header

A diff usually begins with a file-level header:

1diff --git a/app.py b/app.py
2index 1234567..89abcde 100644
3--- a/app.py
4+++ b/app.py

Here is what those lines mean:

• 'diff --git a/app.py b/app.py tells you which file is being compared'
• 'index ... shows blob hashes and file mode metadata'
• '--- is the old side'
• '+++ is the new side'

The a/ and b/ prefixes do not mean different directories in your project. They are just labels for the old and new versions.

Read the Hunk Header Next

Then you see a hunk header:

@@ -10,4 +10,5 @@ def greet(name):

This tells you where the change is located.

• '-10,4 means the old file section starts at line 10 and spans 4 lines'
• '+10,5 means the new file section starts at line 10 and spans 5 lines'

You do not have to memorize every detail. The practical point is that the hunk header tells you where in the file the change lives.

Understand the Line Prefixes

Inside the hunk:

 def greet(name):
-    return "Hello"
+    return f"Hello, {name}"

The first character on each line is the key:

• Space means unchanged context
• '- means removed from the old version'
• '+ means added in the new version'

That is the core of reading any diff.

What git diff Is Comparing

The command matters too:

git diff

This shows unstaged changes in your working tree compared with the index.

git diff --cached

This shows staged changes compared with the last commit.

git diff main..feature

This compares two commit ranges or branch tips.

So reading a diff always involves two questions:

1. What do the symbols mean
2. Which two states am I actually comparing

That second question is where many misreads start. A diff can be perfectly formatted and still mislead you if you forgot whether you were looking at working-tree changes, staged changes, or a branch-to-branch comparison.

Use Helpful Variants

Sometimes raw patch output is too detailed. These options help:

git diff --stat
git diff --word-diff
git diff -U1

• '--stat gives a summary by file'
• '--word-diff is useful for prose or small text edits'
• '-U1 reduces context lines and makes small changes easier to scan'

These do not change the underlying comparison, only the presentation.

Common Pitfalls

• Reading + as "this line exists now" without also checking the surrounding context.
• Forgetting whether the diff is unstaged, staged, or between two commits.
• Assuming a/ and b/ are real project paths.
• Focusing on line counts and missing what the code behavior actually changed.

Summary

• Read git diff in three layers: file header, hunk header, then changed lines.
• Space means context, - means removed, and + means added.
• Always know which two states are being compared.
• Use --stat or --word-diff when raw patch output is harder to scan.
• Once you understand the prefixes, the output becomes much easier to interpret.

That clarity comes quickly with practice.