# What is a .env.example file?

> A .env.example file lists the variables an app needs, with placeholders instead of real values, so it can live in Git. How to keep it accurate.

URL: https://crunu.com/learn/env-example-file
Language: en
Updated: 2026-10-30

A `.env.example` file is a committed template of a project's [.env file](https://crunu.com/learn/dotenv-file): it lists every variable the application expects, with placeholder or harmless default values, so a new developer knows what to fill in without anyone sending them the real file.

## What it is for

The real `.env` stays out of version control because it holds secrets. That leaves a gap: how does someone cloning the repository learn which variables exist? The template fills it. Laravel ships one in every new project, and its documentation suggests teams keep "including and updating the `.env.example` file", because "by putting placeholder values in the example configuration file, other developers on your team can clearly see which environment variables are needed" ([Laravel](https://laravel.com/docs/13.x/configuration)). The same file goes by other names: `.env.sample`, `.env.template`, `.env.dist`.

```dotenv
# Copy to .env and fill in. Ask in #payments for staging values.
DATABASE_URL=postgres://localhost:5432/payments
STRIPE_SECRET_KEY=sk_test_REPLACE_ME
STRIPE_WEBHOOK_SECRET=
LOG_LEVEL=info
```

A good template also documents. A comment next to a variable can say what format it takes, which values are safe locally, and where the real value comes from.

## Common mistakes

- **A real value in the template.** Someone copies their `.env` to `.env.example` and forgets to blank one line. The template is committed on purpose, so the value is now in Git history, which is the same as a [leaked secret](https://crunu.com/learn/leaked-secret).
- **Drift.** A developer adds `REDIS_URL` to their own file and the code, but not to the template. The next person to clone gets a crash, or worse, a silent fallback. This is [configuration drift](https://crunu.com/learn/configuration-drift) between the template and reality.
- **Defaults that work in production.** A placeholder such as `SESSION_SECRET=changeme` that the app accepts will, sooner or later, be deployed unchanged.
- **The template as the handover.** It tells people *which* values they need, not how to get them. "Ask a colleague" usually ends in a chat message with the real file.

## How to keep it in sync

The simplest check compares names, not values: every variable the code reads should appear in the template, and every name in the template should still be used. Some teams fail the build on a mismatch. The [compare two .env files](https://crunu.com/tools/env-diff) tool shows the names that are present in one file and missing from the other, in the browser. A longer treatment is in [keeping .env.example in sync](https://crunu.com/blog/keep-env-example-in-sync).

## How Crunu relates to it

Crunu has no special support for template files; it doesn't read or update `.env.example`. What it changes is the step after the template. Instead of each developer filling in a copy, the team keeps the real values in environments such as `payments-api / development`, and people get them through their access. **Compare environments** shows which variables exist only in one environment and which values differ, with values hidden until you choose to show them. When you create an environment with **Variable names only, no values**, it starts with the names of another environment and none of its values, which is the template idea applied inside the vault.

The template still earns its place in the repository: it documents the variables for people who don't have access yet, and it is the file you can safely let an AI coding agent read. More on the overall setup: [how to share .env files with your team](https://crunu.com/guides/share-env-files-with-a-team).

## Sources

- [Laravel 13.x: Configuration](https://laravel.com/docs/13.x/configuration), checked October 30, 2026.