Quick answer
.env.example goes out of sync because it's a plain text file with no way to enforce that it matches your code — nothing runs when a variable is added, removed, or made conditional. The fix isn't a better example file; it's a schema: a single, versioned file that declares what your configuration is actually supposed to be, which a tool then generates the example file from and validates everything else against. In EnvShield, that schema is env.schema.toml — envshield schema sync generates .env.example from it, and envshield schema sync --check fails the moment the two drift, typically wired into a pre-commit hook so it's caught before the commit lands, not after a teammate hits it.
The problem
Open almost any repo's .env.example and you'll find the same story: it was accurate the day someone wrote it, and it's been quietly drifting ever since. A teammate adds STRIPE_WEBHOOK_SECRET to the payment service, the PR gets reviewed for logic, and nobody thinks to update the template — why would they? It's not code. Six weeks later someone clones the repo, copies .env.example to .env, runs the app, and it crashes on a variable the file never mentioned.
Search for this problem and you'll find a lot of people asking variations of the same three questions: how do I keep .env and .env.example in sync, why does .env.example keep missing environment variables, and is there a better way to do environment variable documentation than a hand-maintained text file. This article is about why the file drifts in the first place, and what actually stops it — not just what to rename it.
