ignore

go-ignore

A minimal, zero-dependency Go library for matching file paths against .gitignore patterns.

Features

• Zero dependencies — stdlib only
• Common gitignore syntax — *, ?, **, !, /, trailing /, \ escapes, [abc], [a-z]
• Nested .gitignore support — scoped base paths
• Cross-platform — Windows backslash normalization, Unix-correct literal backslash
• Automatic encoding handling — UTF-8 BOM, CRLF/CR/LF line endings
• Thread-safe — concurrent access supported
• Parse warnings — malformed pattern diagnostics
• Match debugging — MatchWithReason for troubleshooting
• Configurable — case sensitivity, backtrack limits

Installation

go get github.com/Sriram-PR/go-ignore

Requires Go 1.25 or later.

Quick Start

package main

import (
    "fmt"
    "os"

    ignore "github.com/Sriram-PR/go-ignore"
)

func main() {
    m := ignore.New()

    // IMPORTANT: Add .git/ explicitly if you want Git-like behavior
    // (the library intentionally doesn't auto-ignore .git/)
    m.AddPatterns("", []byte(".git/\n"))

    // Load .gitignore (BOM and CRLF automatically handled)
    content, _ := os.ReadFile(".gitignore")
    if warnings := m.AddPatterns("", content); len(warnings) > 0 {
        for _, w := range warnings {
            fmt.Printf("Warning line %d: %s\n", w.Line, w.Message)
        }
    }

    // Check paths (thread-safe)
    fmt.Println(m.Match("node_modules/foo.js", false)) // true (ignored)
    fmt.Println(m.Match("src/main.go", false))         // false (not ignored)
    fmt.Println(m.Match("build", true))                // true if "build/" pattern exists
}

Usage

Basic Matching

m := ignore.New()
m.AddPatterns("", []byte(`
*.log
build/
node_modules/
!important.log
`))

// Check if path should be ignored
// Second parameter indicates if path is a directory
m.Match("debug.log", false)           // true
m.Match("important.log", false)       // false (negated)
m.Match("build", true)                // true (directory)
m.Match("build/output.js", false)     // true (inside ignored dir)
m.Match("src/main.go", false)         // false

Nested .gitignore Files

m := ignore.New()

// Root .gitignore
m.AddPatterns("", []byte("*.log\n"))

// src/.gitignore (patterns scoped to src/)
m.AddPatterns("src", []byte("*.tmp\n!keep.tmp\n"))

// src/lib/.gitignore (patterns scoped to src/lib/)
m.AddPatterns("src/lib", []byte("*.bak\n"))

// Results:
m.Match("test.log", false)           // true (root pattern)
m.Match("src/test.log", false)       // true (root pattern applies everywhere)
m.Match("src/test.tmp", false)       // true (src pattern)
m.Match("src/keep.tmp", false)       // false (negated in src)
m.Match("test.tmp", false)           // false (src pattern doesn't apply at root)
m.Match("src/lib/test.bak", false)   // true (src/lib pattern)

Debug Why a Path Matches

m := ignore.New()
m.AddPatterns("", []byte(`
*.log
!important.log
build/
`))

result := m.MatchWithReason("debug.log", false)
fmt.Printf("Ignored: %v\n", result.Ignored)   // true
fmt.Printf("Rule: %s\n", result.Rule)         // *.log
fmt.Printf("Line: %d\n", result.Line)         // 1
fmt.Printf("Negated: %v\n", result.Negated)   // false

result = m.MatchWithReason("important.log", false)
fmt.Printf("Ignored: %v\n", result.Ignored)   // false (re-included)
fmt.Printf("Rule: %s\n", result.Rule)         // !important.log
fmt.Printf("Negated: %v\n", result.Negated)   // true

Case-Insensitive Matching (Windows/macOS)

// For case-insensitive filesystems
m := ignore.NewWithOptions(ignore.MatcherOptions{
    CaseInsensitive: true,
})

m.AddPatterns("", []byte("BUILD/\n*.LOG\n"))

m.Match("build", true)      // true
m.Match("Build", true)      // true
m.Match("BUILD", true)      // true
m.Match("test.log", false)  // true
m.Match("test.LOG", false)  // true

Parse Warnings

// Option 1: Collect warnings
m := ignore.New()
warnings := m.AddPatterns("", content)
for _, w := range warnings {
    fmt.Printf("Line %d: %s - %s\n", w.Line, w.Pattern, w.Message)
}

// Option 2: Use a handler (must be set BEFORE AddPatterns)
m := ignore.New()
m.SetWarningHandler(func(basePath string, w ignore.ParseWarning) {
    log.Printf("[%s] line %d: %s", basePath, w.Line, w.Message)
})
m.AddPatterns("", content)       // warnings go to handler
m.AddPatterns("src", srcContent) // warnings include "src" as basePath

Windows Path Support

On Windows, backslashes in paths are automatically normalized to forward slashes. On Linux/macOS, backslashes are treated as literal filename characters (matching Git's behavior).

m := ignore.New()
m.AddPatterns("", []byte("src/build/\n*.log\n"))

// On Windows: backslashes are converted to forward slashes
m.Match("src\\build\\output.exe", false)  // true on Windows
m.Match("src\\main.go", false)            // false on Windows

// On all platforms: forward slashes always work
m.Match("src/build/output.exe", false)    // true
m.Match("src/main.go", false)             // false

Concurrent Usage

m := ignore.New()
m.AddPatterns("", content)

// Safe to call Match from multiple goroutines
var wg sync.WaitGroup
for _, path := range paths {
    wg.Add(1)
    go func(p string) {
        defer wg.Done()
        if m.Match(p, false) {
            // handle ignored file
        }
    }(path)
}
wg.Wait()

Global Gitignore

Load the user's global gitignore file (core.excludesFile or ~/.config/git/ignore) with a single call:

m := ignore.New()

// Load global patterns (core.excludesFile → $XDG_CONFIG_HOME/git/ignore → ~/.config/git/ignore)
if err := m.AddGlobalPatterns(); err != nil {
    log.Fatal(err)
}

// Then load repo-level .gitignore as usual
content, _ := os.ReadFile(".gitignore")
m.AddPatterns("", content)

m.Match("debug.log", false) // may be ignored by global patterns

If the global gitignore file does not exist, AddGlobalPatterns returns nil (no error).

Repository Exclude File

Load the repository's .git/info/exclude file:

m := ignore.New()

// Load .git/info/exclude patterns
if err := m.AddExcludePatterns(".git"); err != nil {
    log.Fatal(err)
}

// Then load repo-level .gitignore as usual
content, _ := os.ReadFile(".gitignore")
m.AddPatterns("", content)

If the exclude file does not exist, AddExcludePatterns returns nil (no error).

Supported Syntax

Note: ? and character classes ([...]) operate on raw bytes, not Unicode code points, consistent with Git's behavior. A multi-byte UTF-8 character requires multiple ? to match.

Pattern Anchoring

• No slash → matches anywhere: temp matches temp, src/temp, a/b/temp
• Contains slash → anchored to base: src/temp matches only src/temp
• Leading slash → anchored to root: /temp matches only temp at root
• Trailing slash → directories only: build/ matches build/ dir and all contents
• **/ prefix → floats (not anchored): **/temp matches anywhere

Limitations

The library does not automatically ignore .git/ — add it explicitly if needed.

Path Normalization Notes

The library does not resolve .. (parent directory) components in paths. Paths containing .. are matched literally against patterns. If your application accepts paths from untrusted sources, use filepath.Clean() before passing them to Match() to prevent path traversal issues.

Resource Limits

Default limits prevent resource exhaustion from untrusted input:

Set any limit to -1 to disable it (not recommended for untrusted input).

API Reference

Types

type Matcher struct { /* ... */ }

type MatcherOptions struct {
    MaxBacktrackIterations int  // Default: 10000, use -1 for unlimited
    CaseInsensitive        bool // Default: false
    MaxPatterns            int  // Default: 100000, use -1 for unlimited
    MaxPatternLength       int  // Default: 4096, use -1 for unlimited
}

type MatchResult struct {
    Ignored  bool   // Final decision
    Matched  bool   // Whether any rule matched
    Rule     string // The matching pattern
    BasePath string // Source .gitignore location
    Line     int    // Line number (1-indexed)
    Negated  bool   // Was it a negation rule
}

type ParseWarning struct {
    Pattern  string
    Message  string
    Line     int
    BasePath string
}

type WarningHandler func(basePath string, warning ParseWarning)

Functions

func New() *Matcher
func NewWithOptions(opts MatcherOptions) *Matcher

func (m *Matcher) AddPatterns(basePath string, content []byte) []ParseWarning
func (m *Matcher) AddGlobalPatterns() error
func (m *Matcher) AddExcludePatterns(gitDir string) error
func (m *Matcher) Match(path string, isDir bool) bool
func (m *Matcher) MatchWithReason(path string, isDir bool) MatchResult
func (m *Matcher) SetWarningHandler(fn WarningHandler)
func (m *Matcher) Warnings() []ParseWarning
func (m *Matcher) RuleCount() int

Performance

Benchmarked on Intel i9-14900HX (Go 1.25, linux/amd64):

The backtrack budget (MaxBacktrackIterations, default 10,000) is shared across all rules within a single Match call. A matcher with many complex ** patterns will exhaust the budget faster than one with few patterns. When the budget is exceeded, remaining rules are treated as non-matching. Increase the budget via MatcherOptions if needed.

Thread Safety

Matcher is safe for concurrent use:

• Multiple goroutines can call Match simultaneously (read lock)
• AddPatterns can be called concurrently with Match (write lock)

Best practice: Batch all AddPatterns calls before starting concurrent Match operations to minimize lock contention.

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: go test ./...
2. Race detector passes: go test -race ./...
3. New features include tests
4. Code is formatted: go fmt ./...

License

MIT — see LICENSE for details.