How to Read Diff Output: Understanding Patch Files and Changes

How to Read Diff Output: Understanding Patch Files and Changes

Diff output is the universal language of version control systems. Every developer encounters diff output regularly — during code review, when resolving merge conflicts, or when applying patches from open-source contributions. Yet many developers never learn to read diff output efficiently.

This guide explains how to read diff output in its most common formats, how patch files work, and how to interpret changes with confidence.

What Is Diff Output?

Diff output is a structured representation of differences between two files or sets of files. The diff utility, created by Douglas McIlroy at Bell Labs in the 1970s, remains the foundation of Git, Mercurial, and most other version control systems.

When you run git diff or any diff command, the output shows precisely what changed, where it changed, and how it changed — in a format that both humans and machines can read.

Understanding the Unified Diff Format

The unified diff format is the most widely used output format today. It groups changes into hunks, each preceded by context lines that help you locate the change within the file.

Anatomy of a Hunk Header

Every hunk begins with a header that looks like this:

@@ -start,count +start,count @@

Let us break this down:

| Part | Meaning | |------|---------| | @@ | Delimiters marking the start of a hunk | | -3,7 | In the original file, this hunk starts at line 3 and spans 7 lines | | +3,8 | In the new file, this hunk starts at line 3 and spans 8 lines | | @@ | Closing delimiters |

The context line immediately after the header (typically a function name or nearby comment) helps you identify which part of the file the change belongs to.

Lines in a Hunk

Each line inside a hunk is prefixed with a single character:

 context line (unchanged)
-added line    (present in new file, absent in old)
+added line    (present in new file, absent in old)

• Context lines begin with a space. These are identical in both versions and provide reference points.
• Removed lines begin with a minus sign (-). These exist in the old file but were deleted.
• Added lines begin with a plus sign (+). These are new in the changed file.

Practical Example

Here is a diff showing a function being modified:

@@ -5,7 +5,9 @@
 def greet(name):
-    print("Hello, " + name)
-    print("Welcome!")
+    message = f"Hello, {name}!"
+    print(message)
+    print("We are glad to see you.")
+
     if name == "admin":
         print("You have admin privileges.")

Reading this diff:

• The old version printed "Hello, " plus the name, then "Welcome!".
• The new version builds a formatted message string, prints it, adds an extra greeting line, and keeps the admin check unchanged.
• Two lines were removed (the - lines), three lines were added (the + lines), and the empty + line preserves a blank line for readability.

Patch Files: Diffs You Can Apply

A patch file is simply a diff saved to a file — conventionally with a .patch or .diff extension. Patch files serve as a portable way to share changes without sharing the entire codebase.

Creating a Patch

Using Git, create a patch from your latest commit:

git format-patch HEAD~1

Or create a patch from uncommitted changes:

git diff > my-changes.patch

Applying a Patch

Apply a patch to a target repository:

git apply my-changes.patch

Or use the classic patch command:

patch -p1 < my-changes.patch

The -p1 flag strips the first directory component from file paths, which accounts for differences in directory structure between the patch creator and the person applying it.

Common Diff Output Formats

Beyond unified diff, you may encounter these formats:

Normal Diff

The default output of the original diff command. Changes are shown as instructions to change, add, or delete lines using commands like a (append), c (change), and d (delete).

3c3
< Hello world
---
> Hello beautiful world

Context Diff

An older format that provides three lines of context around every change. It uses exclamation marks to indicate changed lines.

Side-by-Side Diff

Not a single-file format — instead, it displays two columns side by side. This is common in graphical diff tools and online diff checkers.

Reading Diff Output in Code Reviews

When reviewing a pull request, focus on these elements:

1. The hunk headers: they tell you which files and functions are affected.
2. The ratio of added to removed lines: a large number of changes in critical files warrants closer attention.
3. Context lines: they show you the surrounding logic, helping you assess whether the change is correct.
4. Whitespace-only changes: many diff tools highlight these differently, as they can clutter the review.

Best Practices for Interpreting Diffs

• Read diffs from top to bottom, file by file — this matches the order in which changes were made.
• Pay attention to unchanged context lines near modified code; they reveal the structural relationship between old and new code.
• Use a tool that supports syntax highlighting in diff view — color makes patterns easier to spot.
• When reviewing large diffs, start with the test files to understand what behavior the author intended to change.

Understanding diff output is a foundational skill for collaborative development. Once you are comfortable reading diffs, you will navigate code reviews, merge conflicts, and patch files with much greater confidence.