Git Still Tracks the File You Put in .gitignore

A matching ignore rule doesn't remove a file from Git's index. Diagnose tracking and rule matching separately, then plan a narrow change that preserves local work.

Share
An orange document remains clipped to an archive tray beside a separate filter, illustrating tracked membership versus ignore rules.

You add a local config file to .gitignore, save it, and Git immediately offers to commit its next change. The rule looks right. The path looks right. At this point, adding another slash starts to feel like a debugging strategy.

Check whether the file is already tracked. .gitignore keeps matching untracked files out of ordinary add operations; it doesn't remove existing entries from Git's index. If the repository should stop carrying that file, remove that one path from the index with git rm --cached, keep an ignore rule for it, and review the resulting staged deletion. If the file should remain a shared default, split the local overrides into another file instead.

This is an AI-prepared, documentation-based explainer, not a personally reproduced incident. The paths and commands below form an illustrative walkthrough and have not been executed for this article. See the editorial policy.

A matching rule and a tracked file can coexist

Imagine the repository already contains config/local.json. You add this line to the repository-root .gitignore:

/config/local.json

That pattern identifies the intended path. But Git has already put the file on the guest list. The sign outside the door doesn't eject someone sitting at the table.

The gitignore manual makes this distinction explicit: existing tracked paths aren't affected by ignore rules. The index is the staging area that records the content proposed for the next commit. A file can still exist on disk, be listed in the index, and match a rule that would exclude it if it were untracked.

Those are separate facts. Treating them as one question is why the usual “try a different pattern” loop goes nowhere.

Ask Git two questions

Run these illustrative commands from the repository root, substituting your actual path:

# Is this path in the index?
git ls-files --cached -- config/local.json

# Which rule matches, even if the path is already tracked?
git check-ignore -v --no-index -- config/local.json

git ls-files --cached lists tracked paths. If it prints the config path, you have evidence of index membership. Don't use its ordinary successful exit alone as proof that this specific path was found; inspect the listing.

git check-ignore normally leaves tracked files out of its results. The --no-index option lets you inspect the ignore rules independently of that membership. It doesn't change the index or untrack anything.

The verbose result identifies the source file, line number, pattern and path. Read the pattern too: a matching pattern beginning with ! is a negation, meaning the path is being included rather than ignored. A printed line isn't automatically proof of exclusion.

Index listingRule resultUseful next step
Path appearsPositive ignore pattern matchesDecide whether the repository should stop tracking the path.
Path appearsNo exclusion, or a negation winsBoth tracking and rule behavior need attention.
Path absentNo exclusion, or a negation winsDebug the pattern's location, precedence and parent directories.
Path absentPositive ignore pattern matchesThe path is untracked and excluded; inspect any separate staged deletion before concluding the change is finished.

For a pattern problem, the location of the ignore file matters. A slash-anchored rule is relative to that ignore file's directory. Later rules and rules in more specific directories can change the result. Git also can't re-include a file inside a directory it has already excluded without fixing the parent exclusion. The verbose rule trace is more useful here than a growing collection of experimental asterisks.

Remove one index entry, deliberately

First decide what the file represents. A generated artifact or machine-local configuration usually shouldn't be shared as live content. A required project default often should. Untracking the latter without a replacement can turn your tidy Git status into someone else's broken checkout.

For the machine-local case, preserve any local contents you need outside the worktree before the change, and check both unstaged and staged changes:

git status --short
git diff -- config/local.json
git diff --cached -- config/local.json

Keep the root ignore rule shown earlier, then remove only this path from the index:

git rm --cached -- config/local.json
git add -- .gitignore
git diff --cached -- .gitignore config/local.json

The git rm documentation distinguishes --cached from a normal removal: it leaves the working-tree file alone while removing its index entry. The staged deletion is therefore expected. It says the next snapshot will stop containing the file, not that your current local copy was deleted.

If Git refuses because the staged content doesn't match the required state, stop and inspect the two diffs. Don't immediately add -f. The index may contain a version that differs from both the last commit and the file on disk; that is information worth preserving.

Review the entire staged diff before committing so unrelated staged work doesn't hitch a ride. If the application needs a starter config, prepare a separate, safe template such as config/local.example.json with defaults or placeholders and stage that intentionally. Don't populate a tracked example by blindly copying private local settings.

Your disk and everyone else's next checkout are different promises

--cached preserves the local file in the worktree where you run that command. It doesn't attach a “please preserve this everywhere” instruction to the commit.

The commit records a deletion. When another clone updates to that snapshot, a clean tracked copy can be removed as Git applies the change. Local modifications can cause an update to refuse or require resolution; neither behavior is a backup policy. Tell collaborators to preserve their local configuration before taking the change, and provide the template or setup step they need afterward.

If the actual requirement is “keep a common config in Git, but let each developer override it,” an ignored override file plus a tracked default is the clearer design. Git's update-index notes specifically caution against treating assume-unchanged or skip-worktree as a general way to ignore changes to tracked files. Those bits aren't a portable team configuration system.

Verify the boundary you intended to change

After the intended change is committed, check the three facts separately:

# The local file is still present where you performed --cached.
test -f config/local.json

# The path should no longer appear in the index listing.
git ls-files --cached -- config/local.json

# The intended positive ignore rule should match it.
git check-ignore -v -- config/local.json

These are suggested checks, not recorded results. Also inspect a fresh disposable checkout when changing the team's setup path: the ignored local file won't come from Git, so the documented template-copy or generation step needs to supply it.

Untracking doesn't erase earlier commits. If the file carried a credential, an ignore rule and a new deletion commit don't make that credential private again. Handle the exposed credential and any history cleanup as a separate incident.

For related Git diagnosis, see why a reverted merge doesn't bring its changes back on the next merge, or browse Debugly's Git articles. Prepared for Rohit Bhadani's Debugly publication; about Debugly.

In the next config review, ask two questions before touching a pattern: should this path belong to the repository, and where should each machine's private values live? Once those answers are explicit, .gitignore can do its small, useful job.