Exclude items by shell pattern as well as by name

Patterns such as `.*` or `@*` are matched against an item's own name
with `fnmatch`, in the same places as excluded names: resolving a
tree, extending a watch to a directory that appears later, and
delivering events. Dependents that prune large trees can now skip
whole families of directories without listing each name.

Sources/Inotify/DirectoryResolver.swift

@@ -4,28 +4,28 @@ 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, excluding: itemNames) { resolved.append($0) }
+			try await withSubdirectories(at: path, excluding: exclusions) { resolved.append($0) }
 		}
 
 		return resolved
 	}
 
-	/// The direct children of `directory`, without the excluded names.
-	static func entries(of directory: FilePath, excluding itemNames: Set<String> = []) async throws -> [(name: String, isDirectory: Bool)] {
+	/// 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 !itemNames.contains(name) else { continue }
+			guard !exclusions.excludes(name) else { continue }
 			entries.append((name: name, isDirectory: childContent.type == .directory))
 		}
 		try await directoryHandle.close()
@@ -33,14 +33,14 @@ public struct DirectoryResolver {
 	}
 
 	/// Calls `body` for every subdirectory below `path`, depth first. Excluded
-	/// names are neither reported nor descended into.
-	private static func withSubdirectories(at path: FilePath, excluding itemNames: Set<String>, body: (FilePath) async throws -> Void) async throws {
+	/// 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, !itemNames.contains(name) else { continue }
+			guard let name = childContent.path.lastComponent?.string, !exclusions.excludes(name) else { continue }
 			try await body(childContent.path)
-			try await withSubdirectories(at: childContent.path, excluding: itemNames, 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/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

@@ -37,11 +37,12 @@ When a directory is moved out of the watched tree, the watches on it and on its
 
 ### 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",
@@ -49,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

@@ -4,7 +4,7 @@ import SystemPackage
 
 public actor Inotify {
 	private let fd: CInt
-	private var excludedItemNames: Set<String> = []
+	private var exclusions = ExclusionList()
 	private var watches = InotifyWatchManager()
 	private nonisolated(unsafe) let eventReader: any DispatchSourceRead
 	private nonisolated let eventStream: AsyncStream<RawInotifyEvent>
@@ -33,12 +33,14 @@ public actor Inotify {
 		)
 	}
 
+	/// 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...) {
@@ -47,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)
 		}
 	}
 
@@ -63,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)
@@ -99,7 +122,7 @@ public actor Inotify {
 			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)
@@ -152,7 +175,7 @@ public actor Inotify {
 	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.excludedItemNames) 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(