"scripts": "env:init": "node -e \"const fs = require('fs'); if (!fs.existsSync('.env.local') && fs.existsSync('.env.dist.local')) fs.copyFileSync('.env.dist.local', '.env.local');\"" Use code with caution.
| File | Git | Purpose | Contains secrets? | |------|-----|---------|------------------| | .env.dist | ✅ committed | Shared default template | ❌ No | | .env.dist.local | ✅ committed (optional) | Machine‑specific defaults template | ❌ No | | .env | ❌ ignored | Actual runtime config (prod/dev) | ✅ Yes | | .env.local | ❌ ignored | Actual machine overrides | ✅ Yes |
Whenever you add a new .env variant to your project, you must explicitly define its relationship with your version control system (Git). What to Commit vs. What to Ignore Commit to Git? Description .env Public baseline defaults. .env.dist / .env.example Yes Global template with empty/dummy values. .env.dist.local No (Usually) Local template/fallback layer. .env.local No Active local secrets and overrides. Updating Your .gitignore
The file is a specialized configuration file used in modern software development to manage environment variables. While standard .env files are common, .env.dist.local specifically serves as a local template for team members, bridging the gap between shared configuration and machine-specific secrets. Core Purpose of .env.dist.local
Common contents and structure
: The distribution template. It contains the keys of all required variables but leaves the sensitive values blank. It acts as documentation and is tracked in Git. Where does .env.dist.local fit?
LOG_CHANNEL=stack LOG_LEVEL=debug
.env.dist.local solves this. It holds the pre-filled defaults for local development only and is committed to Git. Developers clone the repo, copy .env.dist.local to .env.local , and they are ready to run. 2. Disconnecting Production Defaults from Local Defaults
: A template file that defines the keys required by the application, usually populated with placeholder values ( DATABASE_URL=mysql://user:pass@127.0.0.1/db ). (Committed to Git). Where Does .env.dist.local Fit In? .env.dist.local
: The final, private file that contains actual secrets (passwords, private keys). This file is never committed to version control. Why use .env.dist.local ?
.env⟶.env.dist⟶.env.dist.local⟶.env.local.env ⟶ .env.dist ⟶ .env.dist.local ⟶ .env.local
: It allows for overrides that apply only to a specific machine while still following the structure of the distribution file. Version Control Safety : Like other files, it is typically added to .gitignore
Here are some best practices to keep in mind when working with .env.dist.local : "scripts": "env:init": "node -e \"const fs = require('fs');
If your team modifies the local Docker environment—such as changing a local Redis port from 6379 to 6380 —update the .env.dist.local file immediately. This ensures that the next time a teammate pulls the main branch, their template updates automatically. A Typical Setup Example
.env.dist.local is a simple text file that contains environment variables and their values. The .dist extension indicates that it's a distribution file, meant to be used as a template or a starting point. The .local extension suggests that it's specific to your local machine.
: Use this file to document variables that are unique to a developer's machine but necessary for the app to run (e.g., LOCAL_DB_PORT=5432 ).