Why .gitignore does not ignore a tracked file

You added a filename to .gitignore, saved the file, and Git still reports changes to it. The first question is whether Git already tracks that path. Ignore rules are intended for untracked files; they do not remove an existing file from the index. The gitignore reference explains that distinction.

This example uses settings.local.json in a repository that already has a commit. Save open editor buffers and keep a backup of any valuable local settings before changing tracking. Check the repository root and use your actual filename in each command.

1. Check whether the file is tracked

git status --short
git ls-files --error-unmatch -- settings.local.json

If the second command prints settings.local.json, the path is in the index. If it exits with an error, check the spelling and repository location; the file may already be untracked. The git ls-files documentation defines this index check. Do not assume that every file visible in your editor is tracked.

2. Check the ignore rule separately

For a file at the repository root, add this line to the root .gitignore:

/settings.local.json

Then inspect the matching rule:

git check-ignore -v --no-index -- settings.local.json

The verbose output identifies the ignore file, line number and matching pattern. The --no-index option lets this diagnostic examine a path even when it is tracked. Without it, tracked paths are normally omitted. See git check-ignore.

3. Remove only that path from tracking

First preview the operation, then perform it if the path is correct:

git rm -n --cached -- settings.local.json
git rm --cached -- settings.local.json

The first command is a dry run. The second removes the path from the index while leaving the working file on disk. Keep --cached in the command. If Git refuses because the staged content differs, inspect those versions rather than adding --force. The git rm reference covers the option and its checks.

4. Review the staged change before committing

git add -- .gitignore
git status --short
git diff --cached --stat

A staged deletion for settings.local.json is expected: the next commit will omit that path. Confirm the local file still opens and contains the settings you need. Review the complete staged changes before making your normal commit.

In the isolated verification for this example, the local file stayed byte-for-byte unchanged after cached removal and after the commit. An older commit still contained it. A clean collaborator clone lost the tracked file when it pulled the removal commit. Discuss that effect with your team if everyone needs a local configuration file; a separate example configuration can document the required fields.

If you only meant to unstage an edit

Stopping tracking changes future commits. If the file should remain tracked and you only want to remove an edit from the next commit, follow the guide to unstaging a file without losing its current edits instead. Choose the operation based on what the next commit should contain.