Pin the docs workflow to Swift 6.3

Without a version the setup action installs the latest toolchain.
Swift 6.4.0 shipped on 2026-09-15 and the swiftly build cached on the
runner cannot install it, so the docs job started failing.

.github/workflows/docs.yml

@@ -26,6 +26,7 @@ jobs:
     - name: Set up Swift
       uses: swift-actions/setup-swift@v3
       with:
+        swift-version: "6.3"
         skip-verify-signature: true
     - name: Generate Docs
       run: |

Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "17ce26ba5c862ca674cd3ceeb43a9fe8a5c5251c5561de65e632a06d79916342",
+  "originHash" : "d30dadbb08ce17a04cba957d25e81d1d76b8dc0a7bdc84a591c7af3b8eb74b85",
   "pins" : [
     {
       "identity" : "noora",
@@ -78,8 +78,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/swiftlang/swift-subprocess.git",
       "state" : {
-        "revision" : "ba5888ad7758cbcbe7abebac37860b1652af2d9c",
-        "version" : "0.3.0"
+        "revision" : "b3937ab85dd32f6e9435914599c1519074769c1a",
+        "version" : "1.0.0"
       }
     },
     {

Package.swift

@@ -8,22 +8,28 @@ let package = Package(
 		.library(
 			name: "Inotify",
 			targets: ["Inotify"]
-		)
+		),
+		.library(
+			name: "InotifyMask",
+			targets: ["InotifyMask"]
+		),
 	],
 	dependencies: [
 		.package(url: "https://github.com/apple/swift-argument-parser", from: "1.7.1"),
 		.package(url: "https://github.com/apple/swift-log", from: "1.10.1"),
 		.package(url: "https://github.com/apple/swift-nio", from: "2.95.0"),
 		.package(url: "https://github.com/apple/swift-system", from: "1.6.4"),
-		.package(url: "https://github.com/swiftlang/swift-subprocess.git", from: "0.3.0"),
+		.package(url: "https://github.com/swiftlang/swift-subprocess.git", "0.3.0"..<"2.0.0"),
 		.package(url: "https://github.com/tuist/Noora", from: "0.55.1")
 	],
 	targets: [
 		.systemLibrary(name: "CInotify"),
+		.target(name: "InotifyMask"),
 		.target(
 			name: "Inotify",
 			dependencies: [
 				"CInotify",
+				"InotifyMask",
 				.product(name: "Logging", package: "swift-log"),
 				.product(name: "_NIOFileSystem", package: "swift-nio"),
 				.product(name: "SystemPackage", package: "swift-system")

README.md

@@ -64,7 +64,7 @@ Subdirectories created after the call are **not** watched.
 
 ### Automatic Subtree Watching
 
-`addWatchWithAutomaticSubtreeWatching` does everything `addRecursiveWatch` does, and additionally listens for `CREATE` events with the `isDir` flag. Whenever a new subdirectory appears, a watch is installed on it automatically:
+`addWatchWithAutomaticSubtreeWatching` does everything `addRecursiveWatch` does, and additionally listens for `CREATE` and `MOVED_TO` events with the `isDir` flag. Whenever a subdirectory appears, whether created or moved in, a watch is installed on it and on its subdirectories automatically:
 
 ```swift
 try await inotify.addWatchWithAutomaticSubtreeWatching(
@@ -75,9 +75,13 @@ try await inotify.addWatchWithAutomaticSubtreeWatching(
 
 This is the most convenient option when you need full coverage of a growing directory tree.
 
+Items that already exist inside a directory that appears this way never produce kernel events. The library reports them as if they had just appeared, using the same kind of event (`CREATE` or `MOVED_TO`), with `synthesized` set to `true`. A synthesized event may duplicate a kernel event for the same item, so consumers that act on events should tolerate seeing an item twice.
+
+When a watched directory is moved out of the tree, the watches on it and on its subdirectories are removed, so no events are reported under the stale path.
+
 ## 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:
+You can tell the `Inotify` actor to ignore certain file or directory names, either exactly or by a shell pattern. Excluded items are skipped during recursive directory resolution (so no watch is installed on them), never get a watch when they appear later, and are silently dropped from the event stream:
 
 ```swift
 let inotify = try Inotify()
@@ -85,18 +89,23 @@ let inotify = try Inotify()
 // Ignore version-control and build directories
 await inotify.exclude(names: ".git", "node_modules", ".build")
 
+// Ignore every hidden item and every metadata directory of a NAS
+await inotify.exclude(patterns: ".*", "@eaDir")
+
 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.
+A pattern is matched against an item's own name, not its path, the way the shell matches file names: `*` and `?` stand for any characters and `[…]` for a set of characters. Use `isExcluded(_:)` to check whether a name is currently excluded.
 
 ## Event Masks
 
 `InotifyEventMask` is an `OptionSet` that mirrors the native inotify flags. You can combine them freely.
 
+The mask lives in the separate `InotifyMask` product, which has no Linux dependency. Depend on it alone where code only stores or compares masks and must build or be tested on other platforms; `Inotify` re-exports it.
+
 | Mask | Description |
 |------|-------------|
 | `.access` | File was read |
@@ -118,6 +127,8 @@ Watch flags: `.dontFollow`, `.onlyDir`, `.oneShot`.
 
 Kernel-only flags returned in events: `.isDir`, `.ignored`, `.queueOverflow`, `.unmount`.
 
+When the kernel queue overflows, events are lost and a single event with `.queueOverflow` is delivered instead. It has no path and a watch descriptor of `-1`; rescan the watched directories if you must not miss changes.
+
 ## Removing a Watch
 
 Every `addWatch` variant returns one or more watch descriptors that you can use to remove the watch later:

Sources/Inotify/DirectoryResolver.swift

@@ -4,33 +4,43 @@ public struct DirectoryResolver {
 	static let fileManager = FileSystem.shared
 
 	public static func resolve(_ paths: String..., excluding itemNames: Set<String> = []) async throws -> [FilePath] {
-		try await Self.resolve(paths, excluding: itemNames)
+		try await Self.resolve(paths, excluding: ExclusionList(names: itemNames))
 	}
 
-	static func resolve(_ paths: [String], excluding itemNames: Set<String> = []) async throws -> [FilePath] {
+	static func resolve(_ paths: [String], excluding exclusions: ExclusionList = ExclusionList()) async throws -> [FilePath] {
 		var resolved: [FilePath] = []
 
 		for path in paths {
 			let path = FilePath(path)
 			resolved.append(path)
-			try await withSubdirectories(at: path, recursive: true) { subdirectoryPath in
-				guard let basename = subdirectoryPath.lastComponent?.description else { return }
-				guard !itemNames.contains(basename) else { return }
-				resolved.append(subdirectoryPath)
-			}
+			try await withSubdirectories(at: path, excluding: exclusions) { resolved.append($0) }
 		}
 
 		return resolved
 	}
 
-	private static func withSubdirectories(at path: FilePath, recursive: Bool = false, body: (FilePath) async throws -> Void) async throws {
+	/// The direct children of `directory`, without the excluded items.
+	static func entries(of directory: FilePath, excluding exclusions: ExclusionList = ExclusionList()) async throws -> [(name: String, isDirectory: Bool)] {
+		let directoryHandle = try await fileManager.openDirectory(atPath: directory)
+		var entries: [(name: String, isDirectory: Bool)] = []
+		for try await childContent in directoryHandle.listContents() {
+			guard let name = childContent.path.lastComponent?.string else { continue }
+			guard !exclusions.excludes(name) else { continue }
+			entries.append((name: name, isDirectory: childContent.type == .directory))
+		}
+		try await directoryHandle.close()
+		return entries
+	}
+
+	/// Calls `body` for every subdirectory below `path`, depth first. Excluded
+	/// directories are neither reported nor descended into.
+	private static func withSubdirectories(at path: FilePath, excluding exclusions: ExclusionList, body: (FilePath) async throws -> Void) async throws {
 		let directoryHandle = try await fileManager.openDirectory(atPath: path)
 		for try await childContent in directoryHandle.listContents() {
 			guard childContent.type == .directory else { continue }
+			guard let name = childContent.path.lastComponent?.string, !exclusions.excludes(name) else { continue }
 			try await body(childContent.path)
-			if recursive {
-				try await withSubdirectories(at: childContent.path, recursive: recursive, body: body)
-			}
+			try await withSubdirectories(at: childContent.path, excluding: exclusions, body: body)
 		}
 		try await directoryHandle.close()
 	}

Sources/Inotify/ExclusionList.swift

@@ -0,0 +1,33 @@
+#if canImport(Musl)
+import Musl
+#else
+import Glibc
+#endif
+
+/// The item names an ``Inotify`` instance skips: exact names and shell
+/// patterns, both matched against an item's own name.
+struct ExclusionList: Sendable {
+	private var names: Set<String> = []
+	private var patterns: [String] = []
+
+	init(names: Set<String> = [], patterns: [String] = []) {
+		self.names = names
+		self.patterns = patterns
+	}
+
+	mutating func add(name: String) {
+		self.names.insert(name)
+	}
+
+	mutating func add(pattern: String) {
+		guard !self.patterns.contains(pattern) else { return }
+		self.patterns.append(pattern)
+	}
+
+	/// Patterns are matched as the shell matches file names: `*` and `?`
+	/// stand for any characters, `[…]` for a set, and a leading dot needs
+	/// no special treatment.
+	func excludes(_ name: String) -> Bool {
+		self.names.contains(name) || self.patterns.contains { fnmatch($0, name, 0) == 0 }
+	}
+}

Sources/Inotify/Exports.swift

@@ -0,0 +1,3 @@
+// The mask lives in its own module so that it is usable off Linux; users
+// of `Inotify` keep seeing it as before.
+@_exported import InotifyMask

Sources/Inotify/Inotify.docc/Inotify.md

@@ -20,7 +20,7 @@ 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.
+You can also exclude certain file or directory names, exactly or by shell pattern, so that they are skipped during directory resolution and silently dropped from the event stream. See ``Inotify/Inotify/exclude(names:)``, ``Inotify/Inotify/exclude(patterns:)`` and <doc:WatchingDirectoryTrees> for details.
 
 All public types conform to `Sendable`, so they can be safely passed across concurrency boundaries.
 

Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md

@@ -31,15 +31,18 @@ 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.
+Internally this listens for `CREATE` and `MOVED_TO` events carrying the ``InotifyEventMask/isDir`` flag and installs new watches with the same mask on the subdirectory and its subtree whenever one appears. Items that already exist inside such a subdirectory are reported with ``InotifyEvent/synthesized`` set to `true`, since the kernel never produces events for them; a synthesized event may duplicate a kernel event for the same item.
+
+When a directory is moved out of the watched tree, the watches on it and on its subdirectories are removed, so no events are reported under the stale path.
 
 ### 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:
+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:)`` or ``Inotify/Inotify/exclude(patterns:)`` **before** adding a recursive or automatic-subtree watch:
 
 ```swift
 let inotify = try Inotify()
 await inotify.exclude(names: ".git", "node_modules", ".build")
+await inotify.exclude(patterns: ".*", "*.tmp")
 
 try await inotify.addWatchWithAutomaticSubtreeWatching(
     forDirectory: "/home/user/project",
@@ -47,7 +50,7 @@ try await inotify.addWatchWithAutomaticSubtreeWatching(
 )
 ```
 
-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.
+Excluded names and patterns are matched against the last path component of each directory during resolution, against a directory that appears later before a watch is extended to it, and against every event, so you never receive events for excluded items. A pattern is matched the way the shell matches file names: `*` and `?` stand for any characters and `[…]` for a set of characters; a leading dot needs no special treatment.
 
 ### Choosing the Right Method
 

Sources/Inotify/Inotify.swift

@@ -1,30 +1,46 @@
 import Dispatch
 import CInotify
+import SystemPackage
 
 public actor Inotify {
 	private let fd: CInt
-	private var excludedItemNames: Set<String> = []
+	private var exclusions = ExclusionList()
 	private var watches = InotifyWatchManager()
-	private var eventReader: any DispatchSourceRead
-	private var eventStream: AsyncStream<RawInotifyEvent>
-	public var events: AsyncCompactMapSequence<AsyncStream<RawInotifyEvent>, InotifyEvent> {
+	private nonisolated(unsafe) let eventReader: any DispatchSourceRead
+	private nonisolated let eventStream: AsyncStream<RawInotifyEvent>
+	private nonisolated let continuation: AsyncStream<RawInotifyEvent>.Continuation
+	public nonisolated var events: AsyncCompactMapSequence<AsyncStream<RawInotifyEvent>, InotifyEvent> {
 		self.eventStream.compactMap(self.transform(_:))
 	}
 
-	public init() throws {
+	/// Creates an inotify instance.
+	///
+	/// Events are read from the kernel as soon as they arrive and buffered
+	/// until they are consumed from ``events``.
+	///
+	/// - Parameter bufferingPolicy: How events are kept while no consumer is
+	///   reading ``events``. The default `.unbounded` keeps every event, so a
+	///   burst of changes is never lost; a bounded policy trades memory for
+	///   dropped events.
+	public init(bufferingPolicy: AsyncStream<RawInotifyEvent>.Continuation.BufferingPolicy = .unbounded) throws {
 		self.fd = inotify_init1(CInt(IN_NONBLOCK | IN_CLOEXEC))
 		guard self.fd >= 0 else {
 			throw InotifyError.initFailed(errno: cinotify_get_errno())
 		}
-		(self.eventReader, self.eventStream) = Self.createEventReader(forFileDescriptor: fd)
+		(self.eventReader, self.eventStream, self.continuation) = Self.createEventReader(
+			forFileDescriptor: fd,
+			bufferingPolicy: bufferingPolicy
+		)
 	}
 
+	/// Whether an item with this name is skipped, by an excluded name or
+	/// an excluded pattern.
 	public func isExcluded(_ name: String) -> Bool {
-		self.excludedItemNames.contains(name)
+		self.exclusions.excludes(name)
 	}
 
 	public func exclude(name: String) {
-		self.excludedItemNames.insert(name)
+		self.exclusions.add(name: name)
 	}
 
 	public func exclude(names: String...) {
@@ -33,7 +49,28 @@ public actor Inotify {
 
 	public func exclude(names: [String]) {
 		for name in names {
-			self.excludedItemNames.insert(name)
+			self.exclusions.add(name: name)
+		}
+	}
+
+	/// Excludes every item whose name matches a shell pattern such as
+	/// `*.tmp` or `@*`, with the same effect as an excluded name.
+	///
+	/// The pattern is matched against the item's own name, not its path,
+	/// as the shell matches file names: `*` and `?` stand for any
+	/// characters and `[…]` for a set of characters. A leading dot needs
+	/// no special treatment, so `.*` excludes hidden items.
+	public func exclude(pattern: String) {
+		self.exclusions.add(pattern: pattern)
+	}
+
+	public func exclude(patterns: String...) {
+		self.exclude(patterns: patterns)
+	}
+
+	public func exclude(patterns: [String]) {
+		for pattern in patterns {
+			self.exclusions.add(pattern: pattern)
 		}
 	}
 
@@ -49,7 +86,7 @@ public actor Inotify {
 
 	@discardableResult
 	public func addRecursiveWatch(forDirectory path: String, mask: InotifyEventMask) async throws -> [CInt] {
-		let directoryPaths = try await DirectoryResolver.resolve(path, excluding: self.excludedItemNames)
+		let directoryPaths = try await DirectoryResolver.resolve([path], excluding: self.exclusions)
 		var result: [CInt] = []
 		for path in directoryPaths {
 			let wd = try self.addWatch(path: path.string, mask: mask)
@@ -73,32 +110,92 @@ public actor Inotify {
 	}
 
 	deinit {
-		cinotify_deinit(self.fd)
+		// The file descriptor is closed by the reader's cancel handler once
+		// libdispatch has unregistered it. Closing it here would leave a
+		// registration behind that a later instance reusing the descriptor
+		// number could inherit, silently losing its events.
+		self.eventReader.cancel()
 	}
 
 	private func transform(_ rawEvent: RawInotifyEvent) async -> InotifyEvent? {
+		if rawEvent.mask.contains(.queueOverflow) {
+			return InotifyEvent(from: rawEvent, inDirectory: "")
+		}
 		guard let path = self.watches.path(forId: rawEvent.watchDescriptor) else { return nil }
-		guard !self.excludedItemNames.contains(rawEvent.name) else { return nil }
+		guard !self.exclusions.excludes(rawEvent.name) else { return nil }
 		let event = InotifyEvent.init(from: rawEvent, inDirectory: path)
+		self.forgetWatchInCaseTheKernelRemovedIt(event)
+		self.removeWatchesInCaseADirectoryLeftTheTree(event)
 		await self.addWatchInCaseOfAutomaticSubtreeWatching(event)
-		return InotifyEvent.init(from: rawEvent, inDirectory: path)
+		return event
+	}
+
+	/// The kernel reports `IN_IGNORED` once a watch is gone, whether it was
+	/// removed explicitly or because its item was deleted or unmounted.
+	/// Forgetting it keeps a reused descriptor number from mapping to a
+	/// stale path.
+	private func forgetWatchInCaseTheKernelRemovedIt(_ event: InotifyEvent) {
+		guard event.mask.contains(.ignored) else { return }
+		self.watches.remove(forId: event.watchDescriptor)
+	}
+
+	/// A directory moved out of a watched tree keeps its kernel watches,
+	/// which would then report events under the old path. Those watches
+	/// are removed instead.
+	private func removeWatchesInCaseADirectoryLeftTheTree(_ event: InotifyEvent) {
+		guard event.mask.contains(.movedFrom), event.mask.contains(.isDir) else { return }
+		for wd in self.watches.descriptors(under: event.path.string) {
+			inotify_rm_watch(self.fd, wd)
+			self.watches.remove(forId: wd)
+		}
 	}
 
 	private func addWatchInCaseOfAutomaticSubtreeWatching(_ event: InotifyEvent) async {
-		guard watches.isAutomaticSubtreeWatching(event.watchDescriptor),
-			  event.mask.contains(.create),
-			  event.mask.contains(.isDir) else {
+		guard !event.synthesized,
+			  watches.isAutomaticSubtreeWatching(event.watchDescriptor),
+			  event.mask.contains(.isDir),
+			  let kind = Self.subtreeTrigger(in: event.mask) else {
 			return
 		}
 
 		guard let mask = self.watches.mask(forId: event.watchDescriptor) else { return }
-		let _ = try? await self.addWatchWithAutomaticSubtreeWatching(forDirectory: event.path.string, mask: mask)
+		guard let wds = try? await self.addWatchWithAutomaticSubtreeWatching(forDirectory: event.path.string, mask: mask) else { return }
+		await self.synthesizeEvents(forContentOfWatches: wds, kind: kind, cookie: event.cookie)
 	}
 
-	private static func createEventReader(forFileDescriptor fd: CInt) -> (any DispatchSourceRead, AsyncStream<RawInotifyEvent>) {
+	private static func subtreeTrigger(in mask: InotifyEventMask) -> InotifyEventMask? {
+		if mask.contains(.create) { return .create }
+		if mask.contains(.movedTo) { return .movedTo }
+		return nil
+	}
+
+	/// Items that already exist when a directory becomes watched never
+	/// produce kernel events, so they are reported as if they had just
+	/// appeared, marked as synthesized.
+	private func synthesizeEvents(forContentOfWatches wds: [CInt], kind: InotifyEventMask, cookie: UInt32) async {
+		for wd in wds {
+			guard let directory = self.watches.path(forId: wd) else { continue }
+			guard let entries = try? await DirectoryResolver.entries(of: FilePath(directory), excluding: self.exclusions) else { continue }
+			for entry in entries {
+				let mask: InotifyEventMask = entry.isDirectory ? [kind, .isDir] : kind
+				self.continuation.yield(RawInotifyEvent(
+					watchDescriptor: wd,
+					mask: mask,
+					cookie: cookie,
+					name: entry.name,
+					synthesized: true
+				))
+			}
+		}
+	}
+
+	private static func createEventReader(
+		forFileDescriptor fd: CInt,
+		bufferingPolicy: AsyncStream<RawInotifyEvent>.Continuation.BufferingPolicy
+	) -> (any DispatchSourceRead, AsyncStream<RawInotifyEvent>, AsyncStream<RawInotifyEvent>.Continuation) {
 		let (stream, continuation) = AsyncStream<RawInotifyEvent>.makeStream(
 			of: RawInotifyEvent.self,
-			bufferingPolicy: .bufferingNewest(512)
+			bufferingPolicy: bufferingPolicy
 		)
 
 		let reader = DispatchSource.makeReadSource(
@@ -112,10 +209,11 @@ public actor Inotify {
 			}
 		}
 		reader.setCancelHandler {
+			cinotify_deinit(fd)
 			continuation.finish()
 		}
 		reader.activate()
 
-		return (reader, stream)
+		return (reader, stream, continuation)
 	}
 }

Sources/Inotify/InotifyEvent.swift

@@ -1,10 +1,20 @@
 import SystemPackage
 
+/// A filesystem event delivered by an ``Inotify`` instance.
+///
+/// When the kernel's event queue overflows, it drops events and reports a
+/// single event whose ``mask`` contains ``InotifyEventMask/queueOverflow``.
+/// Such an event belongs to no watch: its ``watchDescriptor`` is `-1` and
+/// its ``path`` is empty. Consumers that must not miss changes should
+/// rescan the watched trees when they receive one.
 public struct InotifyEvent: Sendable, Hashable, CustomStringConvertible {
 	public let watchDescriptor: Int32
 	public let mask: InotifyEventMask
 	public let cookie: UInt32
 	public let path: FilePath
+	/// Whether the event was produced by the library for an item that already
+	/// existed when its directory became watched, rather than by the kernel.
+	public let synthesized: Bool
 
 	public var description: String {
 		var parts = ["InotifyEvent(wd: \(watchDescriptor), mask: \(mask), path: \"\(path)\""]
@@ -20,7 +30,8 @@ extension InotifyEvent {
 			watchDescriptor: rawEvent.watchDescriptor,
 			mask: rawEvent.mask,
 			cookie: rawEvent.cookie,
-			path: dirPath.appending(rawEvent.name)
+			path: dirPath.appending(rawEvent.name),
+			synthesized: rawEvent.synthesized
 		)
 	}
 }

Sources/Inotify/InotifyEventMask.swift

@@ -1,47 +0,0 @@
-import CInotify
-
-public struct InotifyEventMask: OptionSet, Sendable, Hashable {
-	public let rawValue: CUnsignedInt
-
-	public init(rawValue: UInt32) {
-		self.rawValue = rawValue
-	}
-
-	// MARK: - Watchable Events
-
-	public static let access        = InotifyEventMask(rawValue: CUnsignedInt(IN_ACCESS))
-	public static let attrib        = InotifyEventMask(rawValue: CUnsignedInt(IN_ATTRIB))
-	public static let closeWrite    = InotifyEventMask(rawValue: CUnsignedInt(IN_CLOSE_WRITE))
-	public static let closeNoWrite  = InotifyEventMask(rawValue: CUnsignedInt(IN_CLOSE_NOWRITE))
-	public static let create        = InotifyEventMask(rawValue: CUnsignedInt(IN_CREATE))
-	public static let delete        = InotifyEventMask(rawValue: CUnsignedInt(IN_DELETE))
-	public static let deleteSelf    = InotifyEventMask(rawValue: CUnsignedInt(IN_DELETE_SELF))
-	public static let modify        = InotifyEventMask(rawValue: CUnsignedInt(IN_MODIFY))
-	public static let moveSelf      = InotifyEventMask(rawValue: CUnsignedInt(IN_MOVE_SELF))
-	public static let movedFrom     = InotifyEventMask(rawValue: CUnsignedInt(IN_MOVED_FROM))
-	public static let movedTo       = InotifyEventMask(rawValue: CUnsignedInt(IN_MOVED_TO))
-	public static let open          = InotifyEventMask(rawValue: CUnsignedInt(IN_OPEN))
-
-	// MARK: - Combinations
-
-	public static let move: InotifyEventMask = [.movedFrom, .movedTo]
-	public static let close: InotifyEventMask = [.closeWrite, .closeNoWrite]
-	public static let allEvents: InotifyEventMask = [
-		.access, .attrib, .closeWrite, .closeNoWrite,
-		.create, .delete, .deleteSelf, .modify,
-		.moveSelf, .movedFrom, .movedTo, .open
-	]
-
-	// MARK: - Watch Flags
-
-	public static let dontFollow    = InotifyEventMask(rawValue: CUnsignedInt(IN_DONT_FOLLOW))
-	public static let onlyDir       = InotifyEventMask(rawValue: CUnsignedInt(IN_ONLYDIR))
-	public static let oneShot       = InotifyEventMask(rawValue: CUnsignedInt(IN_ONESHOT))
-
-	// MARK: - Kernel-Only Flags
-
-	public static let isDir         = InotifyEventMask(rawValue: CUnsignedInt(IN_ISDIR))
-	public static let ignored       = InotifyEventMask(rawValue: CUnsignedInt(IN_IGNORED))
-	public static let queueOverflow = InotifyEventMask(rawValue: CUnsignedInt(IN_Q_OVERFLOW))
-	public static let unmount       = InotifyEventMask(rawValue: CUnsignedInt(IN_UNMOUNT))
-}

Sources/Inotify/InotifyEventParser.swift

@@ -31,7 +31,8 @@ struct InotifyEventParser {
 				watchDescriptor: rawEvent.wd,
 				mask: InotifyEventMask(rawValue: rawEvent.mask),
 				cookie: rawEvent.cookie,
-				name: Self.extractName(from: eventPointer, nameLength: rawEvent.len)
+				name: Self.extractName(from: eventPointer, nameLength: rawEvent.len),
+				synthesized: false
 			))
 
 			offset += Self.eventSize(nameLength: rawEvent.len)

Sources/Inotify/InotifyWatchManager.swift

@@ -36,6 +36,14 @@ struct InotifyWatchManager {
 		return self.watchPaths[watchDescriptor]
 	}
 
+	/// The descriptors of the watch on `path` itself and of every watch below it.
+	func descriptors(under path: String) -> [CInt] {
+		let prefix = path.hasSuffix("/") ? path : path + "/"
+		return self.watchPaths
+			.filter { $0.value == path || $0.value.hasPrefix(prefix) }
+			.map(\.key)
+	}
+
 	func mask(forId watchDescriptor: CInt) -> InotifyEventMask? {
 		return self.watchMasks[watchDescriptor]
 	}

Sources/Inotify/RawInotifyEvent.swift

@@ -3,6 +3,9 @@ public struct RawInotifyEvent: Sendable, Hashable, CustomStringConvertible {
 	public let mask: InotifyEventMask
 	public let cookie: UInt32
 	public let name: String
+	/// Whether the event was produced by the library for an item that already
+	/// existed when its directory became watched, rather than by the kernel.
+	public let synthesized: Bool
 
 	public var description: String {
 		var parts = ["RawInotifyEvent(wd: \(watchDescriptor), mask: \(mask), name: \"\(name)\""]

Sources/InotifyMask/InotifyEventMask.swift

@@ -0,0 +1,51 @@
+/// The events and flags of an inotify watch or event, as bits.
+///
+/// The values are the constants of the Linux `<sys/inotify.h>` header,
+/// which are part of the kernel's stable interface. Spelling them out here
+/// keeps this module free of the C header, so it builds on every platform
+/// and lets code that only stores or compares masks be tested off Linux.
+public struct InotifyEventMask: OptionSet, Sendable, Hashable {
+	public let rawValue: UInt32
+
+	public init(rawValue: UInt32) {
+		self.rawValue = rawValue
+	}
+
+	// MARK: - Watchable Events
+
+	public static let access = InotifyEventMask(rawValue: 0x0000_0001)
+	public static let modify = InotifyEventMask(rawValue: 0x0000_0002)
+	public static let attrib = InotifyEventMask(rawValue: 0x0000_0004)
+	public static let closeWrite = InotifyEventMask(rawValue: 0x0000_0008)
+	public static let closeNoWrite = InotifyEventMask(rawValue: 0x0000_0010)
+	public static let open = InotifyEventMask(rawValue: 0x0000_0020)
+	public static let movedFrom = InotifyEventMask(rawValue: 0x0000_0040)
+	public static let movedTo = InotifyEventMask(rawValue: 0x0000_0080)
+	public static let create = InotifyEventMask(rawValue: 0x0000_0100)
+	public static let delete = InotifyEventMask(rawValue: 0x0000_0200)
+	public static let deleteSelf = InotifyEventMask(rawValue: 0x0000_0400)
+	public static let moveSelf = InotifyEventMask(rawValue: 0x0000_0800)
+
+	// MARK: - Combinations
+
+	public static let move: InotifyEventMask = [.movedFrom, .movedTo]
+	public static let close: InotifyEventMask = [.closeWrite, .closeNoWrite]
+	public static let allEvents: InotifyEventMask = [
+		.access, .attrib, .closeWrite, .closeNoWrite,
+		.create, .delete, .deleteSelf, .modify,
+		.moveSelf, .movedFrom, .movedTo, .open,
+	]
+
+	// MARK: - Watch Flags
+
+	public static let onlyDir = InotifyEventMask(rawValue: 0x0100_0000)
+	public static let dontFollow = InotifyEventMask(rawValue: 0x0200_0000)
+	public static let oneShot = InotifyEventMask(rawValue: 0x8000_0000)
+
+	// MARK: - Kernel-Only Flags
+
+	public static let unmount = InotifyEventMask(rawValue: 0x0000_2000)
+	public static let queueOverflow = InotifyEventMask(rawValue: 0x0000_4000)
+	public static let ignored = InotifyEventMask(rawValue: 0x0000_8000)
+	public static let isDir = InotifyEventMask(rawValue: 0x4000_0000)
+}

Sources/TaskCLI/GenerateDocumentation Command.swift

@@ -53,8 +53,8 @@ struct GenerateDocumentationCommand: AsyncParsableCommand {
 				"swift:latest",
 				"/bin/bash", "-c", script
 			],
-			output: .standardOutput,
-			error: .standardError
+			output: .currentStandardOutput,
+			error: .currentStandardError
 		)
 		if !dockerRunResult.terminationStatus.isSuccess {
 			noora.error("Documentation generation failed.")
@@ -112,7 +112,7 @@ struct GenerateDocumentationCommand: AsyncParsableCommand {
 			.name("swift"),
 			arguments: ["package", "describe", "--type", "json"],
 			output: .data(limit: 10_000),
-			error: .standardError
+			error: .currentStandardError
 		)
 
 		struct PackageDescription: Codable {
@@ -178,8 +178,8 @@ struct GenerateDocumentationCommand: AsyncParsableCommand {
 				"package", "--package-path", directory.path(percentEncoded: false),
 				"add-dependency", "--from", Self.doccPluginMinVersion, Self.doccPluginURL
 			],
-			output: .standardOutput,
-			error: .standardError
+			output: .currentStandardOutput,
+			error: .currentStandardError
 		)
 		if !swiftRunResult.terminationStatus.isSuccess {
 			throw GenerateDocumentationError.dependencyInjectionFailed

Sources/TaskCLI/Test Command.swift

@@ -30,10 +30,10 @@ struct TestCommand: AsyncParsableCommand {
 				"--security-opt", "systempaths=unconfined",
 				"--platform", Docker.getLinuxPlatformStringWithHostArchitecture(),
 				"-w", "/code", "swift:latest",
-				"/bin/bash", "-c", "swift test --skip InotifyLimitTests; swift test --skip-build --filter InotifyLimitTests"
+				"/bin/bash", "-c", "swift test --skip InotifyLimitTests && swift test --skip-build --filter InotifyLimitTests"
 			],
-			output: .standardOutput,
-			error: .standardError
+			output: .currentStandardOutput,
+			error: .currentStandardError
 		)
 		if dockerRunResult.terminationStatus.isSuccess {
 			noora.success("All tests completed successfully.")

Tests/InotifyIntegrationTests/BufferingTests.swift

@@ -0,0 +1,32 @@
+import Foundation
+import Testing
+@testable import Inotify
+
+@Suite("Event Buffering")
+struct BufferingTests {
+	@Test func deliversEveryEventOfABurstToALateConsumer() async throws {
+		try await withTempDir { dir in
+			let fileCount = 1000
+			let watcher = try Inotify()
+			try await watcher.addWatch(path: dir, mask: .create)
+
+			for index in 0..<fileCount {
+				try createFile(at: "\(dir)/file-\(index).txt")
+			}
+			try await Task.sleep(for: .milliseconds(500))
+
+			let eventTask = Task {
+				var events: [InotifyEvent] = []
+				for await event in await watcher.events {
+					events.append(event)
+				}
+				return events
+			}
+			try await Task.sleep(for: .seconds(1))
+			eventTask.cancel()
+			let events = await eventTask.value
+
+			#expect(events.count == fileCount, "Expected \(fileCount) CREATE events, got \(events.count)")
+		}
+	}
+}

Tests/InotifyIntegrationTests/DirectoryResolverTests.swift

@@ -14,4 +14,24 @@ struct DirectoryResolverTests {
 			#expect(directories.map { $0.description } == [dir, "\(dir)/Subfolder", subDirectory])
 		}
 	}
+
+	@Test func doesNotDescendIntoExcludedDirectories() async throws {
+		try await withTempDir { dir in
+			let excludedSubdirectory = "\(dir)/Excluded/Inside"
+			try FileManager.default.createDirectory(atPath: excludedSubdirectory, withIntermediateDirectories: true)
+			let directories = try await DirectoryResolver.resolve(dir, excluding: ["Excluded"])
+
+			#expect(directories.map { $0.description } == [dir])
+		}
+	}
+
+	@Test func doesNotDescendIntoDirectoriesMatchingAnExcludedPattern() async throws {
+		try await withTempDir { dir in
+			let excludedSubdirectory = "\(dir)/@eaDir/Inside"
+			try FileManager.default.createDirectory(atPath: excludedSubdirectory, withIntermediateDirectories: true)
+			let directories = try await DirectoryResolver.resolve([dir], excluding: ExclusionList(patterns: ["@*"]))
+
+			#expect(directories.map { $0.description } == [dir])
+		}
+	}
 }

Tests/InotifyIntegrationTests/EventMaskTests.swift

@@ -0,0 +1,31 @@
+import CInotify
+import Testing
+@testable import Inotify
+
+@Suite("Event Mask")
+struct EventMaskTests {
+	@Test(arguments: [
+		(InotifyEventMask.access, UInt32(IN_ACCESS)),
+		(.attrib, UInt32(IN_ATTRIB)),
+		(.closeWrite, UInt32(IN_CLOSE_WRITE)),
+		(.closeNoWrite, UInt32(IN_CLOSE_NOWRITE)),
+		(.create, UInt32(IN_CREATE)),
+		(.delete, UInt32(IN_DELETE)),
+		(.deleteSelf, UInt32(IN_DELETE_SELF)),
+		(.modify, UInt32(IN_MODIFY)),
+		(.moveSelf, UInt32(IN_MOVE_SELF)),
+		(.movedFrom, UInt32(IN_MOVED_FROM)),
+		(.movedTo, UInt32(IN_MOVED_TO)),
+		(.open, UInt32(IN_OPEN)),
+		(.dontFollow, UInt32(IN_DONT_FOLLOW)),
+		(.onlyDir, UInt32(IN_ONLYDIR)),
+		(.oneShot, UInt32(IN_ONESHOT)),
+		(.isDir, UInt32(IN_ISDIR)),
+		(.ignored, UInt32(IN_IGNORED)),
+		(.queueOverflow, UInt32(IN_Q_OVERFLOW)),
+		(.unmount, UInt32(IN_UNMOUNT)),
+	] as [(InotifyEventMask, UInt32)])
+	func matchesTheKernelConstant(mask: InotifyEventMask, constant: UInt32) {
+		#expect(mask.rawValue == constant)
+	}
+}

Tests/InotifyIntegrationTests/ExclusionTests.swift

@@ -0,0 +1,22 @@
+import Testing
+@testable import Inotify
+
+@Suite("Exclusion")
+struct ExclusionTests {
+	@Test func excludesANameThatMatchesAPattern() async throws {
+		let inotify = try Inotify()
+		await inotify.exclude(patterns: "*.tmp", "@*")
+
+		#expect(await inotify.isExcluded("scan.tmp"))
+		#expect(await inotify.isExcluded("@eaDir"))
+		#expect(await !inotify.isExcluded("scan.pdf"))
+	}
+
+	@Test func excludesAnExactName() async throws {
+		let inotify = try Inotify()
+		await inotify.exclude(name: ".git")
+
+		#expect(await inotify.isExcluded(".git"))
+		#expect(await !inotify.isExcluded(".gitignore"))
+	}
+}

Tests/InotifyIntegrationTests/InotifyLimitTests.swift

@@ -40,4 +40,35 @@ struct InotifyLimitTests {
 			}
 		}
 	}
+
+	@Test func reportsQueueOverflowInsteadOfDroppingIt() async throws {
+		try await withTempDir { dir in
+			try await withInotifyWatchLimit(of: 1, for: [.queuedEvents]) {
+				let watcher = try Inotify()
+				try await watcher.addWatch(path: dir, mask: .allEvents)
+				let overflowTask = Task { () -> (InotifyEvent?, Int) in
+					var received = 0
+					for await event in await watcher.events {
+						received += 1
+						if event.mask.contains(.queueOverflow) { return (event, received) }
+					}
+					return (nil, received)
+				}
+
+				let deadline = ContinuousClock.now + .seconds(5)
+				var index = 0
+				while !overflowTask.isCancelled, ContinuousClock.now < deadline {
+					try createFile(at: "\(dir)/burst-\(index).txt", contents: "hello")
+					index += 1
+					if index % 200 == 0 { await Task.yield() }
+				}
+				overflowTask.cancel()
+				let (overflow, received) = await overflowTask.value
+
+				#expect(overflow != nil, "Expected a queue overflow event after \(index) file creations and \(received) received events")
+				#expect(overflow?.watchDescriptor == -1)
+				#expect(overflow?.path == "")
+			}
+		}
+	}
 }

Tests/InotifyIntegrationTests/LifecycleTests.swift

@@ -0,0 +1,24 @@
+import Foundation
+import Testing
+@testable import Inotify
+
+@Suite("Instance Lifecycle")
+struct LifecycleTests {
+	@Test func aDeallocatedInstanceDoesNotStealEventsOfItsSuccessor() async throws {
+		try await withTempDir { dir in
+			let filename = "after-reuse.txt"
+			do {
+				let predecessor = try Inotify()
+				try await predecessor.addWatch(path: dir, mask: .create)
+			}
+
+			let events = try await getEventsForTrigger(
+				in: dir,
+				mask: .create,
+			) { try createFile(at: "\($0)/\(filename)") }
+
+			let createEvent = events.first { $0.mask.contains(.create) && $0.path.lastComponent?.string == filename }
+			#expect(createEvent != nil, "Expected CREATE for '\(filename)', got: \(events)")
+		}
+	}
+}

Tests/InotifyIntegrationTests/RecursiveEventTests.swift

@@ -39,6 +39,44 @@ struct RecursiveEventTests {
 		}
 	}
 
+	@Test func ignoresFileCreationInASubfolderMatchingAnExcludedPattern() async throws {
+		try await withTempDir { dir in
+			let subDirectory = "\(dir)/@eaDir"
+			let filepath = "\(subDirectory)/modify-target.txt"
+			try FileManager.default.createDirectory(atPath: subDirectory, withIntermediateDirectories: true)
+
+			let events = try await getEventsForTrigger(
+				in: dir,
+				mask: [.create],
+				recursive: .recursive,
+				excludePatterns: ["@*"]
+			) { _ in try createFile(at: "\(filepath)", contents: "hello") }
+
+			let createEvent = events.first { $0.mask.contains(.create) && $0.path.string == filepath }
+			#expect(createEvent == nil, "Did not expect CREATE for '\(filepath)', got: \(events)")
+		}
+	}
+
+	@Test func doesNotWatchANewSubfolderMatchingAnExcludedPattern() async throws {
+		try await withTempDir { dir in
+			let subDirectory = "\(dir)/@eaDir"
+			let filepath = "\(subDirectory)/modify-target.txt"
+
+			let events = try await getEventsForTrigger(
+				in: dir,
+				mask: [.create],
+				recursive: .withAutomaticSubtreeWatching,
+				excludePatterns: ["@*"]
+			) { _ in
+				try FileManager.default.createDirectory(atPath: subDirectory, withIntermediateDirectories: true)
+				try await Task.sleep(for: .milliseconds(400))
+				try createFile(at: "\(filepath)", contents: "hello")
+			}
+
+			#expect(events.isEmpty, "Did not expect any event, got: \(events)")
+		}
+	}
+
 	@Test func newSubfoldersOfRecursiveWatchAreAutomaticallyWatchedToo() async throws {
 		try await withTempDir { dir in
 			let subDirectory = "\(dir)/Subfolder"
@@ -58,4 +96,66 @@ struct RecursiveEventTests {
 			#expect(createEvent != nil, "Expected CREATE for '\(filepath)', got: \(events)")
 		}
 	}
+
+	@Test func stopsReportingForDirectoriesMovedOutOfTheWatchedTree() async throws {
+		try await withTempDir { dir in
+			let root = "\(dir)/Root"
+			let outside = "\(dir)/Outside"
+			let movedSource = "\(root)/Moved"
+			let movedDestination = "\(outside)/Moved"
+			let filename = "created-after-move.txt"
+			try FileManager.default.createDirectory(atPath: movedSource, withIntermediateDirectories: true)
+			try FileManager.default.createDirectory(atPath: outside, withIntermediateDirectories: true)
+
+			let events = try await getEventsForTrigger(
+				in: root,
+				mask: [.create, .movedFrom],
+				recursive: .withAutomaticSubtreeWatching
+			) { _ in
+				try FileManager.default.moveItem(atPath: movedSource, toPath: movedDestination)
+				try await Task.sleep(for: .milliseconds(400))
+				try createFile(at: "\(movedDestination)/\(filename)", contents: "hello")
+			}
+
+			let staleEvent = events.first { $0.mask.contains(.create) && $0.path.lastComponent?.string == filename }
+			#expect(staleEvent == nil, "Did not expect CREATE for '\(filename)' after its directory left the tree, got: \(events)")
+		}
+	}
+
+	@Test func watchesAndReportsContentOfDirectoriesMovedIntoTheTree() async throws {
+		try await withTempDir { dir in
+			let root = "\(dir)/Root"
+			let treeSource = "\(dir)/Outside/Tree"
+			let treeDestination = "\(root)/Tree"
+			try FileManager.default.createDirectory(atPath: "\(treeSource)/Sub", withIntermediateDirectories: true)
+			try FileManager.default.createDirectory(atPath: root, withIntermediateDirectories: true)
+			try createFile(at: "\(treeSource)/existing.txt", contents: "hello")
+			try createFile(at: "\(treeSource)/Sub/nested.txt", contents: "hello")
+
+			let events = try await getEventsForTrigger(
+				in: root,
+				mask: [.create, .movedTo],
+				recursive: .withAutomaticSubtreeWatching
+			) { _ in
+				try FileManager.default.moveItem(atPath: treeSource, toPath: treeDestination)
+				try await Task.sleep(for: .milliseconds(400))
+				try createFile(at: "\(treeDestination)/Sub/created-after-move.txt", contents: "hello")
+			}
+
+			let movedIn = events.first { $0.mask.contains(.movedTo) && $0.mask.contains(.isDir) && $0.path.string == treeDestination }
+			#expect(movedIn != nil, "Expected MOVED_TO for '\(treeDestination)', got: \(events)")
+
+			let existing = events.first { $0.synthesized && $0.mask.contains(.movedTo) && $0.path.string == "\(treeDestination)/existing.txt" }
+			#expect(existing != nil, "Expected a synthesized MOVED_TO for the existing file, got: \(events)")
+
+			let subdirectory = events.first { $0.synthesized && $0.mask.contains(.isDir) && $0.path.string == "\(treeDestination)/Sub" }
+			#expect(subdirectory != nil, "Expected a synthesized MOVED_TO for the existing subdirectory, got: \(events)")
+
+			let nested = events.first { $0.synthesized && $0.path.string == "\(treeDestination)/Sub/nested.txt" }
+			#expect(nested != nil, "Expected a synthesized MOVED_TO for the nested file, got: \(events)")
+
+			let createdAfterMove = events.first { !$0.synthesized && $0.mask.contains(.create) && $0.path.string == "\(treeDestination)/Sub/created-after-move.txt" }
+			#expect(createdAfterMove != nil, "Expected CREATE inside the moved-in subdirectory, got: \(events)")
+		}
+	}
 }

Tests/InotifyIntegrationTests/Utilities/getEventsForTrigger.swift

@@ -11,10 +11,12 @@ func getEventsForTrigger(
 	mask: InotifyEventMask,
 	recursive: RecursivKind = .nonrecursive,
 	exclude: [String] = [],
+	excludePatterns: [String] = [],
 	trigger: @escaping (String) async throws -> Void,
 ) async throws -> [InotifyEvent] {
 	let watcher = try Inotify()
 	await watcher.exclude(names: exclude)
+	await watcher.exclude(patterns: excludePatterns)
 	switch recursive {
 	case .nonrecursive:
 		try await watcher.addWatch(path: dir, mask: mask)

Tests/InotifyIntegrationTests/Utilities/withLowInotifyWatchLimit.swift

@@ -1,10 +1,28 @@
 import Foundation
 
-func withInotifyWatchLimit(of limit: Int, _ body: () async throws -> Void) async throws {
+enum InotifyLimit: String, CaseIterable {
+	case userWatches = "max_user_watches"
+	case userInstances = "max_user_instances"
+	case queuedEvents = "max_queued_events"
+}
+
+func withInotifyWatchLimit(
+	of limit: Int,
+	for limits: [InotifyLimit] = InotifyLimit.allCases,
+	_ body: () async throws -> Void
+) async throws {
 	let confPath = URL(filePath: "/proc/sys/fs/inotify")
-	let filenames = ["max_user_watches", "max_user_instances", "max_queued_events"]
+	let filenames = limits.map(\.rawValue)
 	var previousLimits: [String: String] = [:]
 
+	defer {
+		for filename in filenames {
+			let filePath = confPath.appending(path: filename)
+			guard let previousLimit = previousLimits[filename] else { continue }
+			try? previousLimit.write(to: filePath, atomically: false, encoding: .utf8)
+		}
+	}
+
 	for filename in filenames {
 		let filePath = confPath.appending(path: filename)
 		let currentLimit = try String(contentsOf: filePath, encoding: .utf8)
@@ -13,10 +31,4 @@ func withInotifyWatchLimit(of limit: Int, _ body: () async throws -> Void) async
 	}
 
 	try await body()
-
-	for filename in filenames {
-		let filePath = confPath.appending(path: filename)
-		guard let previousLimit = previousLimits[filename] else { continue }
-		try previousLimit.write(to: filePath, atomically: false, encoding: .utf8)
-	}
 }