Reading a Unified Diff

Mental model

Cisco objective 5.12 says “Interpret a unified diff”. Unified diff is the standard patch format. Git, diff -u, GitHub, GitLab, patch, every code-review tool uses it. Four symbols cover 99% of what you will see.

--- a/commands.txt
+++ b/commands.txt
@@ -1,3 +1,4 @@
 show version
-show ip int brief
+show ip interface brief
+show ip route
 show running-config

The four symbols

The @@ hunk header

@@ -1,3 +1,4 @@

• -1,3 → in the OLD file, this hunk starts at line 1 and spans 3 lines.
• +1,4 → in the NEW file, this hunk starts at line 1 and spans 4 lines.
• The @@ on each side wraps the header.

A file with multiple edits has multiple @@ hunks. Each hunk tells you where in both files it applies.

Walking the example

--- a/commands.txt            # old filename (a/ is the "before" prefix git uses)
+++ b/commands.txt            # new filename (b/ is "after")
@@ -1,3 +1,4 @@               # hunk: old lines 1 to 3, new lines 1 to 4
 show version                 # unchanged
-show ip int brief            # removed from old
+show ip interface brief      # added in new
+show ip route                # added in new
 show running-config          # unchanged

What this change does:

• Replaced the abbreviated show ip int brief with the full show ip interface brief.
• Added show ip route as a new command.

Line counts:

• Old file was 3 lines. New file is 4 lines. One line replaced, one added.

Multi-file diff

If a change touches multiple files, each file has its own --- / +++ header and its own set of @@ hunks:

diff --git a/a.py b/a.py
--- a/a.py
+++ b/a.py
@@ -5,2 +5,3 @@
 import os
+import json
 import sys
diff --git a/b.py b/b.py
--- a/b.py
+++ b/b.py
@@ -10,3 +10,3 @@
 def foo():
-    return 1
+    return 2

• a.py: added one import.
• b.py: changed a return value from 1 to 2.

Edge cases on the exam

Rename

diff --git a/old-name.txt b/new-name.txt
rename from old-name.txt
rename to new-name.txt

New file

diff --git a/new.txt b/new.txt
new file mode 100644
--- /dev/null
+++ b/new.txt
@@ -0,0 +1,2 @@
+line one
+line two

• --- /dev/null → file did not exist before.
• -0,0 → zero lines in the old (empty).
• Everything is a + add.

Deleted file

diff --git a/gone.txt b/gone.txt
deleted file mode 100644
--- a/gone.txt
+++ /dev/null

A single-line edit

@@ -42 +42 @@
-password = "hunter2"
+password = os.environ["PWD"]

(When the span is 1 line, the comma count can be omitted.)

In practice

• git diff on your own uncommitted changes.
• git diff HEAD~1 HEAD for the last commit.
• git log -p -1 for the last commit plus its diff.
• diff -u a.txt b.txt for ad-hoc comparisons of two files.
• GitHub / GitLab PR views show the same unified diff rendered with colours.

Reading tips

• Lines you need to understand are - (what was removed) and + (what was added).
• Context lines ( ) help you orient; skim them.
• Red (removed) and green (added) in most tools.
• If a hunk spans only “space, -, +, space” you are reading a replacement (edit in place).
• If a hunk is all + you are reading a pure addition.
• If a hunk is all - you are reading a pure deletion.

FAQ

Why does Git prefix with a/ and b/? Convention from the original diff tool: the “a” tree is before, the “b” tree is after. Just names; you can configure Git away from them but almost no one does.

What is a “patch” file? A text file containing a unified diff, usually with a .patch or .diff extension. Apply with git apply myfile.patch or patch -p1 < myfile.patch.

What is patch -p1? -p1 strips one leading path component (the a/ or b/). Standard for applying git-generated patches.

What is a “merge conflict marker”? Different format. See git branches, merge and conflicts. Conflict markers are <<<<<<<, =======, >>>>>>>.