A diff patch is a text file that records the line-by-line differences between two versions of one or more files, in a format that a tool can later apply to reproduce those exact changes on another copy. The diff is the comparison output; the patch is that output used to transform files. This mechanism is the foundation of code review, version control, and distributing changes: it lets you share just what changed, in a compact, reviewable, and reversible form, rather than shipping whole files.
Key takeaways
- A diff describes changes between file versions; applying it as a patch reproduces them.
- Unified diff format is the standard, using
+,-, and@@hunk headers. - Context lines around each change let patches apply even after line shifts.
- Apply patches with the
patchcommand orgit apply. - The
-poption strips leading path segments so paths line up. - Patches are reversible and can be rejected if the target has diverged too far.
How do I generate a diff?
The classic tool is diff, and the widely used style is unified format, requested with -u:
diff -u original.txt modified.txt > changes.patchIn a Git repository you generate the same kind of output for tracked files with:
git diff > changes.patchBoth produce a text file describing what to add and remove. Because the output is plain text, you can email it, attach it to an issue, or commit it, and anyone with the original files can apply it.
How do I read unified diff format?
A unified diff is organized into hunks, each introduced by a header showing the affected line ranges. Consider:
--- original.txt
+++ modified.txt
@@ -1,4 +1,4 @@
line one
-line two old
+line two new
line three
line fourReading it piece by piece:
- The
---and+++lines name the old and new files. @@ -1,4 +1,4 @@is the hunk header: the old file section starts at line 1 for 4 lines, and the new one likewise.- Lines starting with a space are context, unchanged and shown to locate the edit.
- Lines starting with
-are removed; lines starting with+are added.
A changed line appears as a - immediately followed by a +, which is how the format represents an edit rather than a pure insertion or deletion.
One special marker is worth recognizing. If a file does not end in a newline, the diff includes a line reading No newline at end of file. This is not noise; it records a real difference, because a trailing newline is itself a byte in the file. Ignoring it is a frequent cause of a patch that looks identical yet refuses to apply cleanly, since the context around the file’s end genuinely differs by that one character.
How do I apply a patch file?
The traditional tool is patch, which reads the diff and edits the target files:
patch -p1 < changes.patchFor patches produced by Git, prefer the Git tools, which understand Git-specific metadata such as renames and mode changes:
git apply changes.patchTo carry along the commit message and authorship from a patch created with git format-patch, use git am changes.patch instead, which recreates the commit rather than just the file edits.
What does the -p option do?
Diffs often carry path prefixes that do not match your local layout. Git, for instance, writes paths like a/src/app.js and b/src/app.js. The -p option strips leading directory components so the paths line up with where you are applying from.
| Option | Path in patch | Applied to |
|---|---|---|
-p0 |
a/src/app.js |
a/src/app.js |
-p1 |
a/src/app.js |
src/app.js |
-p2 |
a/src/app.js |
app.js |
Run patch from the same directory the diff was generated relative to, and choose the -p level that makes the remaining path match your files. For Git-style diffs applied from the project root, -p1 is almost always correct.
Why do patches rely on context lines?
A naive approach would record only line numbers, but line numbers shift the moment anyone edits earlier in the file. Unified diffs instead include a few unchanged lines around each change. When applying, the tool searches for that surrounding context to locate the right spot, so a patch still applies cleanly even if the target has grown or shrunk above the change.
This resilience has limits. If the context itself has been edited, the tool cannot find a match and the hunk is rejected. That is the core trade-off of patch-based workflows: they are robust to distant edits but fragile to edits inside the changed region.
What happens when a patch fails, and how do I reverse one?
When a hunk cannot be placed, patch reports a failure and typically writes a .rej file containing the rejected hunks so you can apply them by hand. Common causes are a target file that has diverged, the wrong -p level, or mismatched line endings.
Patches are reversible. To undo a patch you previously applied, run it in reverse:
patch -R < changes.patch
git apply -R changes.patchReversibility is why patches are a safe way to trial a change: apply it, test, and cleanly back it out if needed.
Before committing to an apply, you can preview the outcome. The --dry-run option to patch, and git apply --check, report whether every hunk would apply without touching any files. This is the safest first step with an unfamiliar patch, because it surfaces path and context problems before they leave half-applied changes on disk. When a hunk almost matches, patch can apply it with a fuzz factor, ignoring a limited number of context lines to force a fit. Fuzz is convenient but risky, since it can place a change in a slightly wrong spot, so review the result whenever fuzz was used rather than trusting it blindly.
What diff formats and options are worth knowing?
Unified format is the default for good reason, but a few variants and options solve specific problems.
| Form | How to get it | Best for |
|---|---|---|
| Unified | diff -u |
Code review and patches |
| Context | diff -c |
Older tools expecting context format |
| Side by side | diff -y |
Reading two versions at a glance |
| Recursive | diff -ru |
Comparing whole directory trees |
Several options make diffs cleaner and patches more likely to apply. -w and -b ignore whitespace differences, which is invaluable when reformatting has muddied a diff. When comparing entire directories, add -ru to recurse and produce one combined patch covering many files. Git offers its own knobs, such as git apply --3way, which falls back to a three-way merge using blob information so a patch can still apply against a moderately changed file rather than failing outright. Choosing the right option often turns a rejected patch into a clean one.
What are common diff and patch pitfalls?
- Wrong directory or -p level. The most frequent failure is applying from the wrong location so paths do not resolve.
- Line-ending mismatches. Mixing Windows and Unix line endings makes context fail to match; normalize them first.
- Whitespace changes. Invisible whitespace differences can block a hunk; use whitespace-ignoring options when applying.
- Stale patches. A patch made against an old version may not fit current files; regenerate it against the latest base.
- Binary files. Plain
diffhandles text; binary changes need Git’s binary diff support or a different tool.
Frequently asked questions
What is the difference between a diff and a patch?
A diff is the description of changes produced by comparing two versions; a patch is that diff used as input to reproduce the changes on another copy. In practice the words are often used interchangeably.
What is unified diff format?
Unified format is the common diff style showing changed lines with a few lines of surrounding context, marked with + for additions and – for removals under @@ hunk headers.
How do I apply a patch file?
Use the patch command, as in patch -p1 with the patch as input, or git apply for Git-generated patches. The -p option strips leading path components to match your directory.
What does the -p1 option mean?
It strips one leading directory component from the file paths in the patch, which aligns paths like a/src/file with your local src/file when applying from the project root.
Can a patch fail to apply?
Yes. If the target file has changed too much, the context no longer matches and the patch is rejected, often leaving .rej reject files describing the hunks that failed.
How do I reverse a patch?
Apply it with the reverse option, patch -R or git apply -R, which undoes the changes the patch would have made.
Why include context lines in a diff?
Context lines let the patch tool locate the right place to apply each change even if line numbers have shifted, making patches far more robust than raw line-number edits.