restic diff
restic diff allows you to compare the contents of two different snapshots. It provides a summary of changed files and directories, helping you understand how your data is evolving or why a specific backup grew in size.
diff is the tool for "Change Analysis." It answers: "What happened to my files between Tuesday and Wednesday?"
Basic Syntax
restic diff [snapshotID_1] [snapshotID_2] [flags]
Usage Patterns
# Compare two specific snapshots
restic diff d8f3e2a1 f9e2d1c0
# Compare the latest snapshot with the one before it (for same host/path)
restic diff latest~1 latest
Output Markers
Restic uses single-character markers to indicate the type of change:
| Marker | Description |
|---|---|
+ | Added: File or directory exists in the new snapshot but not the old. |
- | Removed: File or directory exists in the old snapshot but not the new. |
M | Modified: File content, permissions, or metadata changed. |
Key Flags
| Flag | Description |
|---|---|
--metadata | Only show metadata changes (permissions, owners, etc.) |
--json | Output the diff in JSON format for automated analysis |
Practical Examples
1. Investigating Storage Growth
If a daily backup suddenly added 5GB of data, use diff to see what large files were added.
restic diff d8f3e2a1 f9e2d1c0
2. Verifying a Migration
After moving files from one server to another and backing up, use diff to ensure the file tree is identical.
restic diff snapshot_server_a snapshot_server_b
3. Change Summary (The Stats)
At the bottom of every diff output, Restic provides a summary of total changes. This is often all you need.
# Scroll to the bottom of the output
restic diff d8f3e2a1 f9e2d1c0 | tail -n 5
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
| Comparing Unrelated Snapshots | A massive list of files where everything appears "Added" or "Deleted." | Ensure the snapshots have common paths or come from the same host. |
| Large Snapshots | Diffing two 10TB snapshots can be CPU and RAM intensive. | Limit the search scope if possible or wait for the analysis to finish. |
| Forgetting Permissions | M (Modified) might appear even if content is the same (due to a chmod or chown). | Use --metadata to focus only on those types of changes. |
Examples with Output
Examples with Output
1. Simple Comparison (Previous vs Current)
Command:
restic diff 58f2d1c9 2a3b4c5d
Output:
repository a7b2c9d opened successfully, password is correct
comparing snapshot 58f2d1c9 to 2a3b4c5d:
+ /var/www/html/new-page.php
M /var/www/html/index.php
- /var/www/html/old-logo.png
Files: 1 new, 1 removed, 1 changed
Dirs: 0 new, 0 removed
Others: 0 new, 0 removed
Data Blobs: 4 new, 2 removed
Tree Blobs: 2 new, 1 removed
Added: 45.210 KiB
Removed: 12.500 KiB
2. Compare Metadata Only
Useful when file permissions changed but content is identical. Command:
restic diff --metadata 58f2d1c9 2a3b4c5d
Output:
repository a7b2c9d opened successfully, password is correct
comparing snapshot 58f2d1c9 to 2a3b4c5d:
M /etc/shadow
Files: 0 new, 0 removed, 1 changed
Dirs: 0 new, 0 removed
Others: 0 new, 0 removed
Data Blobs: 0 new, 0 removed
Tree Blobs: 1 new, 1 removed
Added: 0 B
Removed: 0 B
3. Comparing Two Hosts (Migration Check)
Command:
restic diff latest --host server-a latest --host server-b
Output:
repository a7b2c9d opened successfully, password is correct
comparing snapshot 58f2d1c9 to 9b8a7c6d:
+ /home/user/unique-to-server-b.txt
- /home/user/unique-to-server-a.txt
Files: 1 new, 1 removed, 0 changed
Dirs: 0 new, 0 removed
Added: 1.024 KiB
Removed: 1.024 KiB
4. JSON Output
Command:
restic diff 58f2d1c9 2a3b4c5d --json
Output:
{"path":"/var/www/html/new-page.php","type":"file","mode":33188,"mtime":...,"change":"added"}
{"path":"/var/www/html/old-logo.png","type":"file","mode":33188,"mtime":...,"change":"removed"}
5. Large Change Summary
Command:
restic diff 58f2d1c9 2a3b4c5d
Output:
repository a7b2c9d opened successfully, password is correct
comparing snapshot 58f2d1c9 to 2a3b4c5d:
[... 5000 lines omitted ...]
Files: 2500 new, 1200 removed, 500 changed
Dirs: 150 new, 50 removed
Added: 5.400 GiB
Removed: 1.200 GiB
What's Next?
If you've identified a deleted file you need back, retrieve it with restic restore.