From 0756fe034ded1ba8f3ccf0c11ff794c81caf4ff8 Mon Sep 17 00:00:00 2001
From: Victor Berchet <victor@suumit.com>
Date: Wed, 22 Jan 2025 08:37:11 +0100
Subject: [PATCH 1/3] Clarify how `wrangler --env` affects loading `.env` and
 `.dev.vars`

---
 .../docs/workers/wrangler/system-environment-variables.mdx   | 5 +++++
 src/content/partials/workers/secrets-in-dev.mdx              | 4 +++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/workers/wrangler/system-environment-variables.mdx b/src/content/docs/workers/wrangler/system-environment-variables.mdx
index 46f72a49a8166e1..fc5cdfa631be36e 100644
--- a/src/content/docs/workers/wrangler/system-environment-variables.mdx
+++ b/src/content/docs/workers/wrangler/system-environment-variables.mdx
@@ -16,6 +16,11 @@ System environment variables are local environment variables that can change Wra
 
 3. Set the values in your shell environment. For example, if you are using Z shell, adding `export CLOUDFLARE_API_TOKEN=...` to your `~/.zshrc` file will set this token as part of your shell configuration.
 
+:::note
+
+You can set system environment variables per environment by creating additional files with the naming convention `.env.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, these files take precedence over `.env`.
+:::
+
 ## Supported environment variables
 
 Wrangler supports the following environment variables:
diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx
index 9f95cf6c5cee8ad..61e63f925443e5c 100644
--- a/src/content/partials/workers/secrets-in-dev.mdx
+++ b/src/content/partials/workers/secrets-in-dev.mdx
@@ -12,4 +12,6 @@ SECRET_KEY="value"
 API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
 ```
 
-You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.
+You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, these files take precedence over `.dev.vars`.
+
+Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.

From 26834053e779ed13dd779acbdc3154eb10ab1841 Mon Sep 17 00:00:00 2001
From: Victor Berchet <victor@suumit.com>
Date: Wed, 22 Jan 2025 13:23:50 +0100
Subject: [PATCH 2/3] Update
 src/content/docs/workers/wrangler/system-environment-variables.mdx

Co-authored-by: Pete Bacon Darwin <pete@bacondarwin.com>
---
 .../docs/workers/wrangler/system-environment-variables.mdx      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/workers/wrangler/system-environment-variables.mdx b/src/content/docs/workers/wrangler/system-environment-variables.mdx
index fc5cdfa631be36e..17e5b41100bd928 100644
--- a/src/content/docs/workers/wrangler/system-environment-variables.mdx
+++ b/src/content/docs/workers/wrangler/system-environment-variables.mdx
@@ -18,7 +18,7 @@ System environment variables are local environment variables that can change Wra
 
 :::note
 
-You can set system environment variables per environment by creating additional files with the naming convention `.env.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, these files take precedence over `.env`.
+You can set system environment variables per environment by creating additional files with the naming convention `.env.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, such an environment specific file will be loaded instead of the `.env` file - they are not merged.
 :::
 
 ## Supported environment variables

From 92989398badb96a0c3dd856fe02d667a92b998ca Mon Sep 17 00:00:00 2001
From: Victor Berchet <victor@suumit.com>
Date: Wed, 22 Jan 2025 13:24:54 +0100
Subject: [PATCH 3/3] Update src/content/partials/workers/secrets-in-dev.mdx

---
 src/content/partials/workers/secrets-in-dev.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx
index 61e63f925443e5c..64e701da9829eb1 100644
--- a/src/content/partials/workers/secrets-in-dev.mdx
+++ b/src/content/partials/workers/secrets-in-dev.mdx
@@ -12,6 +12,6 @@ SECRET_KEY="value"
 API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
 ```
 
-You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, these files take precedence over `.dev.vars`.
+You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, such an environment specific file will be loaded instead of the `.dev.vars` file - they are not merged.
 
 Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.