Why .env.example Gets Out of Sync — and What Actually Fixes It

Description and use

The .env.example file drifts because it is manually maintained. The fix is to use a schema (env.schema.toml) as the single source of truth, generate .env.example from it, and enforce sync with EnvShield’s pre‑commit hook.

Problem

Environment variable example files drift out of sync with code, causing runtime failures and onboarding friction.

Outcome

Adopting a schema‑driven approach eliminates manual maintenance of .env.example, catches drift early via pre‑commit checks, and provides type‑safe validation against code and deployment manifests.

Workflow

• 1. Create or update env.schema.toml with variable definitions, types, defaults, and conditional requirements.
• 2. Run envshield schema sync to generate a fresh .env.example from the schema.
• 3. Commit the generated .env.example and the schema to version control.
• 4. Install the pre‑commit hook with envshield hook install to run envshield schema sync --check before each commit.
• 5. On pull requests, the hook ensures any changes to the schema are reflected in the example file, failing the commit if drift is detected.

Evidence

EnvShield takes the same schema-as-contract idea further in a different direction: the same schema also validates against a Docker Compose or Kubernetes manifest, a second service written in a different language, and the actual git history of what the contract used to require — not just a local .env file.

Source

Wire that into envshield hook install and it runs automatically before a commit lands — but only for a schema you actually staged, so it never blocks a commit that didn't touch configuration.

Source