SugarIgnore
gitignore matching over injected contents — fails closed on hostile patterns
The gitignore engine a repository-walking tool needs, extracted from candy-code so every app answers "is this path ignored?" the same way. It never touches the filesystem: the caller injects each ignore file's contents, so a TUI, a git server and a tree browser share one engine. A cloned repository supplies both the patterns and the paths, so patterns are treated as hostile input. First-party — there is no upstream Go port.
Install
composer require sugarcraft/sugar-ignore
Quickstart
use SugarCraft\Ignore\IgnoreRules;
$rules = IgnoreRules::fromPaths([
'.gitignore' => file_get_contents('.gitignore'),
'pkg/.gitignore' => "!keep.log\n",
'.git/info/exclude' => "scratch.txt\n",
]);
$rules->ignores('app/debug.log', false); // ".gitignore: *.log" (the deciding rule) or null
$rules->isIgnored('pkg/keep.log', false); // false
$rules->ignores('build', true); // directory-only rules need $isDir
The laws
No IOContents are injected as a path => text map; each file is scoped to its own directory and deeper files override shallower ones.
git semanticsNegation, trailing-slash directory rules, anchoring,
* ? classes, ** forms, escapes, .git/info/exclude below every file, and no re-including under an ignored directory.Bounded costSimple shapes run on PCRE; anything that could backtrack runs on a lazily built DFA. A PCRE limit error is never read as "no match".
Fails closedA rule too costly to decide hides (a negation does not re-include) and is reported on
undecidableRules(), not logged under a TUI.Use it for
- Agent file tools — candy-code's Glob, Grep and repo map.
- File browsers and git tooling — candy-files, candy-git and candy-git-server.
Source
API
| Class | Method | Description |
|---|---|---|
| IgnoreRules | static new(?string $root = null): self | Empty ruleset; nothing is ignored |
| IgnoreRules | static fromPaths(array $files, ?string $root = null): self | Build from path => contents; absolute paths under $root are stripped |
| IgnoreRules | withFile(string $path, string $contents): self | A new instance carrying one more (or replaced) ignore file |
| IgnoreRules | ignores(string $relPath, bool $isDir): ?string | The deciding <file>: <pattern>, or null when not ignored |
| IgnoreRules | isIgnored(string $relPath, bool $isDir): bool | Boolean form of ignores() |
| IgnoreRules | undecidableRules(): array / undecidablePatterns(): array | Rules too costly to decide, resolved toward hiding |
| Pattern | static parse(string $line): ?self / pcreMatch(string $subject): ?bool | One compiled ignore line and its PCRE fast path (null on a PCRE limit error) |
| Automaton | static for(Pattern $pattern): self / match(string $subject): ?bool | Backtrack-free matcher; null when over budget |