Git Version Comparison: Practical Tips for Viewing Code Changes with the diff Command

When using Git for version control, we often need to view code changes between different versions—such as what modifications have been made, what new code has been added, and what parts have been deleted. This is where the diff command comes in handy. It clearly shows file change details and is one of the most basic yet practical tools in Git.

一、Why Use `diff`?¶

Imagine you’re modifying a project and later want to recall what changes you made. Or, when collaborating as a team, you need to verify if a teammate’s submitted code is correct. The diff command helps you:
- Compare the working directory (the files you’re editing) with the staging area (files ready to be committed);
- Compare the staging area with a historical commit (e.g., the previous version);
- Compare two historical versions (e.g., two different commits);
- Even compare different branches (e.g., the dev branch vs. the main branch).

二、Basic `diff` Commands and Scenarios¶

Git’s diff command has multiple uses, with core functionality determined by parameters to distinguish the objects being compared. Below are the most common scenarios:

Scenario 1: View Differences Between Working Directory and Staging Area¶

Working Directory: Files you’re editing locally (not yet git added);
Staging Area: Files you’ve staged with git add (not yet committed).

Command:

git diff <filename>  # View differences for a specific file
# Omit the filename to check all modified files

Example:
Suppose you modified main.py from:

print("Hello, Git!")

to:

print("Hello, Git!")
print("This is a test.")  # New line added

Running git diff main.py produces:

diff --git a/main.py b/main.py
index 1234567..8765432 100644
--- a/main.py
+++ b/main.py
@@ -1,1 +1,2 @@
 print("Hello, Git!")
+print("This is a test.")

Interpretation:
- --- a/main.py: Original file (unstaged version in the working directory);
- +++ b/main.py: Modified file (new version after changes);
- @@ -1,1 +1,2 @@: Original file starts at line 1, with 1 line; new file starts at line 1, with 2 lines;
- Lines starting with +: Newly added content (print("This is a test.")).

Scenario 2: View Differences Between Staging Area and Historical Commit¶

If you’ve git added changes but haven’t committed them yet, use the --staged (or --cached) parameter to compare staged content with the last commit:

git diff --staged <filename>  # Compare staging area with the last commit

Example:
After git add main.py, running git diff --staged main.py shows the difference between the staged version and HEAD (the last committed version).

Scenario 3: Compare Two Historical Commits¶

To compare two historical versions (e.g., two different commits), use their commit hashes (e.g., a1b2c3d):

git diff <commit-hash-1> <commit-hash-2>  # Compare two historical commits

Example:
After running git log to find two commit hashes (e.g., abc123 and def456), execute:

git diff abc123 def456

This shows the code changes between these two versions.

Scenario 4: Compare Differences Between Branches¶

To compare code between different branches (e.g., dev vs. main):

git diff <branch-1> <branch-2>  # Compare branch-1 and branch-2

Example:

git diff dev main

This outputs all differences between the two branches’ files.

三、Practical Tips: Refining `diff` Output¶

diff parameters help filter out unnecessary differences (e.g., due to code formatting changes). Here are key parameters:

1. Ignore Whitespace/Empty Line Changes (Fix Formatting Issues)¶

If changes are purely formatting (e.g., spaces, line breaks) but logic remains the same, use:
- -w (or --ignore-all-space): Ignore all whitespace (spaces, tabs);
- -b (or --ignore-space-change): Ignore space changes (but keep line break differences).

Example:

git diff -w main.py  # Ignore all whitespace changes

2. Show Only Filenames (No Content)¶

To list only changed filenames (not their content), use --name-only:

git diff --name-only  # Show only changed filenames

Output:

main.py
utils.py

3. Show Change Statistics¶

Use --stat to quickly see the number of lines modified per file (additions/deletions):

git diff --stat  # Show statistical summary

Output:

 main.py | 2 +-
 utils.py | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

4. Compare Binary Files (Images, Videos, etc.)¶

By default, diff can’t display binary file differences (it shows “Binary files differ”). Use --binary to force display:

git diff --binary image.png  # Compare differences between two images

四、How to Interpret `diff` Output?¶

The most critical symbols in the output are + and -:
- +: Newly added content (new line);
- -: Deleted content (old line);
- (space): No changes.

Example:

@@ -1,3 +1,4 @@
  This is the first line
- This is the second line (deleted)
+ This is the modified second line (new)
+ This is a newly added third line (new)
  This is the fourth line (unchanged)

五、Summary¶

The diff command is one of Git’s most fundamental and powerful tools. Mastering it helps you efficiently manage code changes. Key scenarios and parameters:
- Working Directory vs. Staging Area: git diff;
- Staging Area vs. Historical Commit: git diff --staged;
- Two Historical Commits: git diff <hash1> <hash2>;
- Useful Parameters: -w (ignore whitespace), --stat (show line stats), --name-only (show filenames only).

Practice: Create a local repository, create/edit files, use diff with different parameters to observe effects.

With diff, you can clearly track every code change, avoid accidental commits/merges, and make version control more reliable.

一、Why Use diff?¶

二、Basic diff Commands and Scenarios¶