asdf-direnv
direnv plugin for asdf version manager
Build History
Motivation (or shims de-motivation)
asdf version resolution is slow which makes every command execution pay that penalty. asdf reshim is needed for finding new executables, and some tools are not happy with their executables being masked by shims.
[asdf](https://asdf-vm.com) is a great tool for managing multiple versions of
command-line tools. 99% of the time these managed tools work just as expected.
Shims are just tiny wrappers created by asdf that just forward execution to the
_real_ versioned executables installed by asdf. This way, asdf has a single
shims directory added to your PATH and has no need of mangling the PATH for
every installed version.
When you run an asdf-managed command, like `node`, it will actually execute an
asdf-shim, which will determine the `node` version to activate according to your
`.tool-versions` file.
A downside of this is that every single time you run `node` asdf will have to
determine again which version to use. Even if you haven't changed your
`.tool-versions` file to upgrade the node version to use. And this happens for
every shim execution, which could lead to some users experiencing certain
_slowness_ while asdf is looking up versions, since it has to traverse
directories looking up for a .tool-versions file and probably also legacy
version files.
Another inconvenience is that commands installed by these tools can have some
problems by the way asdf shims work. For example, if a command tries to find
itself by name in PATH (e.g. using `which my-command`) it will find the asdf
shim executable and not the _actual_ executable delegated-to by asdf. This might
cause problems if the command tries to use this location as an installation root
to find auxiliary files, since shims will mask the real executable.
Also, people frequently ask why is reshim needed. Suppose you used asdf to
install a package manager like `npm`, `hex`, `gem`, `cargo`, etc. Any new
binaries installed by these tools won't be available on PATH unless you run
`asdf reshim`. This is because asdf has no way of knowing what the `npm install`
command does, and it's until `asdf reshim` that it will figure out new
executables are available and will create shims for them accordingly.
And finally, some packages come not only with language-specific commands, but
with tons of system tools that will shadow those already installed on your
system. While this may be desirable while the language is in use, having it
installed and not activated leaves dead shims all over the place.
Solution
Perform asdf version resolution only once and defer environment loading to direnv.
All these previously mentioned issues can be solved by using asdf along with the
[direnv](https://direnv.net/) tool.
Just like asdf is a tools manager, direnv is an environment-variables manager.
It can update your shell env upon directory change and clean it up when you
leave that directory.
This `asdf-direnv` plugin lets you install `direnv` and also provides a tiny
script to integrate both. Allowing `direnv` to manage any variables exposed by
asdf tools, primarily the PATH environment, but also any other variable exposed
by your plugin (e.g. MIX_HOME exposed by the asdf-elixir plugin).
This way, running `node` will not invoke the asdf-shim but the _real_
asdf-managed executable in PATH. Which will improve speed since version
resolution is out of the way and made only once by `direnv` upon entering your
project directory. Commands trying to find themselves in PATH will find their
expected location. Also, no more _reshim_ needed upon `npm install`.
Prerequirements
- Make sure you have the required dependencies installed:
- curl
- git
Usage
Setup
Install this plugin and run the setup command for all of your preferred shells bash/fish/zsh.
asdf plugin-add direnv
asdf direnv setup --shell bash --version latestIf you already have a direnv installation, you can specify --version system.
Otherwise this plugin can install it for you. Specify either --version latest
or a direnv release as shown by asdf list-all direnv.
The setup will hint which files were modified, you might want to review its changes. After setup, close and open your terminal.
Configuration
By default asdf-direnv will fail if a plugin is not installed, but is possible
to change this using the environment variable
ASDF_DIRENV_IGNORE_MISSING_PLUGINS=1
Per-Project Environments
Once direnv is hooked into your system, use the asdf direnv local
command on your project root directory to update your environment.
asdf direnv local [<tool> <version>]...Temporary environments for one-shot commands
Some times you just want to execute a one-shot commmand under certain
environment without creating/modifying .envrc and .tool-versions files
on your project directory. In those cases, you might want to try using
asdf direnv shell.
# Enter a new shell having python and node
$ asdf direnv shell python 3.8.10 nodejs 14.18.2
# Just execute a npx command under some node version.
$ asdf direnv shell nodejs 14.18.2 -- npx create-react-appUpdating
Updating this plugin is the same as any asdf plugin:
asdf plugin update direnv
Updating the version of direnv you use depends on which installation method you've chosen:
- `system`: Nothing special required here, whenever your system package manager
updates direnv, this plugin will use the updated version.
- `latest` or `Cached environment
To speed up things a lot, this plugin creates direnv `envrc` files that contain
your tools environment. They are created automatically whenever your `.envrc` or your
`.tool-versions` files change.
Cached environment files can be found under `$XDG_CACHE_HOME/asdf-direnv/env`.
On most systems that resolves to `~/.config/asdf-direnv/env`. It's always safe to
remove files on this directory since they will be re-generated if missing.
If you ever need to regenerate a cached environment file, just `touch .envrc`.
Also, the `asdf direnv envrc` command will print the path to the cached environment
file used for your project.
Now when you leave your project directory and come back to it, direnv will
manage the environment variables for you really fast. For example:
```bash
direnv: loading .envrc
direnv: using asdf
direnv: Creating env file ~/.cache/asdf-direnv/env/909519368-2773408541-1591703797-361987458
direnv: loading ~/.cache/asdf-direnv/env/909519368-2773408541-1591703797-361987458
direnv: using asdf elixir 1.8.1-otp-21
direnv: using asdf nodejs 12.6.0
direnv: export +MIX_ARCHIVES +MIX_HOME +NPM_CONFIG_PREFIX ~PATH
```
Benchmark
#### `node --version`
with asdf-direnv:
| Mean [ms] | Min [ms] | Max [ms] | Relative |
| --------: | -------: | -------: | -------: |
| 4.3 ± 0.4 | 3.6 | 6.0 | 1.00 |
without asdf-direnv:
| Mean [ms] | Min [ms] | Max [ms] | Relative |
| ----------: | -------: | -------: | -------: |
| 189.7 ± 2.7 | 185.6 | 194.0 | 1.00 |
```bash
hyperfine 'node --version'
```
---
#### `npm install -g yarn`
with asdf-direnv:
| Mean [ms] | Min [ms] | Max [ms] | Relative |
| -----------: | -------: | -------: | -------: |
| 683.3 ± 17.3 | 667.9 | 725.1 | 1.00 |
without asdf-direnv:
| Mean [ms] | Min [ms] | Max [ms] | Relative |
| -----------: | -------: | -------: | -------: |
| 870.0 ± 12.9 | 848.4 | 894.6 | 1.00 |
```bash
hyperfine --cleanup 'npm uninstall -g yarn' 'npm install -g yarn'
```
Pro-Tips
- Take a look at `direnv help true`.
- Getting `$ASDF_DIR/shims` out of the PATH.
Some users might want to bypass asdf shims altogether. To do so,
include only `$ASDF_DIR/bin` in your PATH but exclude the shims
directory.
All shims are still available via `asdf exec Useful links
Read direnv documentation for more on .envrc.
If you are willing to contribute, be sure to read our CONTRIBUTING guide.
License
Licensed under the Apache License, Version 2.0.