A developer looking at terminal code on a laptop screen

Photo by Daniil Komov on Pexels

You added a .env file to your .gitignore, but Git still tracks changes to it. Every time you update a local database password or an API key, the file shows up in git status as a modified file ready to be committed.

Here is the exact scenario. You create a project, write your code, and generate a .env file with secrets:

bash
echo "DATABASE_URL=postgres://user:supersecret@localhost:5432/dev" > .env
git add .env
git commit -m "Initial commit with config"

Later, you realize that secrets do not belong in version control. You add .env to your .gitignore file:

bash
echo ".env" >> .gitignore
git add .gitignore
git commit -m "Ignore env files"

Then you edit .env to rotate a key:

bash
echo "DATABASE_URL=postgres://user:newsecret@localhost:5432/dev" > .env

You run git status, expecting Git to ignore the change. Instead, you see this:

text
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   .env

no changes added to commit (use "git add" to score)

Adding a pattern to .gitignore only tells Git to ignore untracked files. It does not stop Git from tracking files that are already inside its index. Since .env was committed once before, Git continues to watch it for changes, ignoring your ignore rule completely.

The fix

You must remove the file from Git’s index without deleting the local file from your disk. Git provides the --cached flag for this exact purpose.

Run this command from the root of your repository:

bash
git rm --cached .env

Your terminal will print:

text
rm '.env'

Do not worry. The file is still on your file system. You can verify this by checking the directory contents:

bash
ls -la .env

Now check your Git status:

bash
git status

The output changes:

text
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	deleted:    .env

Git stages the removal of .env from tracking. Because the file name is already inside .gitignore, Git does not flag it as an untracked file either. Commit this change:

bash
git commit -m "Stop tracking .env without deleting local file"

From this point forward, local changes to .env will no longer show up in git status.

Why this works

Git manages files in three areas: the working directory (your actual files on disk), the index or staging area (the snapshot Git prepares for the next commit), and the commit history (the permanent object database).

A standard git rm .env command deletes the file from both your working directory and the staging area.

Adding the --cached flag restricts the deletion to the index alone. It tells Git to drop the file from the manifest of tracked paths. The physical file on your hard drive remains untouched. Because Git no longer lists .env in its index, the rules in .gitignore finally apply to it.

The gotcha: Pulling this change on another machine

This fix works cleanly on your local machine, but it creates a trap for team members or deployment servers when they pull your commit.

When another clone of the repository pulls the commit where you removed .env from tracking, Git tries to apply that deletion to its own working tree. If that machine has its own .env file, Git might delete it during git pull or throw a checkout conflict:

text
error: The following untracked working tree files would be overwritten by merge:
	.env
Please move or remove them before you merge.
Aborting

To prevent data loss or broken deployment pipelines, follow a standard procedure.

First, create a template file called .env.example that contains all the required variable keys with empty or fake values:

bash
echo "DATABASE_URL=postgres://user:password@localhost:5432/dbname" > .env.example
git add .env.example
git commit -m "Add env template"

Second, if you run this on a server or a teammate’s machine where git pull complains about the untracked .env file, back it up before merging:

bash
cp .env .env.backup
git pull origin main
mv .env.backup .env

Once the repository reaches a state where .env is absent from tracking on all ends, you will not have to repeat this operation.


Published by the Old Lane Developer Desk. This article was drafted with AI assistance.

ADVERTISEMENT

More in Bash