.env files: syntax, merging, and secrets hygiene

.env files (often called dotenv files) are plain text lists of NAME=value assignments. Frameworks and CLIs load them into process environment variables so apps can read configuration without hardcoding it in source. They are simple, which makes them easy to misuse for secrets—so syntax, merge rules, and hygiene matter together.

Core syntax

Each meaningful line is usually KEY=value:

• Comments start with # (after optional whitespace on a line). Blank lines are ignored.
• An optional export prefix is treated like a shell export (export API_URL=https://…) and many parsers accept it.
• The first = splits key from value; keys are trimmed, and leading/trailing spaces around the value depend on quoting (see below).

Keys should look like identifiers: letters, digits, underscore, and sometimes dot or hyphen depending on the loader. POSIX-style shell names are stricter ([A-Za-z_][A-Za-z0-9_]*). If you need keys that work everywhere (including export in POSIX shells), stay in that set.

Quoting and values

• Single quotes `'…'**: the value is taken literally until the closing quote—no escape sequences inside.
• Double quotes "…"**: common escapes apply (for example \n, \t, ", \`). This is the usual choice when the value has spaces or special characters.
• Unquoted values: parsers often trim trailing spaces and may treat inline comments only when a # appears after whitespace (so URL=https://x.com#path can be ambiguous—quote URLs that contain #).

Line continuation: a trailing backslash at the end of a line (dotenv-style) joins the next physical line into one logical line—useful for long values.

Duplicate keys and merging

Many dotenv implementations follow “last assignment wins” for the same key: if PORT=3000 appears twice, the later line overrides the earlier one. That matches how a map of variables is usually built while scanning top to bottom.

When you merge two files (for example a checked-in .env.example plus a local override), products typically offer two strategies:

• Overlay wins: keys present in the “patch” file replace the base; keys only in the base stay.
• Base wins: the base file’s values take precedence where both define the same key.

Know which mode your merge tool uses before you rely on it in automation.

Secrets hygiene (short and strict)

1. Never commit real secrets—add .env, .env.local, and machine-specific files to .gitignore, and use templates (.env.example) with dummy values only.
2. Separate environments: production credentials belong in a secret manager or platform env injection, not in a file copied between laptops.
3. Rotation: if a .env line ever leaked (chat, screenshot, CI log), rotate the credential; editing the file is not enough.
4. Least privilege: scope API keys to the minimum access; prefer short-lived tokens where possible.
5. Where you paste matters: prefer tools that run locally in your browser or on your machine for editing and merging, so file contents are not uploaded as part of the workflow. LocalTools’ Privacy page describes how the site approaches that model.

For one-time sharing, prefer purpose-built flows (for example Secret share on LocalTools) over email or chat, and still treat shared links as sensitive.

Try it in your browser

To parse, validate keys, normalize, and merge dotenv-style text without sending it to a server, use the Env File Editor. Processing stays in your browser on LocalTools.

Related reading

• JSON vs YAML for config — when structured config files replace or complement flat env vars.
• What is TOML? — another human-edited config format often used alongside env-based deployment settings.