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

Описание и применение

Файл .env.example быстро устаревает, так как его обновление вручную не гарантирует синхронизацию с кодом. Решение – использовать env.schema.toml как единственный источник правды, генерировать .env.example из него и проверять синхронизацию через EnvShield, интегрированный в pre‑commit.

Задача

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

Результат

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.

Рабочий процесс

• 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.

Доказательства

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.

Источник

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.

Источник