Understanding ignore pattern matching

[bigsur]

The Ignoring Files section of the documentation is well written and covers everything concisely, and the patterns are clearly explained, but I needed to study the documentation for quite a long time before I grasped the matching process and the resulting effects on each file or directory. The following understanding developed in my mind, and has made it much easier for me to craft a .stignore file. I’m posting for confirmation or correction of my understanding, and also to share with others who may find this helpful (assuming it’s correct).


How does Syncthing determine the disposition of an examined file or directory?

Each item (file or directory) examined** by Syncthing is compared to the .stignore pattern list, starting from the top of the pattern list and working down. The first pattern to match an item determines that item’s disposition (either ignored or included). Any remaining patterns become irrelevant to the disposition of that item. If no patterns match, the item receives an ‘included’ disposition.

**Not all files are examined by Syncthing. See step 2 below.


When examining files and directories, in what order does Syncthing move through the file structure?

1. Syncthing examines all the root files and directories and determines a disposition for each.

2. Syncthing descends one level into each directory and examines the files and directories at that level, determining a disposition for each. Syncthing does not descend into any directory matching an ignore pattern in any previous step. The entire file structure below an ignored directory automatically inherits the ‘ignored’ disposition of its parent and those files and directories are never examined by Syncthing.

3. Step 2 is repeated until the entire file structure under the root has received a disposition (either ignored or included).

[imsodin (Simon)]

Nice explanation. Unfortunately (well, not really ) point 2/** will change in v0.14.49: Syncthing will then only skip ignored directories, if there are no include rules. If there are any include rules, it will descend into all directories, also ignored ones, in order to find included items.

[bigsur]

Thanks Simon. Good to know about the coming changes. I’d like to write my ignore patterns so that their effect won’t change when that new version is released. Is the following an accurate understanding of matching in v0.14.49?

If include patterns are not present–>no change to the matching process

If include patterns are present–> For any directory matching an ignore pattern, the entire structure underneath it (all files and folders) receives a disposition of ‘ignored’ just as before. But Syncthing descends into the structure and compares every file and folder to a subset of the patterns in .stignore (subset = only the include patterns). If any item matches an include pattern, its disposition is changed to ‘include’. All other items remain ‘ignored’.

When a subdirectory and all its contents initially inherit an ‘ignored’ disposition from a parent directory, and then that subdirectory is subsequently changed to ‘included’ by an include rule during this new descend action, do all its contents automatically change to ‘included’ as well?

[bigsur]

Just checking back in on my questions about matching in v0.14.49. It looks like it’s due to be released next week.

I’m hoping to understand how the matching behavior works in v0.14.49 so I can preemptively make adjustments to my .stignore if necessary.

Thanks!

[AudriusButkevicius]

@bigsur

When a subdirectory and all its contents initially inherit an ‘ignored’ disposition from a parent directory, and then that subdirectory is subsequently changed to ‘included’ by an include rule during this new descend action, do all its contents automatically change to ‘included’ as well?

That’s the intention.