Stop tracking an ignored file safely

How-to Last tested 27 October 2026

A .gitignore rule does not stop Git tracking a file already in the index. Remove that path from the index while keeping your working copy, commit the change deliberately, and warn other clone owners that their tracked copy can be removed when they pull.

Understand why the ignore rule did not work

Ignore rules select intentionally untracked paths; they do not retroactively untrack a file already in the index¹. That distinction explains why adding a rule can appear to have no effect on an already tracked file. Check the exact path and repository state first. A similarly named file elsewhere or a rule in a different directory may not be the one you intend to change.

Removing a path from the index is a version-controlled change. The cached option can keep the original working file while staging its removal from the repository². It does not remove the file from prior commits, erase copies already shared, or protect any secret that appeared in history. Treat the history and distribution of sensitive material as separate questions.

Warn other clones before the command

Warning: when another clean clone pulls the commit that removes a tracked file, its working copy of that file can be deleted. Arrange a safe copy and coordinate with affected users before applying the removal in shared history. Uncommitted changes or different local state can alter the outcome; the example demonstrates only a clean second clone.

The example creates a local bare remote and two fictional working copies. It tracks an example settings file and then clones that starting state. In the first copy, it adds an ignore rule and removes the file from the index with the cached option. An assertion confirms the first working copy still has the file before the change is committed and pushed to the local remote.

Read the second-copy result

The second copy pulls the resulting commit while clean. Its assertion verifies that the formerly tracked file is absent, while the original first copy still has its local file. This difference is the point of the test. The first command’s local preservation is not a promise that a different clone retains the file after it incorporates the removal.

The test uses a local path for the bare remote; it does not contact an external service. A real team may have modified files, pending merges or other deployment steps that require different handling. Before sharing a removal, identify who relies on the tracked file and provide a safe transition. If the file contains credentials, rotating or otherwise addressing them is a separate process from adding an ignore pattern.

Choose the scope of the rule

A repository ignore file is a shared instruction for matching untracked paths. A personal exclude file can instead cover local-only patterns, but choosing a location does not change the treatment of an already tracked path. Make the rule as narrow as the actual need, and consider whether other contributors should share it. The example uses one explicit filename rather than a broad pattern.

Inspect the staged change before committing. It should show the intended ignore rule and the intended removal, not unrelated files. If the working copy contains important local changes, save them before proceeding even though the cached operation is designed to leave that copy in place. The command can refuse an unsafe state; do not add a force option simply to suppress a warning without understanding it.

Do not confuse untracking with deletion from history

The new commit records that the file is no longer tracked from that point. Earlier commits can still contain the file, and other copies can retain it. Removing a file from the current index is therefore not a method for making already published data disappear. Assess existing copies and history separately before making claims about exposure or retention.

The companion staged and working differences guide helps separate the index change from a working file that remains on disk. These checks answer what is staged and what is present locally; neither alone establishes what other clones, backups or remote repositories contain.

Make the handoff explicit

The test uses a clean peer so the pull has a predictable result. A real collaborator can have a local edit or a staged version of the same file, and those states require separate inspection. Tell people which exact path is being removed from tracking, what local copy they need to retain and when the change will be shared. The example does not attempt to automate that coordination or decide whether a file should be ignored for a particular project.

Keep the replacement procedure separate from the Git command itself. A template or documented setup can help another person restore a local configuration, but it should not be inferred from the existence of an ignore rule. The rule only affects later handling of matching untracked files; it does not create a replacement file or establish that another copy is safe.

Run the complete local example

Before running: use an empty directory. This script creates example-work, including a fictional working repository and a local bare remote; it stops if that directory already exists. The script commits a file removal and the clean second clone loses its copy; never substitute a real repository. Review the commands first and do not point it at a real project.

Download the complete MIT-licensed example and run it with Git 2.56.0. The printed script is the tested file. The two recorded runs used fresh directories and produced the same output; the remote in this example is a local directory.

#!/bin/sh
# SPDX-License-Identifier: MIT
set -eu
export TZ=UTC LC_ALL=C
export GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null
export GIT_AUTHOR_NAME='Example Author' GIT_AUTHOR_EMAIL='author@example.invalid'
export GIT_COMMITTER_NAME='Example Author' GIT_COMMITTER_EMAIL='author@example.invalid'
export GIT_AUTHOR_DATE='2026-10-27T12:00:00+00:00'
export GIT_COMMITTER_DATE='2026-10-27T12:00:00+00:00'
test "$(git --version)" = 'git version 2.56.0'
mkdir example-work
cd example-work
git init --bare -q --template= --initial-branch=main remote.git
git init -q --template= --initial-branch=main project
cd project
git config commit.gpgsign false
git config core.autocrlf false
git remote add origin ../remote.git
printf 'example settings\n' > settings.local
git add settings.local
git commit -qm 'Track example settings'
git push -q -u origin main
cd ..
git clone -q --template= --branch main remote.git peer
cd project
printf 'settings.local\n' > .gitignore
git add .gitignore
git rm --cached -- settings.local
test -f settings.local
git commit -qm 'Stop tracking settings'
git push -q origin main
git -C ../peer pull -q --ff-only
test ! -e ../peer/settings.local
test -f settings.local
printf 'Original working file remains; peer file removed on pull\n'

Both runs produced:

rm 'settings.local'
Original working file remains; peer file removed on pull

The script leaves example-work in the directory where it ran, including the local repositories and their data. After inspecting the result, remove that example directory when it is no longer needed. Do not remove a directory with the same name in a real project unless you have verified its contents and decided it is safe to delete.

Not covered on this page

• Removal of sensitive material from prior commits or copies.
• Conflict handling for a modified second clone.
• Credential rotation or a guarantee of data deletion.