When reviewing software patches, inspecting Git pull requests, or comparing directory trees in Linux, looking through hundreds of lines of raw unified diff output (+ and - notations) makes it difficult to assess the scope and proportionality of a changeset. Determining how many files were touched, the distribution of insertions versus deletions, and which specific modules received the heaviest modifications requires manual tallying.
The Linux command-line utility diffstat solves this problem by parsing diff output and generating a clean, human-readable statistical histogram. Developed and maintained by Thomas Dickey, diffstat is widely used across the Linux kernel mailing list, open-source maintainer workflows, and CI/CD audit pipelines. This guide explains how to install diffstat across popular Linux distributions, pipe standard diff and Git commands into it, interpret visual histogram charts, and customise output formatting.
Installing diffstat on Linux Distributions
The diffstat package is available directly within the official package repositories of all major Linux distributions.
On Ubuntu, Debian, and Linux Mint
sudo apt update && sudo apt install diffstat -y
On Fedora, CentOS, and RHEL
sudo dnf install diffstat -y
On Arch Linux and Manjaro
sudo pacman -S diffstat
Confirm successful installation by checking the program version:
diffstat -v
Basic Usage: Piping Diff Output into diffstat
The core operating mechanism of diffstat involves reading patch text from standard input (stdin) or passing a patch file directly as an argument. Consider the common scenarios below:
1. Summarising Differences Between Two Local Files
To inspect changes between an original script and a modified version:
diff -u original.py modified.py | diffstat
2. Summarising Differences Between Two Directories
When auditing changes across an entire codebase tree:
diff -ruN project-v1.0/ project-v1.1/ | diffstat
3. Analysing an Existing Patch or Diff File
If you have downloaded a patch file (e.g. kernel-fix.patch):
diffstat kernel-fix.patch
Piping Git Diffs into diffstat
While Git provides an integrated git diff --stat command, piping raw Git diffs into diffstat unlocks custom sorting, colorised histogram scaling, and deeper column formatting controls.
Inspect Uncommitted Working Changes
git diff | diffstat
Inspect Staged Changes Scheduled for Commit
git diff --cached | diffstat
Compare Two Git Branches
git diff main..feature-branch | diffstat
Audit a Specific Commit Hash
git show a1b2c3d | diffstat
Interpreting diffstat Histogram Output
A typical diffstat execution prints output formatted into four distinct columns:
src/auth.c | 42 ++++++++++++++++++++++--------------------
src/config.h | 8 ++++++--
src/main.c | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++-----------------------------------------
3 files changed, 98 insertions(+), 66 deletions(-)
- File Column (Left): Displays the path of each modified file. Long paths are cleanly truncated or aligned.
- Delimiter (
|): Separates the path from numerical metrics. - Change Count (Middle): The absolute total number of lines modified (insertions plus deletions).
- Visual Histogram (Right):
+(plus characters): Indicates added lines.-(minus characters): Indicates removed lines.!(exclamation marks): Appears if context diff format is used to indicate in-place line modifications.
- Summary Line (Bottom): Synthesises total files modified, total insertions, and total deletions.
Advanced Formatting and Histogram Customisation
You can fine-tune diffstat using flags to suit terminal dimensions or pipeline reporting standards:
Sorting Output by Total Changes or File Paths
- Sort alphabetically by file name (default):
diffstat patch.diff - Sort by total change count descending:
diffstat -s patch.diff - Sort by insertions descending:
diffstat -r 1 patch.diff - Sort by deletions descending:
diffstat -r 2 patch.diff
Enabling Terminal Colour Coding
By default, diffstat outputs monochrome text. Adding the -C flag colorises added characters in green and removed characters in red, mirroring modern terminal diff viewers:
git diff | diffstat -C
Adjusting Terminal Width
If you are generating reports on wide monitors or inside narrow logs, adjust the total histogram column width using -w:
git diff | diffstat -w 80
Displaying Summary Statistics Only
To suppress individual file breakdowns and output solely the bottom summary totals, pass the -q (quiet) flag:
diffstat -q massive-refactor.patch
Flag Reference Cheatsheet
| Command Flag | Function Description | Common Use Case |
|---|---|---|
-C |
Enables ANSI syntax colour highlighting | Interactive terminal code reviews |
-s |
Sorts output by total modifications descending | Quickly pinpointing the most heavily edited files |
-w <num> |
Sets fixed terminal character width | Constraining output for email patches or markdown |
-p <num> |
Strips leading pathname components (similar to patch -p) | Normalising directory paths across diverse checkouts |
-q |
Quiet mode; suppresses file-by-file histogram | Quick pass/fail metrics in CI scripts |
Troubleshooting Common diffstat Quirks
- diffstat returns blank output or no files listed: Ensure the input data represents a valid unified diff (
diff -u) or context diff (diff -c). Standard default diffs without context headers cannot be parsed bydiffstat. - Binary files missing from statistics: Standard unified diff generators omit binary content (such as PNG images or compiled ELF binaries).
diffstatprints a brief note indicating that binary files were skipped. Usegit diff --binaryif tracking binary asset modifications. - Histogram wraps awkwardly across multiple terminal lines: If file paths are exceptionally long,
diffstatmay wrap the histogram bar. Pass the-p 1or-p 2flag to strip superfluous parent directory hierarchies and preserve tabular formatting.