Configuration¶
Default config path is reglint-rules.yaml. Generate a starter with reglint init.
Top-level fields¶
Field names are verified against the shipped binary (Go struct in internal/config).
rules(required unlessruleFilesis non-empty): list of regex rules.include: repository-level include globs (default**/*). Overridden by per-rulepaths.exclude: repository-level exclude globs (default**/.git/**,**/node_modules/**,**/vendor/**). Overridden by per-ruleexclude.failOn: one oferror,warning,notice,info. Unset by default (no failure threshold).concurrency: worker count override (defaultGOMAXPROCS).baseline: default baseline file path used byanalyzewhen--baselineis not set.ruleFiles: ordered rule file paths loaded after this file's ownrules. Paths resolve relative to this config file's directory — see Rule files.git: default Git scan settings — see Git settings.consoleColorsEnabled: enable or disable ANSI color in console output (defaulttrue).ignoreFilesEnabled: enable or disable ignore file processing (defaulttrue).ignoreFiles: custom ignore file list (default.ignore,.reglintignore) — see Ignore files.
Binary files and files larger than --max-file-size (default 5 MB) are skipped; the console summary line and the stats section of the JSON output report skipped file counts.
Git settings¶
git.mode must be one of off|staged|diff (default off); mode: diff requires git.diff; git.addedLinesOnly is valid only for staged|diff.
git.mode:off,staged, ordiff.git.diff: diff target/range used bymode: diff.git.addedLinesOnly: report only matches on added lines (defaultfalse).git.gitignoreEnabled: enable.gitignorefiltering (defaulttrue).
Rule schema¶
Each rule in rules:
message(required): text reported for matches. Capture groups may be referenced as$1,$2, …regex(required): an RE2 regular expression.severity: one oferror,warning,notice,info.paths: per-rule include globs; a match only counts for paths matching at least one.exclude: per-rule exclude globs; matching paths are skipped for this rule.
Full example¶
include:
- "src/**"
- "lib/**"
exclude:
- "**/generated/**"
failOn: "error"
concurrency: 8
baseline: "testdata/baseline.json"
consoleColorsEnabled: true
ignoreFilesEnabled: true
ignoreFiles:
- ".ignore"
- ".reglintignore"
git:
mode: "diff"
diff: "HEAD~1..HEAD"
addedLinesOnly: false
gitignoreEnabled: true
ruleFiles:
- "rules-go.yaml"
- "rules-security.yaml"
rules:
- message: "Avoid hardcoded token: $1"
regex: "token\\s*[:=]\\s*([A-Za-z0-9_-]+)"
severity: "error"
paths:
- "src/**"
- message: "This is a warning message"
regex: "regex2"
severity: "warning"
exclude:
- "lib/vendor/**"
Rule files¶
Split rules out of the base config into dedicated files — useful for shared, curated rule packs referenced from the base config or passed on the command line.
- A rule file is a YAML document whose only allowed populated field is
rules(non-empty). Any other setting — includingruleFilesitself — is a validation error naming the offending field; unknown top-level keys are rejected too. - Merge order is append-only: base
rules→ruleFilesentries in declared order →--rulesflag values in flag order. - Two rules with the same
(message, regex)pair anywhere in the merged set are a validation error (also within a single file). reglint analyzeaccepts a repeatable--rules <path>flag; these paths resolve relative to the current working directory, unlikeruleFiles(config directory). Duplicate paths acrossruleFilesand--rulesare rejected.- Rule files contribute rules and nothing else: include/exclude,
failOn, git, baseline, ignore, and color settings come from the base config and CLI flags only.
Example rule file (rules-go.yaml):
rules:
- message: "TODO comment left in code"
regex: "TODO|FIXME"
severity: "notice"
paths:
- "**/*.go"
- message: "panic outside main/test"
regex: "\\bpanic\\("
severity: "warning"
paths:
- "**/*.go"
exclude:
- "**/*_test.go"
Rule pack example: regex hygiene¶
Rules match any line text, including the source text of other regexes — so a rule pack can flag patterns with shorter RE2 equivalents:
rules:
- message: 'use \d instead of [0-9] - equivalent in RE2 and shorter'
regex: '\[0-9\]'
severity: info
- message: 'use \w instead of [a-zA-Z0-9_] - equivalent in RE2 and shorter'
regex: '\[a-zA-Z0-9_\]'
severity: info
- message: 'use \w instead of [A-Za-z0-9_] - equivalent in RE2 and shorter'
regex: '\[A-Za-z0-9_\]'
severity: info
- message: 'prefer \s over [ \t] - RE2 \s also matches \r and \f'
regex: '\[ \\t\][+*]?'
severity: info
- message: 'quantifier {0,1} is redundant - use ? instead'
regex: '\{0,1\}'
severity: info
- message: 'quantifier {1} is redundant - drop it'
regex: '\{1\}'
severity: info
Attach it to any config:
reglint analyze -c reglint-rules.yaml --rules regex-hygiene.yaml
To lint your own config and rule files, point the base config's include at them — include/exclude always come from the base config, never from --rules packs:
# reglint-meta.yaml
include:
- "reglint-rules.yaml"
- "rules-*.yaml"
ruleFiles:
- "regex-hygiene.yaml"
Matching is line-based (no regex AST), so keep pack rules narrow — \[0-9\] deliberately does not match [a-z0-9], [^0-9], or [0-9-], but it will flag the literal text [0-9] in prose. Note there is no catastrophic-backtracking detection to write: RE2 is linear-time, so regex hygiene here is brevity and readability only.
Ignore files¶
Ignore files are processed by default in this order: .gitignore, then .ignore, then .reglintignore. Supported syntax: blank lines, # comments, ! negation, leading / anchoring, trailing / directory-only rules, and */?/** wildcards. The last matching rule wins.
Precedence per candidate path:
- Must match at least one effective include glob.
- Any exclude glob match removes it.
- Ignore matcher (last match wins) can still ignore it;
.ignore/.reglintignoretake priority over.gitignoreon conflicts. .gitignorecannot re-include a path removed by include/exclude filters.
Disable per run with --no-gitignore (only .gitignore) or --no-ignore-files (all ignore files), or globally with git.gitignoreEnabled: false / ignoreFilesEnabled: false. Git global excludes (core.excludesFile, .git/info/exclude) are not read.
An invalid ignore pattern exits with code 1 and reports <source>:<line>.
Validation¶
rulesis required unlessruleFilesis non-empty.failOnmust be one of the allowed values when set.concurrencymust be a positive integer when set.baselinemust be a non-empty string when set.ignoreFilesvalues must be non-empty file names without path separators or duplicates.git.modemust beoff|staged|diff;mode: diffrequiresgit.diff;addedLinesOnly: truerequiresstaged|diff.- Any YAML parse failure or invalid rule exits with code
1before scanning starts.
Colors¶
Console output uses ANSI severity colors by default. Disable in config or for a single run with NO_COLOR:
NO_COLOR=1 reglint analyze --config reglint-rules.yaml --format console
Authoritative detail: specs/configuration.md, specs/rule-files.md, specs/ignore-files.md.