Introduction
When working with Git, the git diff command is essential for tracking changes between commits, branches, or files. By default, git diff shows changes at the line level, which can sometimes be too broad—especially when only a few words within a line have been modified.
This is where git diff --word-diff comes in handy. It allows you to see word-level differences, making it easier to pinpoint exact changes in your text. Whether you're reviewing documentation, code comments, or configuration files, --word-diff provides a clearer and more granular view of modifications.
How to Use git diff --word-diff
The basic syntax for git diff --word-diff is:
git diff --word-diff [<options>] [<commit>] [--] [<path>...]
Example 1: Comparing Working Directory Changes
To see word-level differences in your unstaged changes:
git diff --word-diff
Output:
This is a [-sample-]{+demonstration+} text.
Here, -sample- was removed and +demonstration+ was added.
Example 2: Comparing Staged Changes
If you want to check staged changes before committing:
git diff --word-diff --cached
Example 3: Comparing Between Commits
To see word differences between two commits:
git diff --word-diff commit1 commit2
Common Use Cases
1. Reviewing Documentation Changes
When editing Markdown or text files, small word changes matter. --word-diff helps avoid overlooking minor but important updates.
Example:
The [-quick-]{+fast+} brown fox jumps over the lazy dog.
2. Checking Code Comments and Strings
Sometimes, only a variable name or comment changes—--word-diff highlights these precisely.
Example in Python:
# This function [-calculates-]{+computes+} the sum
3. Comparing Configuration Files
For JSON, YAML, or .env files, word-level diff prevents misinterpreting line changes.
Example in JSON:
{
"version": "[-1.0.0-]{+2.0.0+}"
}
Tips and Tricks
While git diff --word-diff is already a powerful tool, there are several hidden tricks and advanced techniques to make it even more useful. Below are some pro tips to supercharge your Git diff workflow.
1. Use --word-diff=color for Better Readability
Instead of the default [-deleted-]{+added+} format, use colored output for easier reading:
git diff --word-diff=color
Example Output:
- Deleted words appear in red.
- Added words appear in green.
This is especially helpful in terminals that support ANSI colors.
2. Define Custom Word Boundaries with --word-diff-regex
By default, Git splits words by whitespace. But what if you want to treat camelCase variables or hyphenated-words as single units?
Example: Treat CamelCase as One Word
git diff --word-diff-regex='[a-zA-Z0-9_]+|[^[:space:]]'
Before:
get[-User-]{+Customer+}Data
After (with custom regex):
[-getUserData-]{+getCustomerData+}
Example: Treat Hyphenated Words as One
git diff --word-diff-regex='[[:alnum:]-]+|[^[:space:]]'
3. Combine --word-diff with --patience for Better Alignment
The --patience algorithm improves diff accuracy by avoiding false matches.
git diff --word-diff --patience
Best for:
- Refactored code where small changes shift line alignments.
- JSON/YAML files where indentation matters.
4. Ignore Whitespace Changes with -b or --ignore-space-change
If you only care about real content changes (not indentation or spaces), use:
git diff --word-diff -b
Example:
# Before (normal diff)
const value = [- getValue()-]{+getValue()+};
# After (`-b` flag)
const value = getValue(); # (No diff if only spacing changed)
5. Use git log -p --word-diff for Historical Word Diffs
Want to see word-level changes in commit history? Combine git log -p with --word-diff:
git log -p --word-diff
Example Output:
commit abc123
Author: John Doe <john@example.com>
Date: Mon Jan 1 12:00:00 2024
Update README
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
This project [-demonstrates-]{+shows+} how to use Git.
6. Compare Specific File Types Differently
Some files (like Markdown) benefit from word-diff, while others (like minified JS) don’t. Use .gitattributes to configure per-file behavior:
echo "*.md diff=word" >> .gitattributes
Now, git diff will automatically use --word-diff for .md files but keep line-diff for others.
7. Use --stat with Word Diff for a Summary
Want a quick summary of word changes (not just lines modified)?
git diff --word-diff --stat
Output:
README.md | 4 [-++--]{+----+}
(Shows that 4 words were changed.)
8. Create a Git Alias for Quick Word Diffs
Tired of typing --word-diff every time? Add an alias:
git config --global alias.wdiff "diff --word-diff"
Now just run:
git wdiff
9. Use --word-diff with Merge Conflicts
When resolving conflicts, sometimes only a few words differ—not entire lines. Use:
git checkout --conflict=diff3 --word-diff
This helps in 3-way merges where small wording changes cause conflicts.
Conclusion
git diff --word-diff is a powerful tool for tracking fine-grained changes in text files, making it invaluable for documentation, code reviews, and configuration management. By focusing on words instead of entire lines, you gain better clarity on modifications.
Next time you need to inspect small but critical changes, try --word-diff and see the difference!
Up Next in the Series: git hooks (pre-commit, pre-push) – Automate checks before commits/pushes
Daily advance GIT tips in your inbox---worth starting? Respond to my poll here🚀
For more useful and innovative tips and tricks, Let's connect on Medium