.env vs .env.example: What Should You Upload to GitHub?

Most modern apps that call external APIs need configuration that changes between environments: different API keys for development and production, different database URLs, different feature flags. The standard way to manage this is with a pair of files: .env for real values and .env.example as a documented template.

.env contains real keys: OPENAI_API_KEY=sk-proj-abc123. .env.example contains the same variable names with placeholder strings: OPENAI_API_KEY=your_openai_key_here. They look similar but serve opposite purposes.

Together, they solve two problems: keeping secrets off GitHub while also making it easy to understand what the project needs to run. You cannot solve both problems with a single file.

.env is your local secret store. It lives in your project root and holds the actual credentials your app needs to run on your development machine. Variable names and their real values, one per line.

Your app framework reads .env at startup: Next.js reads it automatically, Python apps using python-dotenv call load_dotenv(), Vite reads it via import.meta.env. The values become available in code as process.env.VARIABLE_NAME or os.environ['VARIABLE_NAME'].

.env is strictly local. It belongs only on machines where the app runs in development. It must never be committed to Git because Git history is permanent — even if you delete the file later, old commits still contain the value.

.env.example is a safe documentation file. It lists every environment variable your app needs, but instead of real values it uses descriptive placeholder strings: STRIPE_SECRET_KEY=your_stripe_secret_key or DATABASE_URL=postgresql://user:password@localhost:5432/dbname.

When someone clones your project for the first time, they look at .env.example to understand what the app expects. They copy it to .env: cp .env.example .env — then replace the placeholders with their own real values. This makes project setup self-documenting.

.env.example is safe to commit and safe to share publicly. It contains no real secrets. Its value is entirely in the variable names and the placeholder strings that hint at the format expected.

Git stores the entire history of every file ever committed. Committing .env once — even if you immediately delete it in the next commit — leaves the real values permanently accessible in the repository's commit history. Anyone who clones the repo can access older commits.

GitHub is scanned continuously by automated bots looking for patterns that look like API keys. Even in private repositories, exposure risk exists through collaborators, forked repositories, and any future visibility changes.

The correct protection is .gitignore: a file in your project root that lists patterns Git should never track. Adding .env to .gitignore prevents the file from ever appearing in git status as a file to commit.

A placeholder should tell whoever reads it what kind of value goes there — without being a real value itself. Descriptive placeholders are better than empty strings or generic text.

Good placeholders: OPENAI_API_KEY=your_openai_api_key_here, DATABASE_URL=postgresql://user:password@localhost:5432/yourdb, STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key, JWT_SECRET=your_strong_random_secret_here.

Avoid: empty values (OPENAI_API_KEY=), generic single words (OPENAI_API_KEY=xxx), or anything that looks like a real key format. The goal is clarity, not obfuscation.

Next.js .env (local only): OPENAI_API_KEY=sk-proj-... STRIPE_SECRET_KEY=sk_live_... NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_... DATABASE_URL=postgres://localhost:5432/myapp. Only NEXT_PUBLIC_ variables appear in browser code — never use this prefix for secret keys.

Next.js .env.example (safe to commit): OPENAI_API_KEY=your_openai_api_key STRIPE_SECRET_KEY=your_stripe_secret_key NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key DATABASE_URL=postgresql://user:password@localhost:5432/yourdb.

Django .env (local only): SECRET_KEY=your-long-random-secret-key OPENAI_API_KEY=sk-proj-... DATABASE_URL=postgres://localhost:5432/myapp DEBUG=True. Django .env.example: SECRET_KEY=your-secret-key-here OPENAI_API_KEY=your_openai_api_key DATABASE_URL=postgresql://user:password@localhost:5432/yourdb DEBUG=False.

.gitignore is the enforcement mechanism. Without it, the two-file system does not protect you — .env will be committed the first time you run git add. Open .gitignore in your project root and verify .env appears as its own line.

If .gitignore did not exist before your first commit, .env may already be tracked. Check with git ls-files .env — if the command returns the filename, it is tracked. Untrack it with git rm --cached .env, then commit the removal. The key values in past commits remain in history; rotate those keys.

Framework starters usually include .env in .gitignore by default. Still verify it. AI-generated projects sometimes omit or misconfigure .gitignore, especially when the framework is non-standard or the project has unusual tooling.

If your project currently has only a .env with real values and no .env.example, follow these steps: check that .env is in .gitignore (add it if not), create .env.example by copying .env and replacing all real values with placeholders, commit .env.example, and verify .env does not appear in git status.

If your project has neither file, create both. Start with .env.example: list every variable name your app reads and give each a placeholder value. Use it as the specification. Then copy it to .env and fill in your real development values.

Once both files exist and .env is gitignored, maintain them together. When you add a new integration that needs a new variable, add the name with a placeholder to .env.example and the real value to .env. Commit .env.example; never commit .env.