Introduction

If you want Git to stop tracking a file but still keep that file on your machine, use git rm --cached. The --cached flag removes the path from the Git index only, so the next commit deletes it from the repository while leaving your working copy untouched.

Use git rm --cached

Git tracks files through the index. A normal git rm path/to/file removes the file from both the index and the working tree. Adding --cached changes that behavior so only the tracked entry is removed.

git rm --cached config/local.env
echo "config/local.env" >> .gitignore
git commit -m "Stop tracking local.env"

After that commit, the repository no longer tracks the file, but the file still exists on disk in your local clone. Adding the path to .gitignore is usually the second required step, because otherwise Git will immediately show the file again as untracked.

This workflow is useful for local configuration, machine-specific secrets, generated files, IDE settings, or anything else that was committed once but should not stay under version control.

Removing a Directory but Keeping It Locally

The same idea works for directories. Use the recursive flag when the tracked path contains multiple files:

git rm -r --cached .idea
echo ".idea/" >> .gitignore
git commit -m "Stop tracking IDE files"

That pattern is common for editor metadata, local cache folders, and build output that should remain on a developer machine but not in the shared repository.

What Happens to Repository History

git rm --cached only changes the current state of the branch. It does not erase the file from earlier commits. If someone checks out an older commit, the file can still be present there.

That distinction matters a lot when the file contains sensitive data. If an API key, password, private certificate, or token was committed, removing it from the current branch is not enough. You should rotate the secret and then decide whether the repository history also needs to be rewritten.

A good mental model is:

• 'git rm --cached stops future tracking'
• history cleanup handles old commits

Those are related tasks, but they are not the same operation.

Verifying the Result

Before you commit, check both Git and the filesystem:

git status
ls config/local.env

git status should show the file as deleted from version control. The ls command confirms that the local file still exists.

After the commit, run git status again. If the file keeps appearing as untracked, your ignore rule is missing or does not match the correct path.

Shared Ignore Rules Versus Local Ignore Rules

Sometimes the ignore pattern should be shared with the whole team. In that case, put it in .gitignore. Other times the rule is personal and should stay only in your clone. Then .git/info/exclude is the better choice.

git rm --cached notes/private.txt
echo "notes/private.txt" >> .git/info/exclude
git commit -m "Stop tracking private notes"

Use .gitignore for files that everyone should ignore. Use .git/info/exclude for personal scratch files that only matter on your machine.

Common Pitfalls

The most common mistake is forgetting --cached. Without it, Git deletes the working copy as well as the tracked entry.

Another issue is removing the file from the index but forgetting to add an ignore rule. The file stays local, but Git continues to show it as untracked after every status check.

Developers also assume this command removes the file from history. It does not. If secrets were committed, handle secret rotation and possibly history cleanup separately.

Summary

• Use git rm --cached to stop tracking a file while keeping it locally.
• Add the path to .gitignore or .git/info/exclude so it does not keep reappearing in status output.
• Use git rm -r --cached when the tracked path is a directory.
• The command affects future commits only and does not erase older history.
• If the file contained secrets, rotate them and evaluate whether the repository history must also be cleaned.