Update documentation for `--env` compilation flag

1 files changed, 19 insertions, 1 deletions

diff --git a/src/doc/unstable-book/src/compiler-flags/env.md b/src/doc/unstable-book/src/compiler-flags/env.md
index df0547dd24b..56f804fcd0c 100644
--- a/src/doc/unstable-book/src/compiler-flags/env.md
+++ b/src/doc/unstable-book/src/compiler-flags/env.md
@@ -5,7 +5,10 @@ The tracking issue for this feature is: [#118372](https://github.com/rust-lang/r
 ------------------------
 
 This option flag allows to specify environment variables value at compile time to be
-used by `env!` and `option_env!` macros.
+used by `env!` and `option_env!` macros. It also impacts `tracked_env::var` function
+from the `proc_macro` crate.
+
+This information will be stored in the dep-info files.
 
 When retrieving an environment variable value, the one specified by `--env` will take
 precedence. For example, if you want have `PATH=a` in your environment and pass:
@@ -20,6 +23,21 @@ Then you will have:
 assert_eq!(env!("PATH"), "env");
 ```
 
+It will trigger a new compilation if any of the `--env` argument value is different.
+So if you first passed:
+
+```bash
+--env A=B --env X=12
+```
+
+and then on next compilation:
+
+```bash
+--env A=B
+```
+
+`X` value is different (not set) so the code will be re-compiled.
+
 Please note that on Windows, environment variables are case insensitive but case
 preserving whereas `rustc`'s environment variables are case sensitive. For example,
 having `Path` in your environment (case insensitive) is different than using