Getting started

Gitleaks builds and runs on Linux, macOS, and Windows. The only build dependency is Go (the project currently targets Go 1.24+; CI tests on 1.25 — see go.mod and .github/workflows/test.yml).

Prerequisites

Tool	Why
Go ≥ 1.24	Build and test
git	Required at scan time for gitleaks git (uses git log -p / git diff)
make	Convenient targets in Makefile
golangci-lint	Optional, for make lint (config in .golangci.yaml)
gotestsum	Optional, used in CI for nicer test output

Docker is sufficient if you only want to use Gitleaks rather than develop on it (see the README for docker pull instructions).

Clone and build

git clone https://github.com/gitleaks/gitleaks.git
cd gitleaks
make build

make build (Makefile) does three things:

1. Regenerates config/gitleaks.toml from cmd/generate/config/rules/*.go via go generate ./... (only when sources changed).
2. Runs go fmt ./....
3. Runs go mod tidy && go build with -ldflags injecting the latest git tag into version.Version.

The resulting binary ./gitleaks is placed in the repo root.

Run a scan

The most common smoke test is to scan the repo against itself:

./gitleaks git -v .

You should see the ASCII banner, then no leaks found (assuming the .gitleaksignore file is intact). To scan a directory tree without git history:

./gitleaks dir -v ./testdata

To pipe content through stdin:

echo 'aws_access_key_id=AKIAIOSFODNN7EXAMPLE' | ./gitleaks stdin -v

Run the tests

make test           # go fmt, regenerate config, then go test ./... --race
make failfast       # quick iteration: stop on first failure
make test-cover     # produce cover.out and open the HTML report

The full test suite is heavy (detect/detect_test.go alone is ~2700 lines covering hundreds of rule fixtures). On a fresh checkout it can take several minutes.

Run the linter

make lint           # invokes golangci-lint with .golangci.yaml

The configuration enables revive, staticcheck, misspell, inamedparam, exhaustruct, and friends — see patterns and conventions.

Profile a scan

The repo ships with a make profile target (scripts/profile.sh) that builds the binary and runs it with CPU profiling enabled. You can also pass --diagnostics=cpu,mem,trace directly to any subcommand to drop pprof and trace files in --diagnostics-dir (default: cwd). See cmd/diagnostics.go and debugging.

Editor / IDE notes

The project follows standard Go conventions; any gopls-aware editor works. The custom regex engine selection is controlled by the gore2regex build tag — to develop against the WASM RE2 backend, set GOFLAGS='-tags=gore2regex' or build with go build -tags gore2regex ./....

Next steps

• Read architecture for the high-level data flow.
• Read how to contribute for the workflow expected on PRs.
• Browse systems for a deep dive into each subsystem.