Gitleaks: Regex-Based Secret Detection for Git Repositories, Files, and Streams

What Gitleaks Detects and Who Uses It

Gitleaks scans code, past or present, for secrets. That is the one-line description from the README's usage output. In practice, the tool uses regex rules to find patterns matching API keys, tokens, passwords, and other credentials embedded in source files, git history, commit messages, and arbitrary streams. Each finding in the output includes the file path, line number, commit hash, author, date, and a fingerprint string composed of the commit hash, file path, rule ID, and line number.

The primary users are security engineers running compliance checks, developers integrating secret detection into their local workflow before pushing, and CI pipelines that need to gate merges on clean scans. The tool supports three scanning modes: git for repositories with commit history, dir for plain directories and files, and stdin for streaming data from another process. The README includes an example output showing a Sidekiq enterprise token found in a Go source file, with the complete fingerprint, entropy value, and rule ID that matched it.

Three Scanning Modes: git, dir, and stdin

The git command scans a local git repository's commit history. Under the hood, it runs git log -p to generate patches and scans those patches. The --log-opts flag passes options directly to git log, which enables scanning a specific commit range. The README gives this example for scanning between two commits:

gitleaks git -v --log-opts="--all commitA..commitB" path_to_repo

If no target path is given, Gitleaks scans the current working directory as a git repository.

The dir command (with aliases files and directory) scans directories and files without requiring a git repository. The README example is: gitleaks dir -v path_to_directory_or_file. This mode is useful for scanning build artifacts, configuration exports, or any non-git directory.

The stdin command reads data piped from another process. The README gives: cat some_file | gitleaks -v stdin. This enables integration into shell pipelines and log analysis workflows. The README notes that the detect and protect commands from v8.18.0 and earlier are deprecated since v8.19.0 and have been hidden from the --help output, though they still work.

Installing Gitleaks on macOS, Linux, Windows, and Docker

On macOS, the simplest install is through Homebrew:

brew install gitleaks

For Docker, two registries provide official images:

docker pull zricethezav/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] [OPTIONS] [SOURCE_PATH]

The Docker Hub image is zricethezav/gitleaks, and the GitHub Container Registry image is ghcr.io/gitleaks/gitleaks. To build from source, Go must be installed:

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

Release binaries for many platforms and operating systems are also available on the GitHub releases page. On Windows, the README notes Gitleaks is available through its release binaries and can be run from the command prompt or PowerShell. The Dockerfile in the repository builds the binary using golang:1.24 and packages it into an alpine:3.22 final image, which explains the small image size. The go.mod file pins Go version 1.24.11.

Pre-Commit Hook Integration

Gitleaks can run as a pre-commit hook that blocks commits containing secrets before they enter the repository. The setup requires the pre-commit framework to be installed separately. After that, a .pre-commit-config.yaml file at the repository root activates Gitleaks:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

The README provides two hook IDs: gitleaks for native execution and gitleaks-docker for using the Docker image. After adding the config, running pre-commit install activates the hook. The README demonstrates that a commit containing a secret will fail with the message "Detect hardcoded secrets...Failed".

To skip the Gitleaks check for a specific commit, the README shows the SKIP=gitleaks prefix: SKIP=gitleaks git commit -m "skip gitleaks check". This is a deliberate escape hatch for cases where the commit is known to contain test fixtures or other intentional non-secrets that match the detection patterns. The pre-commit autoupdate command updates the pinned rev to the latest release.

The Detection Engine: Regex and Aho-Corasick

The README links to a blog post titled "Regex is (almost) all you need" as the explanation for how the detection engine works. The go.mod file confirms that the library github.com/BobuSumisu/aho-corasick is a dependency, which suggests multi-pattern string matching is used to efficiently screen for potential secrets before applying the more expensive regex rules.

The configuration file format is TOML, and the .gitleaks.toml in the repository root provides the rule definitions. A custom config file can be specified with the --config flag. The configuration supports an allowlist section in .gitleaksignore for suppressing specific findings by their fingerprint. The cmd/generate/config/ directory in the repository contains code that generates the gitleaks.toml from individual rule files; the Makefile regenerates it with go generate ./... before each build. This split between the generated config and the individual rule sources makes the rule set maintainable at scale.

The go.mod also lists github.com/h2non/filetype for binary file type detection and github.com/mholt/archives for scanning inside archive files, which extends coverage beyond plain text files.

Baseline Reports and Configuration Options

For repositories with a long commit history, scanning all commits will produce findings that are already known. Gitleaks supports a baseline mechanism: a previous scan's report file is passed to subsequent scans with --baseline-path, and any finding that appears in the baseline is ignored. Creating the baseline report is done with:

gitleaks git --report-path gitleaks-report.json

Once a baseline report exists, it can be applied on future runs to suppress old findings and surface only new ones. This is the recommended workflow for projects with legacy secrets that have already been rotated.

Other command-line flags documented in the README include: -c / --config for specifying the rule configuration file, -v for verbose output showing each finding's details, --log-opts for passing additional options to git log when scanning a repository, and --report-path for saving the scan results to a file. Report templates are in the report_templates/ directory of the repository. The report output includes a Fingerprint field that combines commit hash, file path, rule ID, and line number to uniquely identify each finding.

Feature Complete: What This Means for Adopters

The README opens with a warning that stands out from most project READMEs: Gitleaks is feature complete, no new features will be merged, future releases will be security patches only, and the maintainer is shifting focus to Betterleaks at betterleaks/betterleaks. This is a significant statement for teams evaluating whether to adopt the tool.

Practically, it means the existing installation and integration continue to work as documented. Security patch releases will address vulnerabilities in the Go binary or its dependencies. However, teams who need coverage for new secret types, new output formats, or integration with platforms not currently supported will not get those from Gitleaks. They will need to either maintain a custom configuration file with additional rules or migrate to Betterleaks when it matures.

The most recent Gitleaks release is v8.30.1 from 2026-03-21. The repository received its last push on 2026-09-09. The version 8 series has been the stable series since the module path was updated to github.com/zricethezav/gitleaks/v8. The USERS.md file in the repository documents known adopters.

TruffleHog Comparison and License

TruffleHog is the most direct alternative to Gitleaks. The RELATED SEARCHES data confirms that the comparison is a common search. TruffleHog is maintained by Truffle Security and focuses on entropy-based and pattern-based detection across multiple source types including git, GitHub, GitLab, S3, and other cloud storage backends. Gitleaks focuses on git repositories, local directories, and stdin, with a regex-centric approach. TruffleHog provides verified secret detection for some credential types, confirming whether a found key is actually active, which Gitleaks does not. Teams who need multi-source scanning beyond git repositories or verified findings should evaluate TruffleHog. Teams who need a simple, self-contained binary for git and local file scanning with a pre-commit hook will find Gitleaks sufficient.

Gitleaks is licensed under MIT, which permits commercial use and modification without requiring source disclosure. The go.mod module path is github.com/zricethezav/gitleaks/v8, reflecting the original author's username. The Gitleaks-Action GitHub Action at gitleaks/gitleaks-action provides a ready-made integration for GitHub repositories without requiring local installation.

Editorial conclusion

Security engineers and DevSecOps teams who need to scan git history or working directories for leaked credentials should find Gitleaks directly usable through its Homebrew, Docker, and GitHub Actions integrations. The feature-complete declaration means no new detection rules or capabilities will be added to this tool, so teams who need ongoing expansion of the rule set or new features should evaluate Betterleaks at betterleaks/betterleaks. Before adding Gitleaks to a CI pipeline, run it against the existing repository history to establish a baseline report that can be passed with --baseline-path, preventing known findings from blocking every future commit.

Frequently asked questions

Official sources

1. gitleaks/gitleaks on GitHub
2. License: MIT
3. Project website
4. README
5. Releases