fix: Override environment variables based on priority

CONTRIBUTING.md

@@ -124,6 +124,28 @@ pub enum SortBy {
 }
 ```
 
+## Tests
+
+To run all tests, use:
+```bash
+pixi run test
+```
+But if you have modified recipe data under the tests/data/channels directory, you need to update the test channel before running tests:
+```bash
+pixi run update-test-channel <channel_name>
+```
+> [!NOTE]
+> This task currently only works on unix systems. If you are on Windows, it is recommended to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install).
+
+For example, if you modified data for dummy_channel_1:
+```bash
+pixi run update-test-channel dummy_channel_1
+```
+After updating the test channel, run the tests again:
+```
+pixi run test
+```
+
 ## CLI documentation
 The CLI reference is automatically generated from the code documentation of CLI commands under `src/cli`.
 
@@ -136,4 +158,4 @@ and `pixi run -e docs mkdocs serve` to check out the web docs locally.
 You must commit the generated files as well as part of your PR.
 
 The `*_extender` files under `docs/reference/cli` are meant as extensions of the autogenerated documentation.
-Those are meant to be updated manually.
+Those are meant to be updated manually.

docs/reference/environment_variables.md

@@ -50,3 +50,117 @@ The following environment variables are set by Pixi, when using the `pixi run`,
 
 !!! note
     Even though the variables are environment variables these cannot be overridden. E.g. you can not change the root of the project by setting `PIXI_PROJECT_ROOT` in the environment.
+
+## Environment Variable Priority
+
+The following priority rule applies for environment variables: `task.env` > `activation.env` > `activation.scripts` > activation scripts of dependencies > outside environment variables.
+Variables defined at a higher priority will override those defined at a lower priority.
+
+!!! warning
+
+    In older versions of Pixi, this priority was not well-defined, and there are a number of known
+    deviations from the current priority which exist in some older versions.
+    Please see the warning in [the advanced tasks documentation](../workspace/advanced_tasks.md#environment-variables)
+    for further details and migration guidance.
+
+##### Example 1:  `task.env` > `activation.env`
+
+In `pixi.toml`, we defined an environment variable `HELLO_WORLD` in both `tasks.hello` and `activation.env`. 
+
+When we run `echo $HELLO_WORLD`, it will output:
+```
+Hello world!
+```
+
+```toml title="pixi.toml"
+[tasks.hello]
+cmd = "echo $HELLO_WORLD"
+env = { HELLO_WORLD = "Hello world!" }
+[activation.env]
+HELLO_WORLD = "Activate!"
+```
+
+##### Example 2: `activation.env` > `activation.scripts`
+
+In `pixi.toml`, we defined the same environment variable `DEBUG_MODE` in both `activation.env` and in the activation script file `setup.sh`.
+When we run `echo Debug mode: $DEBUG_MODE`, it will output:
+```bash
+Debug mode: enabled
+```
+
+```toml title="pixi.toml"
+[activation.env]
+DEBUG_MODE = "enabled"
+
+[activation]
+scripts = ["setup.sh"]
+```
+
+```bash title="setup.sh"
+export DEBUG_MODE="disabled"
+```
+
+##### Example 3: `activation.scripts` > activation scripts of dependencies
+
+In `pixi.toml`, we have our local activation script and a dependency `my-package` that also sets environment variables through its activation scripts.
+When we run `echo Library path: $LIB_PATH`, it will output:
+```
+Library path: /my/lib
+```
+
+```toml title="pixi.toml"
+[activation]
+scripts = ["local_setup.sh"]
+
+[dependencies]
+my-package = "*"  # This package has its own activation scripts that set LIB_PATH="/dep/lib"
+```
+```bash title="local_setup.sh"
+export LIB_PATH="/my/lib"
+```
+
+##### Example 4: activation scripts of dependencies > outside environment variable
+
+If we have a dependency that sets `PYTHON_PATH` and the same variable is already set in the outside environment.
+When we run `echo Python path: $PYTHON_PATH`, it will output:
+```bash
+Python path: /pixi/python
+```
+```
+# Outside environment
+export PYTHON_PATH="/system/python"
+```
+```toml title="pixi.toml"
+[dependencies]
+python-utils = "*"  # This package sets PYTHON_PATH="/pixi/python" in its activation scripts
+```
+
+##### Example 5: Complex Example - All priorities combined
+In `pixi.toml`, we define the same variable `APP_CONFIG` across multiple levels:
+```toml title="pixi.toml"
+[tasks.start]
+cmd = "echo Config: $APP_CONFIG"
+env = { APP_CONFIG = "task-specific" }
+
+[activation.env]
+APP_CONFIG = "activation-env"
+
+[activation]
+scripts = ["app_setup.sh"]
+
+[dependencies]
+config-loader = "*"  # Sets APP_CONFIG="dependency-config"
+```
+```bash title="app_setup.sh"
+export APP_CONFIG="activation-script"
+```
+```bash
+# Outside environment
+export APP_CONFIG="system-config"
+```
+
+Since `task.env` has the highest priority, when we run `pixi run start` it will output:
+
+```
+Config: task-specific
+```

docs/workspace/advanced_tasks.md

@@ -324,33 +324,51 @@ Note: if you want to debug the globs you can use the `--verbose` flag to see whi
 pixi run -v start
 ```
 
-## Environment variables
-You can set environment variables for a task.
-These are seen as "default" values for the variables as you can overwrite them from the shell.
+## Environment Variables
 
-```toml title="pixi.toml"
-[tasks]
-echo = { cmd = "echo $ARGUMENT", env = { ARGUMENT = "hello" } }
-```
-If you run `pixi run echo` it will output `hello`.
-When you set the environment variable `ARGUMENT` before running the task, it will use that value instead.
+You can set environment variables directly for a task, as well as by other means.
+See [the environment variable priority documentation](../reference/environment_variables.md#environment-variable-priority) for full details of ways to set environment variables,
+and how those ways interact with each other.
 
-```shell
-ARGUMENT=world pixi run echo
-✨ Pixi task (echo in default): echo $ARGUMENT
-world
-```
+!!! warning
 
-These variables are not shared over tasks, so you need to define these for every task you want to use them in.
+    In older versions of Pixi, this priority was not well-defined, and there are a number of known
+    deviations from the current priority which exist in some older versions:
+
+    - `activation.scripts` used to take priority over `activation.env`
+    - activation scripts of dependencies used to take priority over `activation.env`
+    - outside environment variables used to override variables set in `task.env`
+
+    If you previously relied on a certain priority which no longer applies, you may need to change your
+    task definitions.
+
+    For the specific case of overriding `task.env` with outside environment variables, this behaviour can
+    now be recreated using [task arguments](#task-arguments). For example, if you were previously using
+    a setup like:
 
-!!! note "Extend instead of overwrite"
-    If you use the same environment variable in the value as in the key of the map you will also overwrite the variable.
-    For example overwriting a `PATH`
     ```toml title="pixi.toml"
     [tasks]
-    echo = { cmd = "echo $PATH", env = { PATH = "/tmp/path:$PATH" } }
+    echo = { cmd = "echo $ARGUMENT", env = { ARGUMENT = "hello" } }
+    ```
+
+    ```shell
+    ARGUMENT=world pixi run echo
+    ✨ Pixi task (echo in default): echo $ARGUMENT
+    world
+    ```
+
+    you can now recreate this behaviour like:
+
+    ```toml title="pixi.toml"
+    [tasks]
+    echo = { cmd = "echo {{ ARGUMENT }}", args = [{"arg" = "ARGUMENT", "default" = "hello" }]}
+    ```
+
+    ```shell
+    pixi run echo world
+    ✨ Pixi task (echo): echo world
+    world
     ```
-    This will output `/tmp/path:/usr/bin:/bin` instead of the original `/usr/bin:/bin`.
 
 ## Clean environment
 You can make sure the environment of a task is "Pixi only".

src/activation.rs

@@ -236,6 +236,19 @@ async fn try_get_valid_activation_cache(
     }
 }
 
+// Extract variable name
+fn extract_variable_name(value: &str) -> Option<&str> {
+    if let Some(inner) = value.strip_prefix('$') {
+        Some(inner)
+    } else if let Some(inner) = value.strip_prefix('%').and_then(|s| s.strip_suffix('%')) {
+        Some(inner)
+    } else if let Some(inner) = value.strip_prefix("${").and_then(|s| s.strip_suffix('}')) {
+        Some(inner)
+    } else {
+        None
+    }
+}
+
 /// Runs and caches the activation script.
 pub async fn run_activation(
     environment: &Environment<'_>,
@@ -286,7 +299,7 @@ pub async fn run_activation(
         let current_env = std::env::vars().collect::<HashMap<_, _>>();
 
         // Run and cache the activation script
-        activator.run_activation(
+        let new_activator = activator.run_activation(
             ActivationVariables {
                 // Get the current PATH variable
                 path: Default::default(),
@@ -301,7 +314,29 @@ pub async fn run_activation(
                 current_env,
             },
             None,
-        )
+        );
+
+        // `activator.env_vars` should override `activator_result` for duplicate keys
+        new_activator.map(|mut map: HashMap<String, String>| {
+            // First pass: Add all variables from activator.env_vars(as map is unordered, we need to update the referenced value in the second loop)
+            for (k, v) in &activator.env_vars {
+                map.insert(k.clone(), v.clone());
+            }
+
+            // Second pass: Loop through the map and resolve variable references
+            let keys_to_update: Vec<String> = map.keys().cloned().collect();
+            for key in keys_to_update {
+                if let Some(value) = map.get(&key).cloned() {
+                    if let Some(referenced_var) = extract_variable_name(&value) {
+                        if let Some(actual_value) = map.get(referenced_var) {
+                            map.insert(key, actual_value.clone());
+                        }
+                    }
+                }
+            }
+
+            map
+        })
     })
     .await
     .into_diagnostic()?

src/cli/run.rs

@@ -373,7 +373,7 @@ async fn execute_task(
     command_env: &HashMap<OsString, OsString>,
     kill_signal: KillSignal,
 ) -> Result<(), TaskExecutionError> {
-    let Some(script) = task.as_deno_script()? else {
+    let Some(script) = task.as_deno_script(command_env)? else {
         return Ok(());
     };
     let cwd = task.working_directory()?;