How does `diff -r` compare directories recursively?

When you use the -r (recursive) flag with diff, it changes the command from a simple "surface-level" check to a deep, multi-level scan.

Here is exactly how it handles the process:

1. The Tree-Walking Process

Normal diff directory1 directory2 only looks at the files directly inside those folders.

With -r, diff performs a "Tree Walk":

It starts at the top level of both directories.
If it finds a sub-directory (a folder inside the folder), it doesn't just say "there's a folder here." It actually enters that sub-directory and starts comparing everything inside it as well.
It continues this process for every level of nesting it finds (folders inside folders inside folders).

2. The Logic it Follows

For every item it finds during the scan, it follows these rules:

If a file exists in A but not B: It reports Only in A: filename.
If a file exists in both A and B: It performs a standard text comparison. If they are different, it shows you the line-by-line changes (or just tells you they differ).
If a subdirectory exists in both: It enters both subdirectories and repeats these rules.

3. A Practical Example

Imagine this structure:

Folder A/           Folder B/
├── notes.txt       ├── notes.txt (modified)
└── Work/           └── Work/
    └── task.txt        └── todo.txt

Running diff -r FolderA FolderB would:

Compare notes.txt in both and show the line changes.
Enter the Work folder in both.
Report Only in FolderA/Work: task.txt.
Report Only in FolderB/Work: todo.txt.

Why is this useful?

The recursive flag is essential for comparing software projects or backups. It ensures that even if you have hundreds of sub-folders, you can be 100% sure that every single file in the entire hierarchy is identical.

Pro Tip: If you only want to know which files are different and don't want to see the specific line changes, you can add the -q (brief) flag:
diff -rq directory1 directory2