Implement watch exclusion lists

Allow exclusion of directories when watching recursively.

README.md

@@ -75,6 +75,24 @@ try await inotify.addWatchWithAutomaticSubtreeWatching(
 
 This is the most convenient option when you need full coverage of a growing directory tree.
 
+## Excluding Items
+
+You can tell the `Inotify` actor to ignore certain file or directory names. Excluded names are skipped during recursive directory resolution (so no watch is installed on them) and silently dropped from the event stream:
+
+```swift
+let inotify = try Inotify()
+
+// Ignore version-control and build directories
+await inotify.exclude(names: ".git", "node_modules", ".build")
+
+try await inotify.addWatchWithAutomaticSubtreeWatching(
+    forDirectory: "/home/user/project",
+    mask: [.create, .modify, .delete]
+)
+```
+
+Use `isExcluded(_:)` to check whether a name is currently on the exclusion list.
+
 ## Event Masks
 
 `InotifyEventMask` is an `OptionSet` that mirrors the native inotify flags. You can combine them freely.
@@ -113,7 +131,9 @@ try inotify.removeWatch(wd)
 
 ## Build Tool
 
-The package ships with a `task` executable (the `TaskCLI` target) that serves as the project's build tool. It spins up a Docker container running `swift:latest` on Linux and executes the full test suite inside it, so you can validate everything on the correct platform even when developing on macOS.
+The package ships with a `task` executable (the `TaskCLI` target) that serves as the project's build tool. It automates running tests and generating documentation inside Linux Docker containers, so you can validate everything on the correct platform even when developing on macOS.
+
+### Tests
 
 ```bash
 swift run task test

Sources/Inotify/Inotify.docc/Inotify.md

@@ -20,6 +20,8 @@ Beyond single-directory watches, the library provides two higher-level methods f
 - ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` installs watches on every existing subdirectory at setup time.
 - ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` does the same **and** automatically watches subdirectories that are created after setup.
 
+You can also exclude certain file or directory names so that they are skipped during directory resolution and silently dropped from the event stream. See ``Inotify/Inotify/exclude(names:)`` and <doc:WatchingDirectoryTrees> for details.
+
 All public types conform to `Sendable`, so they can be safely passed across concurrency boundaries.
 
 ## Topics
@@ -30,6 +32,10 @@ All public types conform to `Sendable`, so they can be safely passed across conc
 - ``InotifyEvent``
 - ``InotifyEventMask``
 
+### Articles
+
+- <doc:WatchingDirectoryTrees>
+
 ### Errors
 
 - ``InotifyError``

Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md

@@ -33,6 +33,22 @@ let descriptors = try await inotify.addWatchWithAutomaticSubtreeWatching(
 
 Internally this listens for `CREATE` events carrying the ``InotifyEventMask/isDir`` flag and installs a new watch with the same mask whenever a subdirectory appears.
 
+### Excluding Directories
+
+When watching large trees you often want to skip certain subdirectories entirely — version-control metadata, build artefacts, dependency caches, and so on. Call ``Inotify/Inotify/exclude(names:)`` **before** adding a recursive or automatic-subtree watch:
+
+```swift
+let inotify = try Inotify()
+await inotify.exclude(names: ".git", "node_modules", ".build")
+
+try await inotify.addWatchWithAutomaticSubtreeWatching(
+    forDirectory: "/home/user/project",
+    mask: .allEvents
+)
+```
+
+Excluded names are matched against the last path component of each directory during resolution and are also filtered from the event stream, so you never receive events for items whose name is on the exclusion list.
+
 ### Choosing the Right Method
 
 | Method | Covers existing subdirectories | Covers new subdirectories |