`env_prepend`

env_prepend returns a dependency that adds one item to the beginning of an environment variable. For PATH, this gives the added directory priority over existing entries. Values are stored unchanged; use path_make_absolute when a path should be resolved from the project root.

Arguments

Argument	Required	Description
`key`	Yes	Environment variable name to change.
`value`	Yes	String item to prepend.
`unique`	No	Keep the existing value when an equivalent item is already present. Defaults to `False`.

Uniqueness uses exact string comparison on Linux and macOS. On Windows, PATH entries are compared case-insensitively; other variables use exact comparison.

Examples

Prefer a project tool directory

load("@os@1", "env_prepend", "os_run")

os_run(
    ("my-tool", "check"),
    deps=[env_prepend("PATH", "tools/bin")],
)

Compose prioritized paths

load("@os@1", "env_prepend", "os_run")

tool_paths = (
    env_prepend("PATH", "vendor/bin", unique=True) +
    env_prepend("PATH", "tools/bin", unique=True)
)

os_run(("my-tool", "check"), deps=[tool_paths])

Because dependencies apply from left to right, tools/bin is first in the final PATH.