Out-of-tree devenvs

Added in 2.0

An out-of-tree devenv lets a project use a configuration that exists outside that project. This method lets many repositories share one configuration without copies. Your project does not need a local devenv.nix.

Select a source

The --from option accepts a local path or a supported input URI:

$ devenv --from path:../shared-devenv shell
$ devenv --from 'github:myorg/devenv-configs?dir=rust-web' shell

The path: prefix is required for file system paths. devenv resolves a relative path from the directory where you run the command. The dir query selects a devenv within the fetched repository.

Use --from with commands such as shell, test, up, and build.

Caution

The source can define scripts, processes, and shell hooks. Use only a source that you trust.

Bind a directory to the source

Use allow to save the source for the current directory:

$ cd my-project
$ devenv --from 'github:myorg/devenv-configs?dir=rust-web' allow
$ devenv shell

The binding applies to the current directory and its subdirectories. Later commands use the saved source without --from. An installed shell hook also starts the environment when you enter the bound directory.

Persistent bindings in version 2.2

Before version 2.2, each command required the --from option.

Load the source configuration

An out-of-tree source can contain these files and references:

• devenv.nix and devenv.local.nix
• devenv.yaml and devenv.local.yaml
• YAML imports and inputs
• Nix modules from the YAML import graph

Complete fetched sources in version 2.4.1

Fetched sources now load the complete YAML configuration. Earlier versions loaded only devenv.nix from a fetched source.

A local path: source stays live. devenv reads its changes without another fetch or allow command.

A fetched source uses the revision in the target directory’s devenv.lock. Run devenv update from to fetch a new source revision, or devenv update to update all inputs. Commit the lock file to give all users the same source revision.

Add target-specific YAML

The target directory can contain devenv.yaml and devenv.local.yaml for project-specific settings. devenv loads the source YAML first, so the target YAML has higher precedence. Relative input URLs in the target YAML resolve from the target directory. The source’s devenv.local.yaml can also import YAML configurations and Nix modules.

An explicit --from option does not load the target’s devenv.nix or devenv.local.nix. Without an explicit option, a local devenv.nix has priority over a saved binding.

Save profiles

Pass profiles to allow to save them with the binding:

$ devenv --from github:myorg/devenv-configs \
    --profile backend \
    --profile observability \
    allow

devenv applies these profiles to later commands. An explicit --profile option has priority over the saved profiles.

Change or remove the binding

Run allow with a different source to replace the current binding:

$ devenv --from path:../new-shared-devenv allow

Run revoke to remove the binding and its trust entry:

$ devenv revoke