Event Filtering¶

Blink provides powerful filtering capabilities to focus on specific files or event types. This can be useful to reduce noise and only receive notifications for the changes you care about.

Improved Filtering¶

Blink includes an advanced filtering system that provides more precise control over which events are processed:

• Improved Pattern Matching: Better file path matching with glob patterns
• Combined Event and Path Filtering: Single-pass filtering for better performance
• Optimized Filter Application: Filters are applied at the watcher level for efficiency
• Separate File and Directory Handling: Different filtering rules can be applied to files and directories

File Pattern Filtering¶

You can filter events based on file patterns using the --include and --exclude flags:

# Only watch for changes to JavaScript, CSS, and HTML files
blink --include "*.js,*.css,*.html"

# Ignore node_modules directory and temporary files
blink --exclude "node_modules,*.tmp"

# Combine include and exclude patterns
blink --include "*.js,*.css,*.html" --exclude "node_modules,*.tmp"

Include Patterns¶

The --include flag specifies patterns for files that should be included in the watch list. Only files matching these patterns will trigger events.

Patterns are comma-separated and support the following wildcards:

• *: Matches any sequence of non-separator characters
• ?: Matches any single non-separator character
• [...]: Matches any character in the set
• [^...]: Matches any character not in the set

Examples:

• *.js: All JavaScript files
• src/*.js: JavaScript files in the src directory
• *.{js,css,html}: JavaScript, CSS, and HTML files
• [a-z]*.js: JavaScript files starting with a lowercase letter

Exclude Patterns¶

The --exclude flag specifies patterns for files that should be excluded from the watch list. Files matching these patterns will not trigger events.

Exclude patterns have the same format as include patterns.

Examples:

• node_modules: The node_modules directory
• *.tmp: Temporary files
• *.{log,tmp,bak}: Log, temporary, and backup files
• .*: Hidden files (starting with a dot)

Event Type Filtering¶

You can filter events based on their type using the --events and --ignore flags:

# Only trigger on write and create events
blink --events "write,create"

# Ignore chmod events
blink --ignore "chmod"

# Combine event type filters
blink --events "write,create" --ignore "chmod"

Available Event Types¶

Blink supports the following event types:

• create: File or directory creation
• write: File modification
• remove: File or directory removal
• rename: File or directory renaming
• chmod: Permission changes

Using Filters with the Watcher¶

The watcher applies filters more efficiently by:

1. Checking exclude patterns first for better performance
2. Applying path filters before event type filters
3. Optimizing pattern matching for common use cases
4. Handling directory events separately from file events

This results in better performance, especially for large directory structures with many files.

Using Filters in the Go Library¶

If you're using Blink as a library in your Go projects, you can use the filtering API with the watcher:

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Create a filter
    filter := blink.NewEventFilter()

    // Set include patterns
    filter.SetIncludePatterns("*.js,*.css,*.html")

    // Set exclude patterns
    filter.SetExcludePatterns("node_modules,*.tmp")

    // Set include event types
    filter.SetIncludeEvents("write,create")

    // Set ignore event types
    filter.SetIgnoreEvents("chmod")

    // Create watcher configuration
    config := blink.WatcherConfig{
        RootPath:        ".",
        Recursive:       true,
        HandlerDelay:    100 * time.Millisecond,
        PollInterval:    4 * time.Second,
        IncludePatterns: []string{"*.js", "*.css", "*.html"},
        ExcludePatterns: []string{"node_modules", "*.tmp"},
        IncludeEvents:   []string{"write", "create"},
        IgnoreEvents:    []string{"chmod"},
    }

    // Create watcher
    watcher, err := blink.NewWatcher(config)
    if err != nil {
        panic(err)
    }

    // Start the watcher
    watcher.Start()

    // Process events
    for {
        select {
        case eventBatch := <-watcher.Events():
            // Process batch of events
            for _, event := range eventBatch {
                fmt.Println("Event:", event)
            }
        case err := <-watcher.Errors():
            fmt.Println("Error:", err)
        }
    }
}