Configuration reference

The configuration file is TOML. The schema is defined by config.ViperConfig (config/config.go) and translated to the runtime form (config.Config / config.Rule / config.Allowlist) by ViperConfig.Translate.

Resolution order

initConfig in cmd/root.go resolves the active config in this order:

1. --config / -c flag (path)
2. Environment variable GITLEAKS_CONFIG (path)
3. Environment variable GITLEAKS_CONFIG_TOML (file content)
4. <source>/.gitleaks.toml
5. The embedded default (config/gitleaks.toml)

If source is a single file (not a directory), only step 5 applies.

Top-level keys

Key	Type	Notes
title	string	Free-form
description	string	Free-form
minVersion	string	Semver. validateMinVersion warns (does not fail) if the running Gitleaks is older.
[extend]	table	Inheritance from another config or the embedded default. Mutually exclusive useDefault / path. Max recursion: 2 levels.
[[rules]]	table array	Detection rules
[[allowlists]]	table array	Global allowlists (and targeted, via targetRules)

Older singular forms ([allowlist], [rules.allowlist]) are still accepted but cannot coexist with the plural forms on the same scope.

[extend]

[extend]
useDefault = true                 # OR path = "common.toml"
disabledRules = ["generic-api-key"]

Behavior:

• useDefault = true extends from the embedded default rules (config.DefaultConfig).
• path = "..." extends from a TOML file at that path (relative to the config that named it).
• disabledRules removes specific rule IDs from whatever was extended.

When extending, your config's rules with IDs that exist in the parent inherit the parent's fields and selectively override Description, Entropy, SecretGroup, Regex, Path. Tags, Keywords, and Allowlists are appended (not replaced). See Config.extend in config/config.go.

[[rules]]

Field	Type	Notes
id	string (required)	Globally unique. Rule.Validate errors if missing.
description	string	Human-readable.
regex	string	Go regex. Required unless path is set. RE2 syntax — no lookarounds.
path	string	File path regex. Required unless regex is set.
entropy	float	Optional Shannon entropy threshold for the captured secret.
secretGroup	int	1-indexed capture group containing the secret. Validated against regex.NumSubexp().
keywords	string array	Pre-regex prefilter. Lowercased internally.
tags	string array	Metadata for reporting.
[[rules.allowlists]]	nested table array	Per-rule allowlists.
[[rules.required]]	nested table array	Auxiliary rules for composite detection.
skipReport	bool	Suppress findings unless this rule is being used as an auxiliary.

Either regex or path must be set; otherwise Rule.Validate returns "both regex and path are empty, this rule will have no effect".

[[rules.allowlists]] and [[allowlists]]

Field	Type	Notes
description	string	Free-form
condition	"OR" (default) or "AND"	All criteria must match for AND; any one for OR.
commits	string array	Commit SHAs to ignore. Case-insensitive.
paths	regex array	File path regexes.
regexes	regex array	Content regexes.
regexTarget	"secret" (default), "match", or "line"	What regexes is tested against.
stopwords	string array	Substrings of the extracted secret. Aho-Corasick.
targetRules	string array	Global-only: scope this allowlist to specific rule IDs. Introduced v8.25.0.

An allowlist with no criteria is a config error.

[[rules.required]]

Field	Type	Notes
id	string (required)	Must reference an existing rule (validated post-extend).
withinLines	int	Optional vertical proximity to the primary match.
withinColumns	int	Optional horizontal proximity.

Both unset = "anywhere in the same fragment". See features/composite-rules.

CLI flags

The persistent flags (registered in cmd/root.go):

Flag	Default	Notes
-c, --config	(empty)	TOML path
-r, --report-path	(empty)	Output file (- for stdout)
-f, --report-format	(inferred)	json / csv / junit / sarif / template
--report-template	(empty)	Path to a Go template file (forces format=template)
-b, --baseline-path	(empty)	Existing JSON report whose findings should be filtered out
--exit-code	1	Exit code when leaks are found
-l, --log-level	info	trace/debug/info/warn/error/fatal
-v, --verbose	false	Pretty-print findings to stdout
--no-color	false	Disable lipgloss colors
--max-target-megabytes	0	Skip files larger than this
--ignore-gitleaks-allow	false	Don't honor gitleaks:allow markers
--redact	0 (or 100 if flag passed without value)	Mask N% of each secret
--no-banner	false	Suppress the ASCII banner
--enable-rule	(empty)	Whitelist of rule IDs
-i, --gitleaks-ignore-path	.	Where to look for .gitleaksignore
--max-decode-depth	5	Recursive base64/hex/percent decoding
--max-archive-depth	0	Archive recursion (off by default)
--timeout	0	Whole-command timeout (seconds, 0 = none)
--diagnostics	(empty)	cpu,mem,trace or http
--diagnostics-dir	(empty)	Where to drop pprof/trace outputs

Subcommand-specific flags:

Command	Flag	Notes
git	--platform	github/gitlab/azuredevops/gitea/bitbucket/none
git	--staged	Scan staged diff (pre-commit)
git	--pre-commit	Scan working tree diff
git	--log-opts	Extra arguments to git log -p
dir	--follow-symlinks	Resolve symlinks during walk

Environment variables

Variable	Notes
GITLEAKS_CONFIG	Path to a TOML config (overridden by --config)
GITLEAKS_CONFIG_TOML	Inline TOML content (used when set and --config/GITLEAKS_CONFIG aren't)

Exit codes

Code	Meaning
0	No leaks
1	Leaks found or a fatal error occurred (configurable via --exit-code)
126	Unknown CLI flag