The .env.dist.local file is a configuration template used to manage machine-specific environment variables that should be shared across a team but contain placeholders for local values. The Feature: Shared Local Templates
This file bridges the gap between general project settings and individual developer needs.
Template for Local Overrides: It provides a structured list of variables that only apply to the local development environment (e.g., local database ports, Docker settings). .env.dist.local
Version Control Safe: Unlike .env.local, which contains sensitive secrets and is ignored by Git, .env.dist.local is committed to the repository.
Standardization: It ensures every team member knows exactly which local variables they need to define to get the app running on their specific machine. Developers on macOS, Windows, or Linux may need
Bootstrap Workflow: Developers use it as a starting point by running a command like cp .env.dist.local .env.local to create their private config file. How it differs from other .env files Git Tracked? .env Default values for all environments. .env.dist A "distribution" template for the entire project. .env.dist.local Yes A template specifically for local machine overrides. .env.local The actual local secrets/settings for your machine.
💡 Pro Tip: Use this file to define variables like LOCAL_DOCKER_PORT or XDEBUG_CONFIG that vary between Mac, Windows, and Linux dev environments. Developers on macOS
If you are setting this up for a specific framework or tool, would you like a sample file structure or a README instruction for your team?
This template includes comments explaining each variable and is structured for clarity, security, and ease of use during local development.
# ==========================================
# .env.dist.local - Local Development Template
# ==========================================
# Copy this file to .env.local and replace values with your own.
# Do not commit .env.local to version control (keep secrets local).
# ==========================================
1. Machine‑Specific Defaults Without Affecting Shared Config
- Developers on macOS, Windows, or Linux may need different absolute paths, Docker host IPs, or local domain names.
- Place those values in
.env.dist.local (e.g., APP_DATA_PATH=/Users/yourname/data), then copy to .env.local (which Git ignores).
Database (MySQL/PostgreSQL)
---------------------------
How It Differs From Similar Files
| 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 |
DB_PORT=5432