guide5 min readBy Aliniyaz Mamat · updated

Hide .env from git (and recover if committed)

To hide your .env file from git, add .env* and !.env.example to .gitignore before the first commit. If a .env was already committed, untracking it isn't enough: rotate every secret in it, then remove it from history. This guide covers both, step by step.

Key takeaways

  • ✓Two lines in .gitignore cover every env file: .env* and !.env.example.
  • ✓.gitignore does nothing for files git already tracks: run git rm --cached .env.
  • ✓A pushed secret is leaked. Rotate it first; cleaning history comes second.
  • ✓git filter-repo --path .env --invert-paths removes the file from every commit; everyone has to re-clone afterwards.
  • ✓Automate: a gitleaks pre-commit hook plus GitHub push protection stop the next leak before it leaves your machine.

Step 1: ignore env files correctly

.gitignore
# all env files (.env, .env.local, .env.production, …)
.env*
# …except the template, which is safe to commit
!.env.example

The ! line re-includes the template. Verify that git really ignores your file and see which rule matched:

git check-ignore -v .env.local
# .gitignore:2:.env*    .env.local

git ls-files | grep -i '\.env'
# should print only .env.example

Most project generators (create-next-app, Vite, Rails, Laravel) already ignore some env files, but the patterns differ (.env*.local vs .env). Check rather than assume.

Step 2: untrack a .env that git already tracks

git rm --cached .env        # stop tracking, keep the local file
git commit -m "Stop tracking .env"
git push

This stops future commits. Every earlier commit still contains the file, and anyone with the repository can run git show <old-commit>:.env. If it held real secrets, continue with step 4.

Step 3: commit a .env.example instead

.env.example
# Database (local: docker compose up db)
DATABASE_URL=postgres://app:app@localhost:5432/app
# Stripe test mode: Dashboard > Developers > API keys
STRIPE_SECRET_KEY=sk_test_
JWT_SECRET=

New developers run cp .env.example .env and fill in the blanks. Create the template from your real file in one paste with the .env.example generator; it strips values and keeps comments.

Step 4: you already pushed secrets

4a. Rotate every secret in the file, now

CredentialWhere to rotate
AWS access keysIAM → Users → Security credentials → deactivate + create new
StripeDashboard → Developers → API keys → Roll key
GitHub tokensSettings → Developer settings → Tokens → revoke + regenerate
OpenAI / Anthropicprovider console → API keys → revoke + create
Database passwordALTER USER app WITH PASSWORD '…', then update the host
JWT / session secretsgenerate new, redeploy (users get logged out)

Paste the leaked file into the ENV leak checker first: it recognises 23 credential formats, so nothing gets overlooked. New values come from the secret generator.

4b. Remove the file from history

# filter-repo works on a fresh clone (it refuses otherwise)
git clone --mirror git@github.com:acme/app.git && cd app.git
git filter-repo --path .env --invert-paths
git push --force --mirror

Afterwards, collaborators must re-clone; old clones would push the file back. On GitHub, cached views, pull-request refs and forks can still contain the old commits. GitHub Support can purge them, which is one more reason rotation comes first.

4c. Check what the key was used for

Review usage logs for the time between the leak and the rotation: AWS CloudTrail, Stripe event logs, GitHub's security log, database connection logs. Unknown IPs or new resources mean it's an incident, not a cleanup.

Step 5: stop the next leak automatically

.pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks
  • Run pre-commit install once per clone; commits containing known secret patterns are then blocked.
  • Turn on GitHub push protection (Settings → Code security): GitHub rejects pushes with recognised secrets.
  • Scan full history in CI with gitleaks or trufflehog; pre-commit hooks can be skipped with --no-verify.

Checklist

  • .env* and !.env.example in .gitignore
  • git ls-files | grep -i .env shows only the template
  • .env.example committed and up to date
  • gitleaks pre-commit hook and GitHub push protection on
  • Production values set in the host, not in files
  • Any leaked secret rotated, history cleaned, logs reviewed

The rest of the rules for working with env files are in .env best practices.

Frequently asked questions

I already committed my .env. Is deleting it enough?

No. The file stays in every earlier commit. Rotate the secrets in it, then remove it from history with git filter-repo and force-push.

Does .gitignore work retroactively?

No. It only affects untracked files. Run git rm --cached .env to untrack a file git already knows about.

Can I commit .env.example?

Yes, you should. It documents every key without secret values. Local-only defaults like a localhost database URL are fine in it.

Is a private repository safe enough for .env files?

No. Everyone with access, every CI integration and every future collaborator can read the history, and repositories do get made public by mistake. Keep secrets out of git regardless of visibility.

git filter-repo or BFG?

git filter-repo is the tool the Git project recommends; BFG still works and is simpler for deleting a single file. Both rewrite history and need a force-push.

Related tools

Continue reading