From d7c146975d101dcf3f66967ef47a8e084abcdcb6 Mon Sep 17 00:00:00 2001
From: Bjarke Sporring <work.bjarke@gmail.com>
Date: Mon, 5 Jan 2026 13:34:59 +0100
Subject: [PATCH] feat: add understanding for diffs

---
 GIT-CHEATSHEET.md           |   8 +++
 module-02-history/README.md | 102 ++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)

diff --git a/GIT-CHEATSHEET.md b/GIT-CHEATSHEET.md
index 20d997f..4755b5e 100644
--- a/GIT-CHEATSHEET.md
+++ b/GIT-CHEATSHEET.md
@@ -94,6 +94,14 @@ git diff <commit1> <commit2> <file>
 ```
 Compare changes to a specific file between two commits.
 
+**Understanding diff output:**
+- Lines with `+` (green) = added
+- Lines with `-` (red) = removed
+- Lines with ` ` (space) = unchanged (context)
+- `@@ -1,5 +1,7 @@` = location of changes (old line/count, new line/count)
+
+For a detailed guide on reading diff output, see Module 02 README.md.
+
 ### Branching
 
 ```bash
diff --git a/module-02-history/README.md b/module-02-history/README.md
index fd4d7a8..f3c56a5 100644
--- a/module-02-history/README.md
+++ b/module-02-history/README.md
@@ -49,6 +49,108 @@ The setup script will create an `answers.md` file in the challenge directory wit
 - **Commit Message**: A description of what changed in that commit, written by the author.
 - **Commit History**: The chronological record of all changes made to a repository.
 - **HEAD**: A pointer to the current commit you're working from.
+- **Diff**: A view showing the differences between two versions of files.
+
+## Understanding Diff Output
+
+When you run `git diff` between commits, the output can look confusing at first. Here's how to read it:
+
+### Example Diff Output
+
+```diff
+diff --git a/app.py b/app.py
+index 1a2b3c4..5d6e7f8 100644
+--- a/app.py
++++ b/app.py
+@@ -1,5 +1,7 @@
+ # app.py - Main application file
++from auth import login, logout
+
+ def main():
+     print("Welcome to My App!")
+-    # Application initialization code here
++    login("user", "password")
+     pass
+```
+
+### Breaking It Down
+
+**1. File Header**
+```diff
+diff --git a/app.py b/app.py
+```
+- Shows which file is being compared
+- `a/app.py` = old version (before)
+- `b/app.py` = new version (after)
+
+**2. Metadata**
+```diff
+index 1a2b3c4..5d6e7f8 100644
+--- a/app.py
++++ b/app.py
+```
+- `---` indicates the old version
+- `+++` indicates the new version
+- The hashes (1a2b3c4, 5d6e7f8) are internal Git identifiers
+
+**3. Change Location (Hunk Header)**
+```diff
+@@ -1,5 +1,7 @@
+```
+- `@@ -1,5 +1,7 @@` tells you where changes occurred
+- `-1,5` = in the old file, starting at line 1, showing 5 lines
+- `+1,7` = in the new file, starting at line 1, showing 7 lines
+- The file grew by 2 lines (from 5 to 7)
+
+**4. The Actual Changes**
+
+Lines are prefixed with symbols:
+- ` ` (space) = unchanged line (context)
+- `-` (minus) = line removed from old version (shown in red in terminal)
+- `+` (plus) = line added in new version (shown in green in terminal)
+
+In our example:
+```diff
+ # app.py - Main application file          ← unchanged
++from auth import login, logout             ← added (new)
+
+ def main():                                ← unchanged
+     print("Welcome to My App!")            ← unchanged
+-    # Application initialization code here ← removed (old)
++    login("user", "password")              ← added (new)
+     pass                                   ← unchanged
+```
+
+### Reading Multiple Files
+
+If multiple files changed, you'll see multiple diff sections:
+
+```diff
+diff --git a/app.py b/app.py
+[changes to app.py]
+
+diff --git a/auth.py b/auth.py
+[changes to auth.py]
+```
+
+### Pro Tips
+
+- **Context lines**: Unchanged lines around changes help you understand where the change happened
+- **Color coding**: In your terminal, deletions are usually red, additions are green
+- **No newline warning**: If you see `\ No newline at end of file`, it means the file doesn't end with a newline character (usually not important for beginners)
+- **Binary files**: For images or other binary files, Git just says "Binary files differ"
+
+### Try It Yourself
+
+In this module's challenge, you'll use:
+```bash
+git diff <commit1> <commit2> app.py
+```
+
+Pay attention to:
+- Which lines were added (green, with `+`)
+- Which lines were removed (red, with `-`)
+- The surrounding context (white, with space)
 
 ## Useful Commands