Insights

The Homeless .env file

Ever struggled with the temptation to push the .env file into github? Or the frustration of losing it an year down the line?

Yantratmika Solutions 14 min read
The Homeless .env file

Let’s start with a scene you’ve probably lived through.

It’s your first morning on a new project. You clone the repo, run npm install (or pip install, or go build, take your pick), start the app, and… it crashes. Something about a missing database URL.

So you do what everyone does. You message a teammate:

“Hey, can you send me the .env?”

A few minutes later, a file lands in your chat. Maybe it’s current. Maybe it’s from three weeks ago and nobody remembers that the payment API key changed. You paste it in, cross your fingers, and get on with your day.

And now that file lives in a chat history. Forever.

If this feels familiar, this post is for you. And I promise there’s a good ending.

The .env paradox

The .env file holds the stuff your app can’t live without: API keys, database passwords, tokens. We all learned the rule early: never commit it to Git. Add it to .gitignore and move on.

Good rule. Really. Committing a plaintext secret is one of the most expensive “oops” moments in software, because Git never forgets. Delete the file in the next commit and the secret is still sitting in history, one git log away from anyone who looks.

But look at what that rule quietly does. It moves a critical piece of your project out of the project. The code is in the repo. The tests are in the repo. The docs are in the repo. The one file you need to actually run the thing? It lives somewhere else, and it travels by word of mouth.

That’s the paradox. We protect the secret by making it homeless.

What homelessness costs you

It doesn’t feel like a big deal until you add it up:

  • Onboarding drags. Every new teammate starts with a treasure hunt. Someone has to be around, remember where the latest copy is, and send it safely (or not so safely).
  • Drift creeps in. Someone adds a new variable. They tell two people. The other four spend an hour wondering why the build is red.
  • Secrets pile up in strange places. Chat messages, emails, sticky notes, a “temp” folder on the desktop. None of those were meant to be a vault.
  • Juggling projects is a nightmare. If you work with more than one team or client (and who doesn’t, these days?), you’re now carrying a pile of .env files, trying to remember which belongs to what.
  • One tired afternoon away from disaster. All it takes is one git add . on a day you forgot the ignore rule, and the plaintext file is in history.

The fix everyone recommends is a proper secrets platform. And for production, that’s the right answer. But for a small team, a side project, or a client engagement, spinning up and paying for infrastructure just to share a dev database password feels like using a crane to hang a picture.

What most of us actually want is simple:

Everything about the project, in one place. Secrets included. But safe.

The idea: commit the secret, just not the plain secret

Here’s the thought that changes everything. The problem was never “secrets in Git.” The problem is plaintext secrets in Git.

What if the repo held an encrypted copy of your .env? Anyone can see it. Nobody can read it without the key. The key stays on your machine, never in the repo. And the whole thing happens automatically, so you never have to remember it.

That’s guardenv.

Meet guardenv

guardenv is a small, free, open-source command-line tool that guards your .env files. It does three things, and does them quietly:

  1. Before every commit, it encrypts your .env into a guarded.env file and adds that to the commit. Plaintext never touches Git.
  2. After every clone, checkout or pull, it decrypts guarded.env back into .env. The file is just there, every time.
  3. It keeps .env in your .gitignore, so the plaintext copy can’t sneak in by accident.

The key lives in a little folder in your home directory (~/.guardenv/), outside any repository. Each project gets its own uniquely named key, so if you work for two different teams, nothing ever collides.

Seeing it in action

Install it. On Windows, with Scoop:

scoop bucket add guardenv https://github.com/yantratmika/scoop-guardenv
scoop install guardenv

(On other systems, grab a build from the Releases page, or run go install github.com/yantratmika/guardenv@latest.)

Then, in your project:

guardenv init

That one command does the setup for you. It makes sure .env is ignored, hunts down every .env file in your repo (monorepo with five of them? no problem; it skips node_modules and anything else Git ignores), creates a fresh random key, writes a small config file, and installs the git hooks.

Now just work like normal:

git add -A
git commit -m "Add database config"

During that commit, guardenv encrypts your .env and slips guarded.env into the commit. That’s the only version Git ever sees.

Here’s the part I love. Your new teammate clones the repo, drops the shared key into ~/.guardenv/ (the file name is in .guardenv/config), and runs:

guardenv install-hooks
guardenv decrypt

Their .env appears. From then on, every git pull keeps it up to date. No more “can someone send me the .env?”. Ever.

“But is it actually safe?”

Fair question. You should always ask it.

Under the hood, guardenv uses AES-256-GCM, straight from Go’s standard cryptography library. That’s a well-studied, authenticated cipher: it keeps the contents secret and notices if anyone has tampered with the file or you’re using the wrong key. Each encryption uses a fresh random nonce. There are no third-party dependencies to worry about. The whole program is a single readable file, so you can check our work yourself.

A few other small safety touches:

  • It won’t overwrite your local edits. If your .env differs from the committed version, guardenv decrypt keeps your file and warns you. You have to ask (--force) to overwrite it.
  • It doesn’t spam your history. If nothing changed, the encrypted file isn’t re-generated, so your commits stay clean.
  • The hooks are per-repository. Installing guardenv doesn’t change anything in your other projects.

Let’s be honest about the limits

I’d rather you hear this from me than discover it later.

  • It’s one shared key per project. Anyone with the key can read every guarded file. There are no per-person permissions. Treat the key like a password: share it over a secure channel.
  • Lose the key and the files are gone. We can’t recover them, and neither can anyone else. Put a backup in your password manager.
  • There’s no key rotation (yet). If someone leaves the team, rotate the actual secrets (the API keys and passwords), and consider a new key. Older commits stay readable with the old key.
  • It’s not for production. For production workloads, use your cloud’s secrets manager. guardenv is for development and shared project configuration, the stuff that today is floating around in chat.

A tool that’s honest about what it is tends to be a tool you can trust.

How it gets to you: a quick peek at the plumbing

For the curious: guardenv’s releases are fully automated. Push a version tag, and a GitHub Actions workflow uses GoReleaser to build binaries for Windows, Linux and macOS, publish a GitHub Release, and update the Scoop package. No manual build steps, no “works on my machine” releases. It’s all in the repo if you’d like to read it.

Try it on a side project this weekend

If your .env story today is “ask someone”, give guardenv ten minutes. Install it, run guardenv init in a small repo, make a commit, delete your .env, and run guardenv decrypt. Watch it come back.

There’s something quietly satisfying about the moment a secret stops being a favor you ask for and becomes just… part of the project.

Your .env deserves a home. Let’s give it one.


Links

guardenv is MIT licensed and provided as-is. Use it at your own risk, and keep a backup of your key.

title: The Homeless .env file description: Ever struggled with the temptation to push the .env file into github? Or the frustration of losing it an year down the line? author: Yantratmika Solutions date: 2026-10-23 image: https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/adtruquptly79c9hg7ae.jpg url: type: article keywords: security, good practices category: engineering


Let’s start with a scene you’ve probably lived through.

It’s your first morning on a new project. You clone the repo, run npm install (or pip install, or go build, take your pick), start the app, and… it crashes. Something about a missing database URL.

So you do what everyone does. You message a teammate:

“Hey, can you send me the .env?”

A few minutes later, a file lands in your chat. Maybe it’s current. Maybe it’s from three weeks ago and nobody remembers that the payment API key changed. You paste it in, cross your fingers, and get on with your day.

And now that file lives in a chat history. Forever.

If this feels familiar, this post is for you. And I promise there’s a good ending.

The .env paradox

The .env file holds the stuff your app can’t live without: API keys, database passwords, tokens. We all learned the rule early: never commit it to Git. Add it to .gitignore and move on.

Good rule. Really. Committing a plaintext secret is one of the most expensive “oops” moments in software, because Git never forgets. Delete the file in the next commit and the secret is still sitting in history, one git log away from anyone who looks.

But look at what that rule quietly does. It moves a critical piece of your project out of the project. The code is in the repo. The tests are in the repo. The docs are in the repo. The one file you need to actually run the thing? It lives somewhere else, and it travels by word of mouth.

That’s the paradox. We protect the secret by making it homeless.

What homelessness costs you

It doesn’t feel like a big deal until you add it up:

  • Onboarding drags. Every new teammate starts with a treasure hunt. Someone has to be around, remember where the latest copy is, and send it safely (or not so safely).
  • Drift creeps in. Someone adds a new variable. They tell two people. The other four spend an hour wondering why the build is red.
  • Secrets pile up in strange places. Chat messages, emails, sticky notes, a “temp” folder on the desktop. None of those were meant to be a vault.
  • Juggling projects is a nightmare. If you work with more than one team or client (and who doesn’t, these days?), you’re now carrying a pile of .env files, trying to remember which belongs to what.
  • One tired afternoon away from disaster. All it takes is one git add . on a day you forgot the ignore rule, and the plaintext file is in history.

The fix everyone recommends is a proper secrets platform. And for production, that’s the right answer. But for a small team, a side project, or a client engagement, spinning up and paying for infrastructure just to share a dev database password feels like using a crane to hang a picture.

What most of us actually want is simple:

Everything about the project, in one place. Secrets included. But safe.

The idea: commit the secret, just not the plain secret

Here’s the thought that changes everything. The problem was never “secrets in Git.” The problem is plaintext secrets in Git.

What if the repo held an encrypted copy of your .env? Anyone can see it. Nobody can read it without the key. The key stays on your machine, never in the repo. And the whole thing happens automatically, so you never have to remember it.

That’s guardenv.

Meet guardenv

guardenv is a small, free, open-source command-line tool that guards your .env files. It does three things, and does them quietly:

  1. Before every commit, it encrypts your .env into a guarded.env file and adds that to the commit. Plaintext never touches Git.
  2. After every clone, checkout or pull, it decrypts guarded.env back into .env. The file is just there, every time.
  3. It keeps .env in your .gitignore, so the plaintext copy can’t sneak in by accident.

The key lives in a little folder in your home directory (~/.guardenv/), outside any repository. Each project gets its own uniquely named key, so if you work for two different teams, nothing ever collides.

Seeing it in action

Install it. On Windows, with Scoop:

scoop bucket add guardenv https://github.com/yantratmika/scoop-guardenv
scoop install guardenv

(On other systems, grab a build from the Releases page, or run go install github.com/yantratmika/guardenv@latest.)

Then, in your project:

guardenv init

That one command does the setup for you. It makes sure .env is ignored, hunts down every .env file in your repo (monorepo with five of them? no problem; it skips node_modules and anything else Git ignores), creates a fresh random key, writes a small config file, and installs the git hooks.

Now just work like normal:

git add -A
git commit -m "Add database config"

During that commit, guardenv encrypts your .env and slips guarded.env into the commit. That’s the only version Git ever sees.

Here’s the part I love. Your new teammate clones the repo, drops the shared key into ~/.guardenv/ (the file name is in .guardenv/config), and runs:

guardenv install-hooks
guardenv decrypt

Their .env appears. From then on, every git pull keeps it up to date. No more “can someone send me the .env?”. Ever.

“But is it actually safe?”

Fair question. You should always ask it.

Under the hood, guardenv uses AES-256-GCM, straight from Go’s standard cryptography library. That’s a well-studied, authenticated cipher: it keeps the contents secret and notices if anyone has tampered with the file or you’re using the wrong key. Each encryption uses a fresh random nonce. There are no third-party dependencies to worry about. The whole program is a single readable file, so you can check our work yourself.

A few other small safety touches:

  • It won’t overwrite your local edits. If your .env differs from the committed version, guardenv decrypt keeps your file and warns you. You have to ask (--force) to overwrite it.
  • It doesn’t spam your history. If nothing changed, the encrypted file isn’t re-generated, so your commits stay clean.
  • The hooks are per-repository. Installing guardenv doesn’t change anything in your other projects.

Let’s be honest about the limits

I’d rather you hear this from me than discover it later.

  • It’s one shared key per project. Anyone with the key can read every guarded file. There are no per-person permissions. Treat the key like a password: share it over a secure channel.
  • Lose the key and the files are gone. We can’t recover them, and neither can anyone else. Put a backup in your password manager.
  • There’s no key rotation (yet). If someone leaves the team, rotate the actual secrets (the API keys and passwords), and consider a new key. Older commits stay readable with the old key.
  • It’s not for production. For production workloads, use your cloud’s secrets manager. guardenv is for development and shared project configuration, the stuff that today is floating around in chat.

A tool that’s honest about what it is tends to be a tool you can trust.

How it gets to you: a quick peek at the plumbing

For the curious: guardenv’s releases are fully automated. Push a version tag, and a GitHub Actions workflow uses GoReleaser to build binaries for Windows, Linux and macOS, publish a GitHub Release, and update the Scoop package. No manual build steps, no “works on my machine” releases. It’s all in the repo if you’d like to read it.

Try it on a side project this weekend

If your .env story today is “ask someone”, give guardenv ten minutes. Install it, run guardenv init in a small repo, make a commit, delete your .env, and run guardenv decrypt. Watch it come back.

There’s something quietly satisfying about the moment a secret stops being a favor you ask for and becomes just… part of the project.

Your .env deserves a home. Let’s give it one.


Links

guardenv is MIT licensed and provided as-is. Use it at your own risk, and keep a backup of your key.

Working on something similar?

We help teams take Generative AI, IoT and AWS systems to production. Talk to the engineers who write these articles.