Requesting clarification on docs: filesystem watching behaviour when non "Top-level include patterns" are used.

I recently encountered some confusing behaviour with regards to “top-level include patterns” on an Android device. The docs appear to incorrectly describe filesystem watching behaviour when a non “top-level include pattern” is used.

Here is a shortened version of my ignore file. In summary, only certain folders were synchronized, with everything else ignored. All include patterns were top-level. Filesystem watching was initially disabled.


Following this, I decided to handle /DCIM/Camera in a separate partnership. My ignore list became this:

/DCIM/Camera    # exclude the Camera folder in DCIM
!/DCIM          # everything else in DCIM

No problems so far. Because this device is always plugged in and battery life is not a concern I decided to enable filesystem watching. Immediately syncthing popped up a “Filesystem Watcher Error”: permission denied traversing /storage/emulated/0/Android/obb

Here is what the docs say:

Top-level include patterns are described as not [causing syncthing to] “scan” [the entire directory tree]

Non top-level include patterns are described as [causing syncthing to] “traverse” and “watch” [the entire directory tree].

I run some tests.

  1. Filesystem watching is enabled.
  2. I use a non top-level include pattern. Hence, syncthing traversed the entire directory tree.
  3. Syncthing couldn’t enter certain folders while traversing, and watching failed to be enabled.
  4. We know that the entire directory tree was traversed because syncthing complains about a folder not explicitly listed in the ignore file.
  5. The error is one of filesystem watching.

Yet with the same setup, minus filesystem watching, syncthing did not complain. I made sure to restart after toggling so syncthing started from scratch each time.

The docs imply that the entire directory tree will be watched if non top-level patterns are included. This does not appear to be true. Instead, what seens to be happening is IF filesystem watching is enabled, then syncthing will traverse and watch the entire directory tree. If filesystem watching is not enabled, syncthing will still traverse the entire tree. But it will not watch the entire directory tree.

The evidence I submit is as follows, by:

  1. Using non top-level include patterns;
  2. having directories in the folder tree with restrictive permissions that would have normally cause syncthing to fail when attempting to watch them;
  3. disabling watching

syncthing will not output any “Filesystem Watcher Errors”. Hence, no watching was done.

I could be wrong in the following scenario: When watching is disabled, and syncthing still enables watching, but suppresses any errors about it.

If watching is disabled, it’s disabled. It won’t be enabled just because you have a certain type of ignore pattern.

If watching is not enabled, nothing will be watched, watching and scanning are different things. Watches trigger scans.

OK, I’m clear on that aspect. Could the docs be clarified? Right now they seem to imply that having !include patterns will cause syncthing to watch the entire directory tree.

Include patterns (that begin with !) cause Syncthing to traverse and watch the entire directory tree regardless of other ignore patterns.

Perhaps something like the below would be more accurate?

Include patterns (that begin with !) cause Syncthing to traverse the entire directory tree regardless of other ignore patterns. If the watcher is enabled, the entire directory tree will be watched as well.

Sure. PRs welcome. :slight_smile:

Just a side note, but ignore patterns do not support inline comments. If your patterns really look like above, then you are literally looking for a file called

/DCIM          # everything else in DCIM


1 Like

Thank you for your time in clarifying this, syncthing developers. I remember being confused at that section a few years ago. I submitted a PR, my second one in syncthing (both relating to phrasing in the documentation). I hope the modification can be of help.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.