Gitignore Not Working? Check Tracked Files Before git rm --cached

Separate tracking from rule matching#

Run these commands from the repository root, replacing local.env with the actual relative path:

1
git ls-files -- local.env
2
git check-ignore -v -- local.env
3
git check-ignore -v --no-index -- local.env

The commands answer different questions. Git’s ignore reference limits ignore rules to untracked files. The check-ignore manual explains that the default check skips tracked files, while --no-index bypasses index membership for the check.

With a tracked local.env and the rule /local.env, the first command prints the path, the second prints nothing, and the third identifies the rule:

1
.gitignore:1:/local.env    local.env

The gap is diagnostic: the pattern matches, but the file is tracked. Rewriting the same pattern will not change that state.

A verbose match alone is not proof of exclusion: negated patterns begin with !. To find other tracked paths that match ignore rules, use the read-only inventory documented by git ls-files:

1
git ls-files -ci --exclude-standard

Review that list as candidates. Do not pipe it directly into a removal command.

Remove one path from the index#

First inspect git status --short and preserve any unrelated staged work. Add an appropriate rule to the root .gitignore; for this example it is:

1
/local.env

Preview the exact removal, apply it, and inspect the staged result:

1
git rm -n --cached -- local.env
2
git rm --cached -- local.env
3
git add -- .gitignore
4
git diff --cached --name-status
5
git diff --cached -- .gitignore

The staged name summary for the example is:

1
A       .gitignore
2
D       local.env

An existing .gitignore would show M instead of A. The D records removal from the next committed tree; it does not mean the local working file was erased. According to the git rm manual, --cached leaves working files alone and -n previews the operation.

If the command refuses because the staged file differs from both HEAD and the working file, inspect git diff --cached -- local.env and git diff -- local.env. Resolve which content to retain before retrying; do not automatically add -f.

Before committing, confirm that the entire staged diff contains only the intended ignore-rule change and file removal. If unrelated work is staged, finish or separate that work first. Then commit the reviewed index:

1
git commit -m "Stop tracking local configuration"
2
git show --name-status --format= HEAD

The commit should include the D entry for local.env. Do not replace this with git commit --only -- .gitignore local.env: in an additional fixture on the same Git version, that command committed only the new ignore file and put the still-existing local.env back into the index. The removal was lost. The git commit reference explains that explicit paths select their working-tree contents rather than the already staged changes.

There is no need to rebuild the whole index or stage the entire repository for a one-file correction.

Verify the result in this working copy#

After the commit:

1
git ls-files -- local.env
2
git check-ignore -v -- local.env
3
git status --short --ignored -- local.env
4
test -f local.env && printf 'local file retained\n'

For the fixture below, ls-files prints nothing, check-ignore identifies /local.env, status prints !! local.env, and the last command confirms the local file remains. These checks establish three separate facts: untracked, ignored, and present on disk.

Ignoring a file in Git does not exclude it from a Docker build context. If the same configuration file must stay out of an image, inspect .dockerignore separately; the Docker build-context guide explains that boundary.

Reproduce what a teammate receives#

The following disposable two-clone fixture was executed during article verification on October 2, 2026, with git version 2.54.0 (Apple Git-157) on macOS. It uses dummy configuration, a local clone, and a clean teammate working tree. It does not test merge conflicts or locally modified teammate files.

Run it in Bash. Keep it separate from your project:

1
fixture_dir="$(mktemp -d)"
2
git init -q -b main "$fixture_dir/author"
3
cd "$fixture_dir/author"
4
git config user.name Fixture
5
git config user.email [email protected]
6

7
printf 'MODE=demo\n' > local.env
8
git add -- local.env
9
git commit -qm "Track fixture"
10
git clone -q . "$fixture_dir/teammate"
11

12
printf '/local.env\n' > .gitignore
13
printf 'MODE=changed\n' > local.env
14
git check-ignore -v --no-index -- local.env
15
git rm --cached -- local.env
16
git add -- .gitignore
17
git commit -qm "Stop tracking local config"
18

19
test -f local.env && printf 'author: present\n'
20
git -C "$fixture_dir/teammate" pull --ff-only
21
if test -f "$fixture_dir/teammate/local.env"; then
22
  printf 'teammate: present\n'
23
else
24
  printf 'teammate: absent\n'
25
fi
26
git show HEAD~1:local.env

The significant observed results were:

1
author: present
2
...
3
 delete mode 100644 local.env
4
teammate: absent
5
MODE=demo

--cached preserved the author’s working file, but the commit contained a deletion. The clean teammate clone applied that deletion on its fast-forward pull. The final command also retrieved the original contents from the earlier commit: stopping tracking did not erase history.

Before sharing this change, have collaborators preserve needed local configuration outside the repository and provide a tracked template with dummy values. They can recreate their ignored local file after updating. Do not treat this clean-clone result as a prediction for every dirty working tree; local edits can affect whether an update proceeds.

If the committed file contained real credentials, follow GitHub’s sensitive-data guidance: revoke or rotate the secret first, then evaluate history cleanup separately. A successful ignore check only proves the current exclusion rule, not removal from old commits or other copies.

References:

• Git ignore rules
• git check-ignore
• git rm
• git ls-files
• git commit
• GitHub: removing sensitive data