docs(runtime): update --env-flag arg flag to include multiple file su…

…pport (#1151)

deploy/manual/environment-variables.md

@@ -41,8 +41,22 @@ update.
 
 When deploying using `deployctl`, you can specify environment variables
 [using the `--env` or `--env-file` flags](./deployctl.md#environment-variables),
-complementing the environment variables already defined for the project. These
-env variables will be specific for the deployment being created.
+complementing the environment variables already defined for the project. You can
+also pass multiple `--env-file` arguments (e.g.,
+`--env-file=.env.one --env-file=.env.two`) to include variables from multiple
+files.
+
+:::note
+
+When multiple declarations for the same environment variable exist within a
+single `.env` file, the first occurrence is applied. However, if the same
+variable is defined across multiple `.env` files (using multiple `--env-file`
+arguments), the value from the last file specified takes precedence. This means
+that the first occurrence found in the last `.env` file listed will be applied.
+
+:::
+
+These env variables will be specific for the deployment being created.
 
 ### Default environment variables
 

runtime/reference/env_variables.md

@@ -29,6 +29,19 @@ Deno supports `.env` files. You can cause Deno to read environment variables
 from `.env` using the `--env-file` flag: `deno run --env-file <script>`. This
 will read `.env` by default; if you want or need to load environment variables
 from a different file, you can specify that file as a parameter to the flag.
+Additionally, you can pass multiple `--env-file` flags (e.g.,
+`deno run --env-file=.env.one --env-file=.env.two --allow-env <script>`) to load
+variables from multiple files.
+
+:::note
+
+When multiple declarations for the same environment variable exist within a
+single `.env` file, the first occurrence is applied. However, if the same
+variable is defined across multiple `.env` files (using multiple `--env-file`
+arguments), the value from the last file specified takes precedence. This means
+that the first occurrence found in the last `.env` file listed will be applied.
+
+:::
 
 Alternately, the `dotenv` package in the standard library will load environment
 variables from `.env` as well.