Skip to content
Get packs

Guide · Open source

How to use gitleaks: scan repos, files and stdin for secrets

Updated · written with AI from the project's own documentation and checked against our catalogue data

Gitleaks is a command-line tool that searches code for secrets such as passwords, API keys, and tokens. This guide explains how to install it, run each of its three scanning modes, add it as a pre-commit hook, and read its flags. After following it, you will be able to scan a repository's history and files and block commits that contain credentials.

Gitleaksgitleaks/gitleaks · ★ 30.6k · MIT

Quick start

  1. 1Install gitleaks. Install it with Homebrew on macOS, pull the Docker image, or clone the repository and run make build if you have Go installed.
  2. 2Scan a repository. Run gitleaks git -v in a repo to scan its commit history using git log -p.
  3. 3Scan files. Run gitleaks dir -v on a directory or file to check its current contents.
  4. 4Scan piped text. Pipe text into gitleaks with the stdin command to check any stream of data.
  5. 5Install the pre-commit hook. Add a .pre-commit-config.yaml file, run pre-commit autoupdate and pre-commit install so commits with secrets are blocked.
  6. 6Tune the results. Use a config file, a baseline, or the --enable-rule and --exit-code flags to control what is reported and how the run ends.

Install gitleaks with Homebrew, Docker or Go

On macOS you can install gitleaks with Homebrew. Docker images are also published, and you can build from source if you have Go installed. Prebuilt binaries for many platforms are listed on the project's releases page.

  • Homebrew (macOS): use the command below
  • Docker: pull the zricethezav/gitleaks image or the ghcr.io/gitleaks/gitleaks image
  • From source: make sure go is installed, then clone the repository and run make build
brew install gitleaks docker pull zricethezav/gitleaks:latest git clone https://github.com/gitleaks/gitleaks.git cd gitleaks make build

Scan a git repository and its commit history

The git command scans local git repositories. Under the hood it uses git log -p to scan patches, so secrets that were committed and later deleted can still be found. If you pass no path, gitleaks scans the current working directory as a git repo.

You can narrow the range of commits with the log-opts option, which is passed to git log. The git log documentation describes the available options.

  • Use -v for verbose output that shows each finding
  • Use --log-opts to limit the commits scanned, for example a range such as commitA..commitB
gitleaks git -v --log-opts="--all commitA..commitB" path_to_repo

Scan directories and files

The dir command scans plain directories and files, which is useful when code is not in a git repository or when you want to check a working tree. The command also accepts the aliases files and directory. If no target is given, gitleaks scans the current working directory.

  • Pass a directory or a single file as the positional argument
gitleaks dir -v path_to_directory_or_file

Scan text piped through stdin

The stdin command reads data from standard input, so you can check any text stream, such as the contents of a file you pipe in. This is handy for checking output from other tools or text that is not stored in a repository.

cat some_file | gitleaks -v stdin

Add gitleaks as a pre-commit hook

Gitleaks can run as a pre-commit hook so that a commit containing a secret is blocked. Install pre-commit first, then create a .pre-commit-config.yaml file at the root of your repository. Run pre-commit autoupdate to move to the latest listed version, then pre-commit install to activate the hook.

If you need to bypass the check for one commit, the README says you can prepend SKIP=gitleaks to the commit command.

  • Install pre-commit from pre-commit.com
  • Create .pre-commit-config.yaml at the repository root
  • Run pre-commit autoupdate, then pre-commit install
repos: - repo: https://github.com/gitleaks/gitleaks rev: v8.24.2 hooks: - id: gitleaks SKIP=gitleaks git commit -m "skip gitleaks check"

Control results with flags and a baseline

Gitleaks has flags for choosing rules, setting the exit code, writing reports and redacting output. Its config is read in a fixed order: the --config flag, then the GITLEAKS_CONFIG environment variable, then GITLEAKS_CONFIG_TOML, then a .gitleaks.toml file in the target path. If none is found, the default config is used. Use -b or --baseline-path to ignore issues recorded in a baseline file when scanning large repositories with long histories.

For reports, the README lists json, csv, junit, sarif and template formats. The --exit-code flag sets the exit code when leaks are found, and it defaults to 1.

  • -c, --config: set a config file path
  • --enable-rule: only enable specific rule IDs
  • --report-format and --report-path: write a report file
  • --redact: hide secrets in logs and stdout
  • --exit-code: change the code returned when leaks are found
  • -i, --gitleaks-ignore-path: point to a .gitleaksignore file
gitleaks git -v -f sarif -r report.sarif path_to_repo

What people use it for

  • Blocking a commit locally when a developer accidentally stages an API key
  • Running a secret-scanning step in a CI pipeline on each push
  • Auditing the full commit history of an older repository for credentials that were committed and later removed
  • Checking text streams from other tools by piping them into the stdin command

Frequently asked questions

Is gitleaks free to use?

Gitleaks is released under the MIT licence, according to the project's repository listing. The licence allows you to use it under its terms; check the LICENSE file in the repository for the full text.

How do I install gitleaks?

On macOS, run brew install gitleaks. You can also pull the Docker image with docker pull zricethezav/gitleaks:latest, or clone the source and run make build if Go is installed. Binaries are also listed on the releases page.

What do I need to run gitleaks?

The README lists Homebrew on macOS, Docker, or Go for building from source as the ways to get it running. Docker or a Go toolchain are the alternatives if you are not on macOS with Homebrew.

Is gitleaks still being developed?

The README says the project is feature complete. The maintainer will not merge new features, and future releases will only be security patches. The maintainer has shifted focus to Betterleaks.

Does gitleaks have a graphical interface?

No. The README documents only command-line usage, with the git, dir and stdin commands and their flags.

How does gitleaks compare to TruffleHog, detect-secrets and git-secrets?

These are comparable projects in the same space of secret scanning. The source does not include a benchmark or accuracy comparison, so check each project's documentation against your own repositories before choosing one.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Gitleaks suits developers and teams who want a simple command-line scanner for git history, files and pre-commit or CI checks. It is a poor choice if you need new features, a graphical interface, or results with no false positives, since the project is feature complete and detection is regex-based.

Install options & downloads