.env.dist.local May 2026

Some developers (regrettably) commit their actual .env file to Git. Now, production credentials leak, local paths clash, and every pull request creates a nightmare of merge conflicts.

JWT_SECRET=local_jwt_secret_do_not_use_in_production

In your CI (GitHub Actions, GitLab CI, Jenkins), you don't want .env.dist.local to be used because CI should mimic production.

Thus, your CI script should explicitly not copy .env.dist.local. Instead, it might copy .env.dist (production-like) or inject secrets directly.

Example .gitlab-ci.yml:

variables:
  APP_ENV: test
before_script:

This ensures that APP_DEBUG=true from .env.dist.local never leaks into your test suite.
Add these lines to your .gitignore:
### Local environment overrides
.env.local
.env.*.local
!.env.dist.local          # <-- IMPORTANT: whitelist the distribution file

This ensures that .env.dist.local is tracked, but actual local overrides are NOT. .env.dist.local
.env.dist.local (committed to repo):
# Local overrides template – copy to .env.local
DATABASE_URL=mysql://app:devpass@127.0.0.1:3306/app_local
TRUSTED_PROXES=127.0.0.1
DEV_TOOLS_ENABLED=1

.env.local (gitignored, created by each dev from the above):
# Real local machine config
DATABASE_URL=mysql://app:mysecret@host.docker.internal:3306/myapp_john
DEV_TOOLS_ENABLED=0   # Turn off heavy tools on laptop


Cause: Multiple developers adding new variables simultaneously.
Solution: Treat .env.dist.local like any source file — resolve conflicts manually. Or adopt a tool like dotenv-linter + alphabetical sorting. Some developers (regrettably) commit their actual
cp .env.dist .env   # for production-like defaults (optional)

Better yet, automate this in a setup script (e.g., bin/setup):

#!/usr/bin/env bash
if [[ ! -f ".env.local" ]]; then
    if [[ -f ".env.dist.local" ]]; then
        cp .env.dist.local .env.local
        echo "✅ Created .env.local from .env.dist.local"
    else
        echo "⚠️  No .env.dist.local found. Skipping."
    fi
fi