From 8af25be549d19e2955af52c03b72866886a02b89 Mon Sep 17 00:00:00 2001 From: "T. R. Bernstein" Date: Wed, 16 Sep 2026 11:21:45 +0200 Subject: [PATCH] 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. --- README.md | 7 +++- Sources/Inotify/DirectoryResolver.swift | 20 +++++----- Sources/Inotify/ExclusionList.swift | 33 ++++++++++++++++ Sources/Inotify/Inotify.docc/Inotify.md | 2 +- .../Inotify.docc/WatchingDirectoryTrees.md | 5 ++- Sources/Inotify/Inotify.swift | 37 ++++++++++++++---- .../DirectoryResolverTests.swift | 10 +++++ .../ExclusionTests.swift | 22 +++++++++++ .../RecursiveEventTests.swift | 38 +++++++++++++++++++ .../Utilities/getEventsForTrigger.swift | 2 + 10 files changed, 154 insertions(+), 22 deletions(-) create mode 100644 Sources/Inotify/ExclusionList.swift create mode 100644 Tests/InotifyIntegrationTests/ExclusionTests.swift diff --git a/README.md b/README.md index 49cede5..648d914 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ When a watched directory is moved out of the tree, the watches on it and on its ## 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() @@ -89,13 +89,16 @@ 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 diff --git a/Sources/Inotify/DirectoryResolver.swift b/Sources/Inotify/DirectoryResolver.swift index 85017b7..05bacc2 100644 --- a/Sources/Inotify/DirectoryResolver.swift +++ b/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 = []) 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 = []) 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 = []) 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, 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() } diff --git a/Sources/Inotify/ExclusionList.swift b/Sources/Inotify/ExclusionList.swift new file mode 100644 index 0000000..67e6c3d --- /dev/null +++ b/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 = [] + private var patterns: [String] = [] + + init(names: Set = [], 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 } + } +} diff --git a/Sources/Inotify/Inotify.docc/Inotify.md b/Sources/Inotify/Inotify.docc/Inotify.md index c2f1af9..3fe58b5 100644 --- a/Sources/Inotify/Inotify.docc/Inotify.md +++ b/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 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 for details. All public types conform to `Sendable`, so they can be safely passed across concurrency boundaries. diff --git a/Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md b/Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md index 83b5044..76cc1d7 100644 --- a/Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md +++ b/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 diff --git a/Sources/Inotify/Inotify.swift b/Sources/Inotify/Inotify.swift index f743239..768b703 100644 --- a/Sources/Inotify/Inotify.swift +++ b/Sources/Inotify/Inotify.swift @@ -4,7 +4,7 @@ import SystemPackage public actor Inotify { private let fd: CInt - private var excludedItemNames: Set = [] + private var exclusions = ExclusionList() private var watches = InotifyWatchManager() private nonisolated(unsafe) let eventReader: any DispatchSourceRead private nonisolated let eventStream: AsyncStream @@ -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( diff --git a/Tests/InotifyIntegrationTests/DirectoryResolverTests.swift b/Tests/InotifyIntegrationTests/DirectoryResolverTests.swift index 12210a7..03755a2 100644 --- a/Tests/InotifyIntegrationTests/DirectoryResolverTests.swift +++ b/Tests/InotifyIntegrationTests/DirectoryResolverTests.swift @@ -24,4 +24,14 @@ struct DirectoryResolverTests { #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]) + } + } } diff --git a/Tests/InotifyIntegrationTests/ExclusionTests.swift b/Tests/InotifyIntegrationTests/ExclusionTests.swift new file mode 100644 index 0000000..b7139c3 --- /dev/null +++ b/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")) + } +} diff --git a/Tests/InotifyIntegrationTests/RecursiveEventTests.swift b/Tests/InotifyIntegrationTests/RecursiveEventTests.swift index ba0e282..b85a8ca 100644 --- a/Tests/InotifyIntegrationTests/RecursiveEventTests.swift +++ b/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" diff --git a/Tests/InotifyIntegrationTests/Utilities/getEventsForTrigger.swift b/Tests/InotifyIntegrationTests/Utilities/getEventsForTrigger.swift index 1cbfc97..424443b 100644 --- a/Tests/InotifyIntegrationTests/Utilities/getEventsForTrigger.swift +++ b/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)