Syncing env files across environments

As a project grows, its env files drift. A new key lands in .env.local, someone adds something to .env.production, and .env.example quietly falls behind. Dotvault gives you a few different ways to spot drift and fix it deliberately.

The .env.example prompt

The most common drift is between a working env file and the .env.example that’s meant to document it. After you save any .env file, Dotvault checks whether any of your new keys are missing from .env.example. If so, a prompt pops up listing the missing keys and offering to add them for you.

You get two choices:

  • Keys only. Adds the key names with empty values. Safe to commit to git.
  • Keys + values. Copies values along with the keys. Dotvault warns you before doing this if the target is .env.example, .env.sample, or .env.template, since those files are almost always committed.

You can selectively include or skip individual keys before confirming.

The Diff tab

For manual, two-file comparisons — dev against production, for instance — open the Diff tab. Pick a source file and a target file and Dotvault lists every key across both, highlighting the rows where values differ or a key is missing from one side.

From the Diff tab you can:

  • Filter the list with the search box to narrow in on a prefix or service.
  • Sync individual keys one at a time with the arrow buttons on each row.
  • Sync everything missing at once with the bulk Add N to file buttons at the top.
  • Switch the sync mode between keys-only and keys+values, just like the .env.example prompt.

Sync is a write operation on the target file, so the usual save behaviour applies — a new snapshot is created on the target after the change lands.

The Compare tab

Sometimes you don’t want a pairwise diff — you want a bird’s-eye view of every env file in the project at once. The Compare tab shows a matrix with one row per variable and one column per .env file. Rows where values differ across environments are highlighted, so you can scan top-to-bottom and spot the keys that look wrong.

Compare is read-only. It’s the tool you reach for when you’re asking “is anything weird here?”, not the one for making edits.

Encrypted files are included

You can sync between encrypted and plaintext env files transparently. Dotvault decrypts .env*.encrypted files on the fly for the Diff and Compare tabs, so you can keep an encrypted production file in sync with a plaintext local one without any manual steps at all.

Managing drift over time

A few habits keep drift under control:

  • Always accept the .env.example prompt after adding a new key locally, even if the values are empty.
  • Use Compare periodically to catch silent divergence between environments.
  • Rotate secrets through Dotvault so every environment picks up the new value through a deliberate sync, rather than patching files ad hoc.