How to debug rsync filter rules

A missing path in an rsync preview can come from a rule that matched the path itself or from an earlier rule that stopped traversal at one of its parent directories. FILTER debug messages name the sender-side match, so the first wrong decision can be corrected without running a live transfer.

Filter order matters because rsync stops at the first matching include or exclude rule for each name. An include for /documents/report.txt cannot rescue the file after * has already hidden /documents/, so every parent directory that must be scanned needs an earlier include.

Run the diagnostic against the same source, destination, and ordered rules planned for the transfer. Use --debug=FILTER when the source is local or on a remote push; use -M--debug=FILTER for a remote pull so the option reaches the remote sender.

1. Reproduce the wrong file list with filter debugging and a dry run.

   $ rsync -a --dry-run --debug=FILTER --include='/documents/report.txt' --exclude='*' source/ destination/
   [sender] hiding directory data because of pattern *
   [sender] hiding directory documents because of pattern *

   Use the exact paths and filter order from the planned transfer. For a remote pull, replace --debug=FILTER with -M--debug=FILTER because the remote source is the sender.

2. Follow the first unexpected match for the missing branch.

   The trace says * hid the documents directory. Rsync therefore did not enter that directory and never evaluated the later file include for documents/report.txt.

3. Insert an include for the parent directory before the file include and final catch-all rule, then repeat the debug dry run.

   $ rsync -a --dry-run --debug=FILTER --include='/documents/' --include='/documents/report.txt' --exclude='*' source/ destination/
   [sender] hiding directory data because of pattern *
   [sender] showing directory documents because of pattern /documents/
   [sender] hiding file documents/notes.txt because of pattern *
   [sender] showing file documents/report.txt because of pattern /documents/report.txt
   [sender] hiding file documents/report-hardlink.txt because of pattern *

   The leading slash anchors both include patterns at the transfer root. The trailing slash on /documents/ limits that rule to the directory.

4. Check that every unexpected hiding or showing line now names the intended rule.

   Keep rules from --filter, --include-from, and --exclude-from in their original relative order while diagnosing a real command because all of them join the same ordered filter list.

5. Remove filter debugging but keep the corrected rules and dry run for the final preview.

   $ rsync -av --dry-run --include='/documents/' --include='/documents/report.txt' --exclude='*' source/ destination/
   sending incremental file list
   ./
   documents/
   documents/report.txt
   
   sent 121 bytes  received 26 bytes  294.00 bytes/sec
   total size is 28  speedup is 0.19 (DRY RUN)

   If the live command includes --delete, do not remove --dry-run until this final list contains only the paths that should be transferred or deleted. Changing filters can also change which destination files are protected from deletion.

   Related: How to mirror a directory with rsync and delete extra files