`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. Relative PATH entries are resolved from project root during executable lookup.

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", "run")

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

Compose prioritized paths

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

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

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

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