A CLI tool written in Go that filters directory contents using gitignore-style rules.
- Exclude files/directories matching patterns (gitignore format).
- Protect files/directories from exclusion (higher priority than exclude).
- Patterns from files, stdin or the command line; optionally the tree's own
.gitignorefiles. - Prints included files as relative paths, ready for
tar,rsync,ziporxargs -0. - Optionally copies the filtered tree to an output directory, preserving permissions and modification times.
- Check mode to fail CI when forbidden files are present.
- Explain mode showing which rule decided each path.
- Dry-run mode to preview what would happen.
Download the latest binary for your platform from the Releases page.
go install github.com/allen0099/blacklist@latestOr clone and build manually:
git clone https://github.com/allen0099/blacklist.git
cd blacklist
go build -o blacklist .docker pull ghcr.io/allen0099/blacklist:latestblacklist [flags] [directory]
If directory is omitted the current working directory is used.
| Flag | Short | Description |
|---|---|---|
--exclude <file> |
-e |
Path to a gitignore-format file with exclusion patterns, - for stdin. Repeatable. |
--protect <file> |
-p |
Path to a gitignore-format file with protection patterns, - for stdin. Repeatable. |
--exclude-pattern <p> |
-E |
Exclusion pattern given directly. Repeatable. |
--protect-pattern <p> |
-P |
Protection pattern given directly. Repeatable. |
--use-gitignore |
Also exclude what the tree's .gitignore files ignore, and .git. |
|
--output <dir> |
-o |
Copy included files to this directory (preserving structure, permissions and modification times). Must not be the source directory or one of its parents; an output directory inside the source is skipped. |
--preserve-symlinks |
With --output, recreate symlinks instead of skipping them. Links are never followed. |
|
--dry-run |
Show what would be done without writing any files. | |
--null |
-0 |
Separate printed paths with NUL instead of newline. |
--check |
Print excluded paths instead and exit 1 if there are any. | |
--explain |
Print every path with its verdict and the rule that decided it. | |
--verbose |
-v |
Enable debug output (env: BLACKLIST_VERBOSE). |
--quiet |
-q |
Suppress all output except errors (env: BLACKLIST_QUIET). |
--version |
Print the version. | |
--help |
-h |
Show help. |
--verbose and --quiet are mutually exclusive, as are --check and --output.
stdout lists the included files (not directories) relative to the
directory, one per line (NUL-separated with -0). Directories are left out so
that tar -T does not recurse into them and pull excluded files back in. Logs
go to stderr.
Changed in 0.2.0: earlier versions printed absolute paths and also listed directories.
Verbosity can be controlled without passing flags by setting environment variables. An explicit flag always takes precedence over an environment variable.
| Variable | Equivalent flag | Accepted values |
|---|---|---|
BLACKLIST_VERBOSE |
--verbose |
1, true, yes (case-insensitive) |
BLACKLIST_QUIET |
--quiet |
1, true, yes (case-insensitive) |
protect > exclude
When a file matches both an exclusion rule and a protection rule, the protection rule wins and the file is included.
Pattern files follow the gitignore specification:
# Comments start with '#'
# Exclude all log files
*.log
# Exclude the vendor directory and everything inside it
vendor/
# Exclude all .tmp files inside any build/ directory
build/**/*.tmpMatching follows git exactly (the test suite compares against git itself).
An excluded directory excludes everything inside it, and a protected directory
protects everything inside it. Note that ./app is not a valid pattern, in git
or here; write /app to anchor a pattern to the directory.
With --use-gitignore, each .gitignore applies to its own directory and a
deeper one takes precedence, as in git.
blacklist -e .gitignore ./srcblacklist -e exclude-logs.txt -e exclude-build.txt ./projectblacklist -e everything.txt -p keep-these.txt ./projectblacklist -e .gitignore -o ./dist ./srcblacklist --use-gitignore -e deploy-exclude.txt -0 . | tar --null -T - -czf deploy.tgzblacklist -E '*.log' -E 'node_modules/' -P 'logs/keep.log' .
printf '*.tmp\n' | blacklist -e - .blacklist --check -E .env -E '*.pem' -E 'node_modules/' .$ blacklist --explain -e exclude.txt -P keep.go .
include main.go
exclude vendor/ excluded by exclude.txt:2: vendor/
include vendor/keep.go excluded by exclude.txt:2: vendor/; protected by pattern: keep.goblacklist -e .gitignore -o ./dist --dry-run ./srcThe image's entrypoint is blacklist, so reset it for GitLab to run the
script. Pin a minor version: 0.x releases may change the output format.
package:
image:
name: ghcr.io/allen0099/blacklist:0.2
entrypoint: [""]
script:
- blacklist --check -E .env -E '*.pem' .
- blacklist --use-gitignore -e ci/exclude.txt -o deploy-root .
artifacts:
paths: [deploy-root/]- Go 1.27 or later
make(GNU Make or compatible)
make build # compile the binary
make test # run tests with race detector
make test-coverage # run tests and print per-function coverage
make fmt # format all Go files in-place (gofmt)
make fmt-check # fail if any files are not formatted (used in CI)
make vet # run go vet
make vuln # run govulncheck to scan for known vulnerabilities
make clean # remove build artifacts
make help # list all targets
make testmake test-coveragemake build
# or:
go build -o blacklist .Releases are managed by release-please.
Use Conventional Commits (feat:, fix:,
feat!: …); release-please keeps a release PR open with the next version and
changelog, and merging it tags the release, uploads the binaries and pushes the
Docker image.
Release binaries and Docker images carry build provenance attestations:
gh attestation verify blacklist-v0.2.0-linux-amd64 -R allen0099/blacklist
gh attestation verify oci://ghcr.io/allen0099/blacklist:0.2 -R allen0099/blacklist