.env Diff & Merge

How to Use

1. Paste your .env file contents into the left textarea.
2. Paste your .env.example (or any second env file) into the right textarea.
3. Click Compare to see missing keys, extra keys, and changed values.
4. Click Generate Merged to create a combined .env with all keys.
5. Copy the merged output with the Copy button.

What Are Environment Variables?

Environment variables are key-value pairs that configure how an application behaves in different environments — development, staging, and production. Instead of hardcoding database URLs, API keys, and feature flags directly in source code, developers store them externally in environment variables. This separation is a core principle of the Twelve-Factor App methodology, which defines best practices for building modern, scalable software.

The .env file convention was popularized by the Ruby dotenv gem and has since been adopted across virtually every programming ecosystem. Libraries like dotenv for Node.js, python-dotenv for Python, and godotenv for Go all read .env files and inject the key-value pairs into the process environment at startup. Docker and Docker Compose also support .env files natively with the env_file directive.

The .env and .env.example Pattern

A well-maintained project uses two companion files. The .env file holds real credentials and secrets — database passwords, third-party API keys, signing secrets — and is listed in .gitignore so it never enters version control. The .env.example file (sometimes called .env.sample or .env.template) is committed to the repository and serves as documentation: it lists every environment variable the application needs, often with placeholder values like your-api-key-here or sensible defaults like localhost.

When a new developer clones the repository, they copy .env.example to .env and fill in their own values. When a feature branch adds a new variable to .env.example, every developer needs to add that key to their local .env — and this is exactly where things go wrong. Over weeks and months, the two files drift apart. A missing REDIS_URL or STRIPE_WEBHOOK_SECRET only surfaces as a cryptic runtime error, sometimes in production. This diff tool catches that drift before it causes problems.

.env File Format and Syntax

The .env format is intentionally simple but has several nuances that this parser handles correctly:

• Basic pairs: KEY=VALUE — the most common format. The key is everything before the first =, the value is everything after.
• Quoted values: KEY="value with spaces" or KEY='value' — surrounding quotes are stripped. Use quotes when values contain spaces, special characters, or trailing whitespace.
• Empty values: KEY= or just KEY — both are valid. The key exists but its value is an empty string.
• Comments: Lines starting with # are ignored. Inline comments after values are not standard and behavior varies across implementations.
• Values with equals signs: DATABASE_URL=postgres://user:pass@host/db?sslmode=require — only the first = is treated as the delimiter.
• Multiline values: Some implementations support multiline values with quotes, though this is not universal across all dotenv libraries.

Security Best Practices for .env Files

Environment files frequently contain production secrets — database passwords, API keys, encryption keys, OAuth client secrets. Mishandling them is one of the most common security vulnerabilities in modern applications. Follow these practices:

• Never commit .env to version control. Add .env to your .gitignore before your first commit. If you accidentally commit secrets, rotate them immediately — removing the file from Git history is not enough, as the secrets may already be cached or cloned.
• Always commit .env.example. This file should contain only placeholder values, never real secrets. It documents what the application needs without exposing sensitive data.
• Use different values per environment. Development, staging, and production should each have unique credentials. Never share database passwords or API keys across environments.
• Consider secrets managers for production. Tools like AWS Secrets Manager, HashiCorp Vault, Doppler, and 1Password CLI provide encrypted storage, access control, audit logs, and automatic rotation that plain .env files cannot offer.
• Validate variables at startup. Libraries like envalid for Node.js and pydantic-settings for Python validate that all required environment variables are present and correctly formatted before your application starts, catching missing keys immediately instead of at runtime.

The Twelve-Factor App and Configuration

The Twelve-Factor App methodology, authored by Heroku co-founder Adam Wiggins, established the principle that application configuration — anything that varies between deploys — must be stored in the environment, not in code. Factor III states: "Store config in the environment." This ensures strict separation between code and config, making applications portable across environments without code changes. The .env file pattern is the most common implementation of this principle for local development.

Common Use Cases for .env Diff

Comparing environment files is useful in several everyday development scenarios. When pulling changes from a shared repository, you can diff your local .env against the updated .env.example to find any newly required variables. During code review, you can verify that a pull request adding new features also adds the corresponding keys to .env.example. When debugging deployment failures, comparing the production environment against the template can reveal missing or misconfigured variables. Teams migrating between cloud providers or container orchestrators can use the merge feature to consolidate environment files from different sources.

Related Tools

Compare any two text files with the Diff Checker. Format JSON configuration files with the JSON Formatter. Convert between JSON and YAML config formats using the JSON-YAML Converter. Encode sensitive values with the Base64 Encoder. Generate secure passwords for environment variables with the Password Generator. Validate JSON config files with the JSON Validator.

Learn More

• Dotenv Best Practices — managing environment variables safely across development, staging, and production.