Linux command: diff

1. The Basics

diff compares two files line by line and describes what you would have to change in the first one to turn it into the second. That direction matters: a diff is not a neutral list of differences, it is a recipe with a from and a to.

1.1 The Simplest Possible Use

Two versions of a small configuration file:

$ diff old.php new.php
3c3
<     'host'  => 'localhost',
---
>     'host'  => 'db.internal',
5c5
<     'debug' => false,
---
>     'debug' => true,

This is the original 1974 output format, and it reads like a set of edits:

Two other letters appear in place of c: a for lines added and d for lines deleted. So 7a8 means "after line 7 of the old file, add what becomes line 8 of the new one".

You will rarely use this format on purpose. Section 4 covers the two you actually want. It is worth recognising, because it is what you get when you forget to ask for anything else.

1.2 The Exit Code Is the Point

The output is for humans. The exit code is what makes diff useful in a script, and it has three values:

$ diff old.php old.php >/dev/null ; echo $?
0                                  # the files are identical

$ diff old.php new.php >/dev/null ; echo $?
1                                  # they differ

$ diff old.php nosuch.php >/dev/null 2>&1 ; echo $?
2                                  # something went wrong

That 2 is the one people forget. A missing file, an unreadable directory or a bad option all produce it, and a script that treats "not zero" as "the files differ" will report a difference that was really a typo in a path.

if diff -q "$a" "$b" >/dev/null; then
    echo "identical"
elif [ $? -eq 1 ]; then
    echo "they differ"
else
    echo "diff itself failed"
fi

The right mental model: diff does not tell you that two files are different. It writes down the instructions for turning the first into the second, in a format precise enough that patch can follow them without you.

3. A Short History

diff came out of Bell Labs in the mid-1970s, and the problem it solved was not source control. It was that computers were slow and disks were small, and storing the difference between two versions of a file was far cheaper than storing both.

The part of the story that changed how software is written came later. In 1985 Larry Wall released patch, and the combination of the two turned a diff from a description into a delivery mechanism. Software was distributed by posting diffs to Usenet newsgroups, where anyone could apply them to their own copy of the source.

The manual page for patch still credits the people involved, and one name in it explains the format you read every day:

$ man patch
AUTHORS
       Larry Wall wrote the original version of patch.  Paul Eggert removed
       patch's arbitrary limits; added support for binary files, setting
       file times, and deleting files; ...  Other contributors include
       Wayne Davison, who added unidiff support, and David MacKenzie, who
       added configuration and backup support.

"Unidiff support" is the unified format. It is worth appreciating how completely it won: GitHub, GitLab, every code review tool, and git diff itself all print the format that was added to a 1985 program so that patches would fit in an email.

Learning to read a unified diff is not learning a Unix command. It is learning the format that every code review in the world is written in.

5. Moderate Use Cases

5.1 Comparing Two Directories

This is where diff stops being a programmer's tool and becomes an administrator's one. -r (short for recursive) walks two trees:

$ diff -r v1 v2
Only in v2: added.txt
diff -r v1/changed.txt v2/changed.txt
1c1
< old
---
> new
diff -r v1/inc/deep.txt v2/inc/deep.txt
1c1
< x
---
> y
Only in v1: removed.txt

On two real websites that output is thousands of lines long. Almost always what you want is -q as well (short for brief), which reports which files differ without printing their contents:

$ diff -rq v1 v2
Only in v2: added.txt
Files v1/changed.txt and v2/changed.txt differ
Files v1/inc/deep.txt and v2/inc/deep.txt differ
Only in v1: removed.txt

diff -rq is the single most useful command in this article for anyone who runs servers. It answers "what is different between these two copies of the site?" in one line, and it is the first thing to run when a deployment has gone wrong, when you suspect a core file has been modified, or when you want to know what an update actually changed.

One option changes its meaning. -N treats a missing file as an empty one, so "only in" becomes "differs":

$ diff -rqN v1 v2
Files v1/added.txt and v2/added.txt differ
Files v1/changed.txt and v2/changed.txt differ
Files v1/inc/deep.txt and v2/inc/deep.txt differ
Files v1/removed.txt and v2/removed.txt differ

Use -N when you are generating a patch, because a patch must be able to create and delete files. Leave it off when you are reading the output yourself, because "only in" is more informative than "differs".

Before you trust any of this, read section 7.1. diff -rq compares file contents and nothing else, and what it leaves out matters more than most people expect.

5.2 Excluding Files and Directories

On a real site the previous command drowns in noise. Caches, logs and generated thumbnails differ constantly and tell you nothing:

$ diff -rq site-a site-b
Files site-a/cache/x.tmp and site-b/cache/x.tmp differ
Files site-a/index.php and site-b/index.php differ
Files site-a/logs/error.log and site-b/logs/error.log differ

Only the middle line matters. -x (short for exclude) takes a shell-style pattern and can be repeated:

$ diff -rq -x cache -x '*.log' site-a site-b
Files site-a/index.php and site-b/index.php differ

Once the list grows, put it in a file and pass it with -X. That file belongs in version control next to whatever script runs the comparison:

$ cat skip.txt
cache
logs
tmp
*.log

$ diff -rq -X skip.txt site-a site-b
Files site-a/index.php and site-b/index.php differ

One rule catches everybody once: the pattern is matched against the file name, not the path. Writing a path with a slash in it silently matches nothing:

$ diff -rq -x 'logs/*' site-a site-b
Files site-a/cache/x.tmp and site-b/cache/x.tmp differ
Files site-a/index.php and site-b/index.php differ
Files site-a/logs/error.log and site-b/logs/error.log differ    <-- not excluded

Exclude logs, not logs/* and not site-a/logs. The name on its own is what diff compares each entry against as it walks the tree, and excluding a directory by name skips everything inside it.

5.3 Ignoring What You Do Not Care About

By default every byte counts, including whitespace:

$ diff ws1.txt ws2.txt
1,2c1,2
< hello world
< second line
---
> hello  world
> second line   

One line gained a space in the middle, the other gained trailing spaces, and both are reported. Four flags turn that off, from mildest to broadest:

There is also -I, which takes a regular expression and ignores any change on a line matching it. This is how you compare two generated reports without the timestamp at the top making every file look different:

$ diff r1.txt r2.txt
1c1
< Generated: 2026-08-23
---
> Generated: 2026-08-24
$ echo $?
1

$ diff -I '^Generated:' r1.txt r2.txt
$ echo $?
0

Use these to investigate, not to decide. A whitespace change is invisible to -w and highly visible to Python, YAML, and anything that reads a here-document.

5.4 The Line-Ending Trap

Every so often a file that "nobody touched" shows every single line as changed. This is almost always line endings, and it is the most common false alarm in web work, because a file edited on Windows and uploaded by FTP comes back with a carriage return on every line.

$ diff crlf.txt lf.txt | cat -A
1,2c1,2$
< line one^M$
< line two^M$
---$
> line one$
> line two$

The ^M at the end of each line is the carriage return, made visible by cat -A. Without that trick the two sides look identical and the diff looks insane. Two commands confirm it and one flag ignores it:

$ file crlf.txt lf.txt
crlf.txt: ASCII text, with CRLF line terminators
lf.txt:   ASCII text

$ diff --strip-trailing-cr crlf.txt lf.txt ; echo $?
0

Fixing the file properly is better than ignoring the difference forever. dos2unix does it, and so does sed -i 's/\r$//' file on a machine that does not have it.

5.5 When It Is Not Text

diff gives up on binary files, and says so:

$ diff bin1.dat bin2.dat
Binary files bin1.dat and bin2.dat differ

That is usually all you need, and the exit code still works. When you want detail, cmp is the right tool: it compares byte by byte and tells you where the first difference is.

$ cmp bin1.dat bin2.dat
bin1.dat bin2.dat differ: byte 25, line 1

$ cmp -l bin1.dat bin2.dat | head -3
 25  60 300
 26 155  72
 41  50  30

cmp -l lists every differing byte with its position and the two values in octal. For a plain yes-or-no on large files, cmp -s (silent) and diff -q are equally quick, because both stop at the first difference; on a pair of identical 200 MB files here they took 0.059s and 0.062s. Choose cmp when you want to know where the difference is, and diff when you want to know what it says.

When you need to actually look at the bytes, turn them into text first and diff that. xxd produces a hex dump with one line per sixteen bytes, which is exactly the shape a line-based tool wants:

$ diff -u <(xxd h1.bin) <(xxd h2.bin)
@@ -1,4 +1,4 @@
 00000000: 7f45 4c46 0201 0100 0000 0000 0000 0000  .ELF............
-00000010: 0300 3e00 0100 0000 306d 0000 0000 0000  ..>.....0m......
-00000020: 4000 0000 0000 0000 2824 0200 0000 0000  @.......($......
+00000010: 0300 3e00 0100 0000 c03a 0000 0000 0000  ..>......:......
+00000020: 4000 0000 0000 0000 1892 0000 0000 0000  @...............

This does not make binary formats readable, but it turns "these two files differ somewhere" into "these two files differ at offset 0x10 and 0x20", which is often enough to recognise a version number, a timestamp or a header field.

5.6 Comparing Things That Are Not Files

Bash lets you hand the output of a command to anything expecting a filename, using <(...). This removes the temporary files from a whole category of checks:

$ diff <(printf 'apache2\nmysql\nphp\n') <(printf 'apache2\nnginx\nphp\n')
2c2
< mysql
---
> nginx

The same idea answers real questions about two servers:

$ diff <(ssh web1 'dpkg -l | sort') <(ssh web2 'dpkg -l | sort')
$ diff <(ssh web1 'php -m | sort') <(ssh web2 'php -m | sort')
$ diff <(cd /var/www/live && find . | sort) <(cd /var/www/staging && find . | sort)

Sort both sides. diff compares in order, so two identical package lists in a different order produce pages of noise. That one habit is what makes this technique usable.

There is one rough edge. Because the "files" are anonymous pipes, the header names them after file descriptors, which tells you nothing:

$ diff -u <(echo a) <(echo b) | head -2
--- /dev/fd/63	2026-08-23 18:33:16.048005790 +0200
+++ /dev/fd/62	2026-08-23 18:33:16.048005790 +0200

--label replaces them, once per side, in order:

$ diff -u --label production --label staging <(echo a) <(echo b) | head -2
--- production
+++ staging

Use it whenever the output will be read by someone else or pasted into a ticket. A diff whose two sides are called production and staging needs no explanation; one whose sides are called /dev/fd/63 and /dev/fd/62 needs a paragraph.

5.7 Normalise Before You Compare

The previous section ended on a habit worth stating as a rule: the best comparison is usually not a comparison of the raw input. Two sides can hold the same information in a different order, a different layout or a different encoding, and a line-based tool will report all of it as change.

The pattern is always the same:

raw input  -->  normalise  -->  compare

Sort, and pin the locale. Sorting both sides is the obvious half. The half almost nobody mentions is that sort order itself depends on the locale, so the same data sorted on two machines with different language settings does not match:

$ cat loc.txt
apple
Banana
cherry

$ LC_ALL=en_US.UTF-8 sort loc.txt
apple Banana cherry

$ LC_ALL=C sort loc.txt
Banana apple cherry           <-- capitals first, by byte value

Diff those two orderings against each other and you get differences on every line, from identical input. When the two sides come from two different servers, that is exactly what happens. Pin the locale on both sides and the problem disappears:

$ diff <(LC_ALL=C sort list1.txt) <(LC_ALL=C sort list2.txt)
$ diff <(ssh web1 'LC_ALL=C dpkg-query -W | sort') \
       <(ssh web2 'LC_ALL=C dpkg-query -W | sort')

LC_ALL=C gives a plain byte ordering that is the same everywhere. It is not the ordering a human would choose, and that does not matter, because nobody is reading it: the two sides only have to agree.

Use a format-aware tool where one exists. Reformatted JSON is a total rewrite as far as diff is concerned, even when nothing changed. jq -S reprints it with the keys sorted, so only real differences survive:

$ diff -u --label old --label new <(jq -S . old.json) <(jq -S . new.json)

The same idea covers most "why is everything different?" complaints: pretty-print the XML, sort the database dump, strip the timestamp header with -I, canonicalise the line endings. Do the normalising once, in the command, and the diff becomes readable.

7. Something Most Users Do Not Know

7.1 diff -rq Compares Content and Nothing Else

Section 5.1 called diff -rq the most useful command in this article. It is, and it will also tell you that two directories match when they are meaningfully different, because it compares file contents and nothing else.

Here are two directories. One file has the same contents in both, but its permissions and its timestamp differ:

$ ls -l p1/f.txt p2/f.txt
-rw-r--r-- Jan  1  2020  p1/f.txt
-rwxrwxrwx Aug 23 17:16  p2/f.txt

$ diff -rq p1 p2
$ echo $?
0                                  <-- "identical"

A file went from 644 to world-writable 777 and diff reported nothing at all. On a website that is the difference between a hardened file and one anybody can rewrite, and a restore verified this way passes with the permissions wrong.

Symbolic links are worse, because diff follows them. Here s1/ptr is a symlink and s2/ptr is a real file with the same content:

$ ls -l s1/ptr s2/ptr
lrwxrwxrwx  s1/ptr -> real.txt
-rw-rw-r--  s2/ptr

$ diff -rq s1 s2
$ echo $?
0                                  <-- still "identical"

The structure was destroyed and the check passed. For any site using the standard current -> releases/2026-08 deployment layout, that is exactly the failure that would matter, and exactly the one this command hides.

Modern GNU diff has a flag for it:

$ diff -rq --no-dereference s1 s2
File s1/ptr is a symbolic link while file s2/ptr is a regular file
$ echo $?
1

So the honest summary of what diff -rq checks is short:

Section 7.5 gives the command that covers the rest.

7.2 Fuzz Will Apply Your Patch to Code That Moved On

Section 6.4 showed a patch failing loudly. This is the failure that does not.

patch finds a hunk by matching its context lines. When it cannot match all of them, it does not stop: it tries again while ignoring the outermost lines of context. The manual states the limit plainly:

$ man patch
       First patch looks for a place where all lines of the context match.
       If no such place is found, and it's a context diff, and the maximum
       fuzz factor is set to 1 or more, then another scan takes place
       ignoring the first and last line of context.  If that fails, and the
       maximum fuzz factor is set to 2 or more, the first two and last two
       lines of context are ignored, and another scan is made.
       (The default maximum fuzz factor is 2.)

Watch what that permits. Here the function the patch was written against has been renamed by somebody else, so the context no longer matches:

$ patch -p1 < ../fix.patch
patching file components/helper.php
Hunk #1 succeeded at 1 with fuzz 2.
$ echo $?
0

Exit code 0. A script sees success. But patch has just written a change into a file whose surrounding code is not the code the patch author was looking at, because it threw away two lines of context at each end in order to find a match.

Sometimes that is exactly right and it saves you an afternoon. Sometimes it puts a fix in a function that is no longer the function it was meant for. The point is that you were not asked.

patch succeeding is not the same as patch being correct. Any line that mentions fuzz means the file had drifted and patch guessed; read what it did before you move on.

For anything unattended, turn the guessing off. -F0 sets the maximum fuzz to zero, so a hunk either matches exactly or fails:

$ patch -p1 -F0 < ../fix.patch
patching file components/helper.php
Hunk #1 FAILED at 1.
1 out of 1 hunk FAILED -- saving rejects to file components/helper.php.rej
$ echo $?
1

That is the behaviour you want in a deployment script: a clear failure you can act on, rather than a silent success you have to discover later.

7.3 diff Does Not See a Moved Block

diff is not comparing line 1 with line 1 and line 2 with line 2. If it were, inserting a single line at the top of a file would report every line below it as changed. Instead it looks for the longest run of lines the two files have in common and treats everything else as inserted or deleted, which is why a one-line insertion reports as exactly one added line.

That alignment is what makes diff useful, and it has a blind spot: it has no concept of a move. Take a file and swap the order of two functions, changing nothing inside them:

$ diff -u mv1.txt mv2.txt
@@ -1,6 +1,6 @@
 header
-function A
-body A
 function B
 body B
+function A
+body A
 footer

Nothing was added and nothing was removed, but the diff shows two deletions and two additions. To the tool there is no difference between "this block moved" and "this block was deleted here and an identical one was written there".

This matters in review. A patch that reorders a large file looks enormous and reads as though everything was rewritten, and the genuinely new lines are buried among the moved ones. Three ways out, in order of how much you have to install:

• Do not mix moves with edits. If you are going to reorder a file, do it in one change that only reorders, so the next diff is readable.
• Ask for a different alignment. -d (--minimal) tells diff to "try hard to find a smaller set of changes". It is slower, and on straightforward files it usually returns the same answer, but on a badly aligned diff it is worth one attempt.
• Use a tool that tracks moves when reviewing, such as git diff --color-moved, which paints moved blocks in a different colour instead of pretending they are new.

The wider point is that a diff is one valid description of how to get from A to B, not the only one and not necessarily the one a human would have written. Two tools can produce different-looking output for the same pair of files and both be correct.

7.4 A Diff Is a Program, Not a Report

Everything else in this article follows from one idea that is easy to miss: the output of diff is machine-readable by design, and the machine that reads it is patch.

That is why the format is so fussy. The leading space on context lines is not decoration, it is the marker for "unchanged" and removing it breaks the patch. The line counts in the @@ header must match the number of lines that follow. An editor that strips trailing whitespace can invalidate a patch file. So can a mail client that wraps long lines, which is why patches were traditionally sent as attachments and why every project has a page about how not to mangle them.

It also explains the two rules that surprise people:

• Never edit a patch file to "fix" it unless you are prepared to fix the line counts in every hunk header you touch.
• Never let colour into a patch. --color=always > fix.patch produces a file that looks perfect and that patch cannot read, because every line now starts with an escape sequence rather than with a space, a plus or a minus.

7.5 Verifying a Restored Backup Properly

Put 7.1 together with the rest and you get the check that is actually worth running after a restore or a migration. It has two halves, because no single command covers both.

First, contents:

$ diff -rq --no-dereference /var/www/live /mnt/restore/live

Then everything diff ignores, by turning the metadata into text and diffing that instead:

$ diff \
    <(cd /var/www/live   && find . -printf '%p %m %u:%g\n' | sort) \
    <(cd /mnt/restore/live && find . -printf '%p %m %u:%g\n' | sort)
3c3
< ./f.txt 644 www-data:www-data
---
> ./f.txt 777 www-data:www-data

The find -printf format string is doing the work: %p the path, %m the permission bits in octal, %u:%g the owner and group. Sorting both sides makes the comparison stable. The result is a one-line report of every file whose mode or ownership changed, which is precisely what the content comparison cannot see.

The same pair of commands answers a second question that comes up more often than anyone would like: has anything on this site been modified that should not have been? Download a clean copy of the same version, and compare it against the running site. Every file that differs is either your own customisation, or something you need to look at very carefully.

Generalise it once more and you have the most useful habit in this article. Capture the state as text before you change anything, capture it again afterwards, and diff the two. It costs two commands and it answers "what did that actually do?" precisely:

$ before=$(mktemp) after=$(mktemp)
$ trap 'rm -f "$before" "$after"' EXIT

$ dpkg-query -W | LC_ALL=C sort > "$before"
$ sudo apt upgrade
$ dpkg-query -W | LC_ALL=C sort > "$after"

$ diff -u --label before --label after "$before" "$after"

The trap line is what makes it safe to put in a script: the temporary files are removed even if it exits early. Anything that prints text works as a snapshot, and on Linux that is nearly everything:

find /etc -type f | LC_ALL=C sort        which configuration files exist
systemctl list-unit-files --state=enabled   which services will start
ss -tulpn                               which ports are listening
php -m | LC_ALL=C sort                  which PHP extensions are loaded
crontab -l ; ls /etc/cron.d             what is scheduled

Run one of those before a migration and again afterwards, and the differences between the two servers stop being a matter of memory.

7.6 Knowing Where diff Stops

Part of expertise is knowing when a tool is the wrong one.

The last row is underused. When you have two lists of names, comm -13 and comm -23 answer "what is only on this side?" more directly than reading a diff does.

9. Common Mistakes

9.1 Myth Versus Reality

9.2 Other Traps to Avoid

• Comparing unsorted output. diff <(ssh a 'dpkg -l') <(ssh b 'dpkg -l') without sort on both sides produces a diff of the ordering, not of the content.
• Reversing the argument order. diff new old is a valid command that produces a patch which undoes your work. The first file is always the "from".
• Forgetting -N when generating a tree patch. Without it, files that only exist on one side are mentioned as "Only in" and are not included, so the patch silently cannot create them.
• Applying a patch from the wrong directory. The -p level and your working directory are two halves of the same setting. Get one wrong and you get "can't find file to patch", or worse, you patch a file with the same name somewhere else.
• Using -w to make a difference go away. Whitespace is significant in Python, YAML, Makefiles and here-documents. -w is for investigating, not for concluding.
• Editing a patch file by hand. The line counts in the @@ headers must agree with the lines that follow, and nothing warns you when they do not.
• Trusting a diff of a generated file. Minified assets, compiled templates and cache files differ constantly for reasons nobody needs to see. Exclude them, or compare the sources they came from.
• Writing an exclusion as a path. -x 'logs/*' and -x 'site/cache' both match nothing at all, silently. The pattern is tested against each entry's name on its own.
• Comparing two servers without pinning the locale. If LANG differs between them, sort produces a different order on each side and the diff is entirely noise. LC_ALL=C sort on both sides.
• Leaving .orig files in a web root. helper.php.orig is not executed by PHP, which means the web server may serve it as plain text, including whatever is in it. Clean them up.