gogitignore

README

A fast and thread-safe Go library for matching paths against gitignore rules.

Documentation

Overview

Package gogitignore implements gitignore-style path matching, organized as a tree of matchers keyed by directory. Matchers cascade from outer (root) to inner (sub-directory) so an inner pattern can negate one set by an outer pattern, mirroring how Git evaluates nested .gitignore files.

Index

• type Matcher
  • func ParseIgnoreFile(r io.Reader) (Matcher, error)
  • func (m Matcher) Match(pth string, isDir bool) bool
• type Tree
  • func New() *Tree
  • func (t *Tree) InsertMatcher(pth string, m Matcher)
  • func (t *Tree) InsertPatterns(pth string, patterns ...string)
  • func (t *Tree) Match(pth string, isDir bool) bool

Types

type Matcher

type Matcher struct {
	// contains filtered or unexported fields
}

Matcher holds the compiled patterns from a single .gitignore file.

func ParseIgnoreFile

func ParseIgnoreFile(r io.Reader) (Matcher, error)

ParseIgnoreFile parses .gitignore file content in r into a Matcher. Blank lines and lines beginning with "#" are skipped. Trailing whitespace on each line is stripped. Returns an error only if reading from r fails; malformed patterns are silently dropped.

func (Matcher) Match

func (m Matcher) Match(pth string, isDir bool) bool

Match reports whether pth (relative to the matcher's base directory) is ignored according to this matcher's patterns. isDir reports whether pth is a directory. Patterns are evaluated in order; the last matching pattern wins, so a later "!negation" can re-include a previously matched path.

type Tree

type Tree struct {
	// contains filtered or unexported fields
}

Tree holds a hierarchy of gitignore matchers keyed by the directory the matcher applies to.

func New

func New() *Tree

New returns an empty Tree.

func (*Tree) InsertMatcher

func (t *Tree) InsertMatcher(pth string, m Matcher)

InsertMatcher inserts m into the tree at the given path. See InsertPatterns for path semantics.

func (*Tree) InsertPatterns

func (t *Tree) InsertPatterns(pth string, patterns ...string)

InsertPatterns parses patterns as gitignore lines and stores the resulting matcher at the given path. The path is the directory the patterns are relative to (e.g. "/" for root, "/sub" for a sub-directory). Replaces any existing matcher at that path.

The empty path "" is reserved for global patterns: they apply to every path in the tree and are evaluated before any in-tree .gitignore, so an in-tree pattern (negation included) can override a global one. This is the slot for patterns sourced from e.g. core.excludesFile; reading those from disk is the caller's responsibility.

func (*Tree) Match

func (t *Tree) Match(pth string, isDir bool) bool

Match reports whether pth should be ignored. pth is a leading-slash, slash-separated path (e.g. "/foo/bar.txt") relative to the tree root. isDir reports whether pth represents a directory.

Match walks the tree from root down to pth, applying each .gitignore matcher in turn. For every matcher it considers not just pth but every intermediate directory between the matcher's base and pth, so that a path inside an excluded directory is treated as ignored regardless of any later !-negation that would otherwise re-include it.