Undo ignored Git files: discover and clean tracked files safely

For developers who take pride in keeping repositories clean, the moment you add .env to .gitignore feels like a job well done. Yet weeks later, that file might still appear in every clone and push—despite the ignore rule. The issue isn’t a bug; it’s a fundamental behavior of Git’s tracking system.

When a file is already committed, adding it to .gitignore prevents new instances from being tracked, but existing tracked files remain untouched. Secrets, logs, or large binaries committed before the ignore rule was added will continue to clutter the repository unless manually removed. A single command—git rm --cached—can fix this, but only if someone notices the lingering file in the first place.

That’s where gitslip comes in, a lightweight CLI tool designed to expose every tracked file that your ignore rules say should be gone. It delivers a clear, actionable report and can even automate the cleanup process.

npx gitslip

Running the command surfaces ignored but still-tracked files along with the specific ignore rule that should have excluded them. For example:

2 tracked files are ignored by your rules but still committed:
  config/secrets.env ↳ .gitignore:7 *.env
  logs/app.log ↳ .gitignore:2 *.log

The tool then provides the exact commands to stop tracking these files without deleting local copies:

git rm --cached -- config/secrets.env
git rm --cached -- logs/app.log

Alternatively, gitslip --apply executes the cleanup automatically, ensuring no ignored files slip through unseen.

Why rely on grep when Git can do the job?

A common impulse is to manually grep .gitignore patterns against git ls-files, but this approach falls short in several ways. A simple grep '\.env' can’t differentiate between a correctly excluded file and one that was committed before the rule existed. It also ignores complexities like negation rules (!), directory-specific patterns, nested .gitignore files, and global exclusion settings stored in .git/info/exclude or core.excludesFile.

Reimplementing Git’s ignore-matching logic risks subtle errors that could expose secrets or fail to catch critical files. Instead of reinventing the wheel, gitslip leverages Git’s own tools to ensure accuracy.

How gitslip uncovers hidden ignored files

The detection process relies on a single Git command that combines tracking and ignore status:

git ls-files -i -c --exclude-standard

Here, -c restricts results to tracked (cached) files, -i filters for ignored files, and --exclude-standard ensures Git considers all standard ignore sources. This combination yields a definitive list of files that are both tracked and ignored, with Git handling directory rules, nested ignores, and negations correctly.

Identifying the specific ignore rule that caught each file requires a bit more finesse. Git’s git check-ignore -v command appears to be the natural fit, but it short-circuits when a file is already tracked, returning "not ignored" and refusing to name the pattern.

To bypass this limitation, gitslip uses a clever workaround: running git check-ignore -v against an empty Git index. By setting GIT_INDEX_FILE to a non-existent path, Git treats the index as empty, effectively untracking all files. This forces check-ignore to evaluate files without the short-circuit and accurately report the matching rule for each path. The process is read-only, so no files are created or modified.

Easy installation and CI integration

Getting started with gitslip is effortless, with zero dependencies required. Choose the version that matches your preferred ecosystem:

# Node.js
npx gitslip

# Python
pip install gitslip

Both versions produce identical output, a detail verified through byte-for-byte comparisons in CI pipelines. The tool can also serve as a gate in automated workflows, exiting with a status code of 1 if any ignored files are detected, allowing pipelines to fail before committing unwanted files.

- name: Check for ignored tracked files
  run: npx gitslip

Take two minutes to run npx gitslip in your current project. If you’ve ever used git add -A before finalizing your .gitignore rules, the chances are high that overlooked files are still lurking in your repository. Whether it’s a forgotten secret, a massive binary, or a lingering .DS_Store from years past, uncovering these files now can prevent future headaches.