Why diffing matters in Git - Why It Works This Way

Overview - Why diffing matters

What is it?

Diffing is the process of comparing two versions of files or code to see what has changed between them. It highlights additions, deletions, and modifications line by line. This helps developers understand exactly what was altered in a project over time. Diffing is a core feature in version control systems like git.

Why it matters

Without diffing, developers would struggle to track changes, find bugs, or collaborate effectively. It would be like trying to spot differences between two similar documents by eye, which is slow and error-prone. Diffing makes reviewing changes fast, clear, and reliable, enabling teamwork and quality control in software projects.

Where it fits

Before learning diffing, you should understand basic file editing and version control concepts like commits. After mastering diffing, you can learn advanced git workflows, code reviews, and merge conflict resolution. Diffing is a foundational skill in the journey of mastering git and collaborative software development.

Mental Model

Core Idea

Diffing is like a spotlight that shows exactly what changed between two versions, making differences clear and easy to understand.

Think of it like...

Imagine comparing two printed pages side by side and using a highlighter to mark every word that was added, removed, or changed. Diffing does this automatically for code or text files.

┌───────────────┐       ┌───────────────┐
│ Version A     │       │ Version B     │
│ Line 1: foo   │       │ Line 1: foo   │
│ Line 2: bar   │  -->  │ Line 2: baz   │
│ Line 3: qux   │       │ Line 3: qux   │
└───────────────┘       └───────────────┘
         │                     │
         └───── Diff shows ───┘
         ┌────────────────────┐
         │ Line 2 changed:     │
         │ 'bar' → 'baz'       │
         └────────────────────┘

Build-Up - 6 Steps

1

Foundation

What is diffing in git

Concept: Diffing compares two sets of files or code to find differences.

Git diff is a command that shows changes between commits, branches, or your working files. It lists lines added, removed, or changed with symbols: '+' for additions and '-' for deletions.

Result

You see a clear list of changes between two versions of your files.

Understanding diffing is essential because it reveals exactly what changed, which is the foundation for tracking and reviewing code.

2

Foundation

Basic git diff usage

Concept: How to run git diff to see unstaged changes.

Run 'git diff' in your project folder to see changes you made but haven't saved to git yet. It compares your working files to the last commit.

Result

Terminal shows lines you added or removed since last commit.

Knowing how to check your current changes helps you catch mistakes before saving them permanently.

3

Intermediate

Diffing between commits and branches

🤔Before reading on: do you think 'git diff commit1 commit2' shows changes from commit1 to commit2 or the other way around? Commit to your answer.

Concept: You can compare any two commits or branches to see what changed between them.

Use 'git diff ' to see differences from commit1 to commit2. For branches, 'git diff branch1 branch2' shows what changed from branch1 to branch2.

Result

You get a detailed list of changes between two points in history.

Understanding direction in diffing prevents confusion about what changes are new or old.

4

Intermediate

Using diff for code reviews

🤔Before reading on: do you think diffing helps find only bugs or also improves collaboration? Commit to your answer.

Concept: Diffs are used to review code changes before merging them into main projects.

Developers share diffs to show what they changed. Reviewers read diffs to check for errors, style, or logic issues before accepting changes.

Result

Teams catch problems early and keep code quality high.

Knowing diffing supports collaboration helps you appreciate its role beyond just spotting bugs.

5

Advanced

Diffing with context and options

🤔Before reading on: do you think showing more lines around changes helps or clutters the diff? Commit to your answer.

Concept: Git diff can show extra lines around changes for better understanding.

Use 'git diff -U5' to show 5 lines of context around changes. Other options like '--stat' summarize changes by file size.

Result

Diff output is easier to read and understand in context.

Knowing how to adjust diff output helps you tailor reviews to your needs and avoid confusion.

6

Expert

How diffing impacts merge conflicts

🤔Before reading on: do you think diffing alone resolves merge conflicts or just helps identify them? Commit to your answer.

Concept: Diffing shows conflicting changes that git cannot merge automatically.

When two branches change the same lines differently, git flags a conflict. Diffing helps you see both versions side by side to decide how to combine them.

Result

You can manually fix conflicts by understanding exactly what changed on each side.

Understanding diffing's role in conflicts prevents frustration and speeds up resolution.

Under the Hood

Git stores snapshots of your files as commits. Diffing compares these snapshots line by line using algorithms like Myers' diff algorithm. It detects additions, deletions, and modifications by matching unchanged lines and highlighting differences. This process is efficient even for large projects.

Why designed this way?

Diffing was designed to be fast and human-readable to support collaboration and debugging. Early tools used simple line-by-line comparisons, but git improved this with efficient algorithms and flexible options to handle complex changes and merges.

┌───────────────┐       ┌───────────────┐
│ Commit A      │       │ Commit B      │
│ File content  │       │ File content  │
└──────┬────────┘       └──────┬────────┘
       │                       │
       │  Myers' diff algorithm │
       └────────────┬──────────┘
                    │
           ┌────────▼────────┐
           │ Diff output     │
           │ (+ additions,   │
           │  - deletions)   │
           └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does 'git diff' show changes already staged for commit? Commit yes or no.

Common Belief: Git diff shows all changes including staged ones.

Reality: Git diff only shows unstaged changes; 'git diff --staged' or 'git diff --cached' shows staged changes.

Why it matters: Confusing this leads to missing what is actually staged for commit, causing unexpected commits.

Quick: Is diff output always symmetrical, meaning diff A to B equals diff B to A? Commit yes or no.

Common Belief: Diffs are symmetrical and show the same changes both ways.

Reality: Diffs are directional; diff A to B shows changes to get from A to B, which is different from B to A.

Why it matters: Misunderstanding direction causes confusion about what changes are new or removed.

Quick: Can diffing alone fix merge conflicts automatically? Commit yes or no.

Common Belief: Diffing resolves conflicts by itself.

Reality: Diffing only shows conflicts; humans or tools must resolve them manually or with merges.

Why it matters: Expecting automatic fixes leads to frustration and broken merges.

Quick: Does diffing compare only code files? Commit yes or no.

Common Belief: Diffing only works on code files.

Reality: Diffing works on any text files, including configs, docs, scripts, and more.

Why it matters: Limiting diffing to code reduces its usefulness in real projects with many file types.

Expert Zone

1

Diff algorithms optimize for minimal changes, but sometimes show unexpected line moves as deletions and additions.

2

Whitespace and line-ending differences can clutter diffs; git offers options to ignore these for cleaner output.

3

Binary files cannot be diffed line-by-line; git shows only that they differ, requiring other tools for content comparison.

When NOT to use

Diffing is less useful for binary files or very large files where line-by-line comparison is impractical. In such cases, use specialized binary diff tools or file hashes. Also, for very complex merges, graphical merge tools may be better than raw diffs.

Production Patterns

In real projects, diffs are used in pull requests for code review, automated testing pipelines to detect changes, and during merges to resolve conflicts. Teams often customize diff settings to ignore whitespace or use side-by-side views for clarity.

Connections

Code Review

Diffing is the foundation for code review processes.

Understanding diffing deeply helps you give precise feedback and catch subtle bugs during reviews.

Merge Conflict Resolution

Diffing reveals conflicting changes that need manual resolution.

Knowing how diffs show conflicts speeds up fixing merges and prevents errors.

Text Comparison in Document Editing

Diffing in git is similar to track changes in word processors.

Recognizing this connection shows how diffing concepts apply beyond code to any collaborative editing.

Common Pitfalls

#1 Confusing unstaged and staged changes in git diff.

Wrong approach:

git diff --staged

Correct approach:

git diff

Root cause:

Misunderstanding that 'git diff' shows unstaged changes and '--staged' shows staged ones.

#2 Expecting diff output to be symmetrical.

Wrong approach:

git diff commitB commitA

Correct approach:

git diff commitA commitB

Root cause:

Not realizing diff direction matters and changes are shown from first to second argument.

#3 Trying to diff binary files as text.

Wrong approach:

git diff image.png

Correct approach:

Use specialized binary diff tools outside git.

Root cause:

Assuming all files can be compared line-by-line like text.

Key Takeaways

Diffing is the essential process that shows exactly what changed between two versions of files.

It enables developers to track changes, review code, and collaborate effectively in software projects.

Diffs are directional and can be customized to show context or ignore irrelevant differences like whitespace.

Understanding diffing deeply helps resolve merge conflicts and improves code quality through better reviews.

Diffing applies beyond code to any text-based files, making it a versatile tool in many collaborative workflows.