Skip to content
unclutter your .profile
Branch: master
Clone or download
jonas-schievink and zimbatm Use `fish_preexec` hook instead of `fish_prompt` (#512)
This is more reliable, as `fish_prompt` could miss changing directories with Alt+Left/Right. It also runs when pressing enter on an empty shell, so as far as I can tell it's a superset of `fish_prompt`.
Latest commit 5665299 Jul 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE github: fix the issue templates Jun 7, 2019
ci Release v2.20.1 (#486) Mar 31, 2019
docs Add manpage for config.toml. (#337) Feb 20, 2018
gzenv move gzenv into new package Nov 5, 2018
man rename the configuration to direnv.toml (#498) May 21, 2019
nix nix: pin nixpkgs Mar 31, 2019
script make: handle when /dev/stderr doesn't exist (#491) Apr 6, 2019
test test: fix shellcheck warnings Mar 31, 2019
vendor/github.com update dependencies (#433) Dec 27, 2018
.gitignore Overhaul the build system (#375) Jul 8, 2018
.nojekyll New site: put the doc inside the project so it stays in sync Jun 12, 2014
CHANGELOG.md Release v2.20.1 (#486) Mar 31, 2019
CNAME New site: put the doc inside the project so it stays in sync Jun 12, 2014
GNUmakefile make: handle when /dev/stderr doesn't exist (#491) Apr 6, 2019
Gopkg.lock update dependencies (#433) Dec 27, 2018
Gopkg.toml use the new `dep` tool to manage dependencies Sep 7, 2017
LICENSE.md Update repo urls to point to the new org Jun 27, 2015
README.md ci: replace Travis CI with Azure Pipelines Mar 31, 2019
azure-pipelines.yml ci: only release on master Apr 2, 2019
cmd_allow.go config: introduce warn_timeout Apr 2, 2019
cmd_apply_dump.go config: introduce warn_timeout Apr 2, 2019
cmd_current.go config: introduce warn_timeout Apr 2, 2019
cmd_deny.go config: introduce warn_timeout Apr 2, 2019
cmd_dotenv.go config: introduce warn_timeout Apr 2, 2019
cmd_dump.go config: introduce warn_timeout Apr 2, 2019
cmd_edit.go config: introduce warn_timeout Apr 2, 2019
cmd_exec.go direnv exec: DIR is always necessary (#493) Apr 18, 2019
cmd_expand_path.go config: introduce warn_timeout Apr 2, 2019
cmd_export.go config: introduce warn_timeout Apr 2, 2019
cmd_help.go config: introduce warn_timeout Apr 2, 2019
cmd_hook.go config: introduce warn_timeout Apr 2, 2019
cmd_prune.go config: introduce warn_timeout Apr 2, 2019
cmd_reload.go config: introduce warn_timeout Apr 2, 2019
cmd_show_dump.go config: introduce warn_timeout Apr 2, 2019
cmd_status.go config: introduce warn_timeout Apr 2, 2019
cmd_stdlib.go config: introduce warn_timeout Apr 2, 2019
cmd_version.go config: introduce warn_timeout Apr 2, 2019
cmd_watch.go config: introduce warn_timeout Apr 2, 2019
commands.go config: introduce warn_timeout Apr 2, 2019
config.go rename the configuration to direnv.toml (#498) May 21, 2019
const.go stdlib: add DIRENV_IN_ENVRC (#414) Nov 22, 2018
default.nix nix: pin nixpkgs Mar 31, 2019
env.go move gzenv into new package Nov 5, 2018
env_diff.go stdlib: add DIRENV_IN_ENVRC (#414) Nov 22, 2018
env_diff_test.go Fix `go vet` warnings Jun 21, 2016
env_test.go Fix `go vet` warnings Jun 21, 2016
file_times.go file_times: check Stat and Lstat (#457) Feb 9, 2019
file_times_test.go File times impl working, tested Mar 10, 2016
index.html website: update ditto to v0.15 Dec 8, 2017
log.go Only output color if $TERM is not dumb (#264) Mar 24, 2017
look_path.go Try to detect an editor in the PATH if EDITOR is not set. Jun 15, 2014
main.go Build-time bash path Apr 4, 2016
rc.go export: always output something Mar 31, 2019
rc_test.go If two paths don't have a common ancestors, don't make them relative. Feb 28, 2014
shell.go add a new "gzenv" shell Nov 5, 2018
shell.nix nix: pin nixpkgs Mar 31, 2019
shell_bash.go Fix bash hook (#473) Mar 8, 2019
shell_elvish.go fixup! fix arity mismatch for elvish (#482) Mar 29, 2019
shell_fish.go Use `fish_preexec` hook instead of `fish_prompt` (#512) Jul 12, 2019
shell_gzenv.go add a new "gzenv" shell Nov 5, 2018
shell_json.go shell: introduce a dump capability Nov 5, 2018
shell_tcsh.go shell: introduce a dump capability Nov 5, 2018
shell_test.go refactor shells Mar 26, 2016
shell_vim.go shell: introduce a dump capability Nov 5, 2018
shell_zsh.go shell: introduce a dump capability Nov 5, 2018
stdlib.go Handle failing pipenv on empty file and avoid an extra pipenv executi… Jul 3, 2019
stdlib.sh Handle failing pipenv on empty file and avoid an extra pipenv executi… Jul 3, 2019
version.go Release v2.20.1 (#486) Mar 31, 2019
version.txt Release v2.20.1 (#486) Mar 31, 2019
xdg.go Still WIP but approaching a workable state Feb 7, 2013

README.md

direnv -- Unclutter your .profile

Built with Nix Build Status direnv is an environment switcher for the shell. It knows how to hook into bash, zsh, tcsh, fish shell and elvish to load or unload environment variables depending on the current directory. This allows project-specific environment variables without cluttering the ~/.profile file.

Before each prompt, direnv checks for the existence of a ".envrc" file in the current and parent directories. If the file exists (and is authorized), it is loaded into a bash sub-shell and all exported variables are then captured by direnv and then made available to the current shell.

Because direnv is compiled into a single static executable, it is fast enough to be unnoticeable on each prompt. It is also language-agnostic and can be used to build solutions similar to rbenv, pyenv and phpenv.

Example

$ cd ~/my_project
$ echo ${FOO-nope}
nope
$ echo export FOO=foo > .envrc
.envrc is not allowed
$ direnv allow .
direnv: reloading
direnv: loading .envrc
direnv export: +FOO
$ echo ${FOO-nope}
foo
$ cd ..
direnv: unloading
direnv export: ~PATH
$ echo ${FOO-nope}
nope

Install

From system packages

direnv is packaged for a variety of systems:

See also:

Packaging status

From binary builds

Binary builds for a variety of architectures are also available for each release.

Fetch the binary, chmod +x direnv and put it somewhere in your PATH.

Compile from source

Setup go environment https://golang.org/doc/install

go >= 1.9 is required

Clone project:

$ git clone git@github.com:direnv/direnv.git

Build by just typing make:

$ cd direnv
$ make

To install to /usr/local:

$ make install

Or to a different location like ~/.local:

$ make install DESTDIR=~/.local

Setup

For direnv to work properly it needs to be hooked into the shell. Each shell has its own extension mechanism:

BASH

Add the following line at the end of the ~/.bashrc file:

eval "$(direnv hook bash)"

Make sure it appears even after rvm, git-prompt and other shell extensions that manipulate the prompt.

ZSH

Add the following line at the end of the ~/.zshrc file:

eval "$(direnv hook zsh)"

FISH

Add the following line at the end of the ~/.config/fish/config.fish file:

direnv hook fish | source

TCSH

Add the following line at the end of the ~/.cshrc file:

eval `direnv hook tcsh`

Elvish (0.12+)

Run:

$> direnv hook elvish > ~/.elvish/lib/direnv.elv

and add the following line to your ~/.elvish/rc.elv file:

use direnv

Usage

In some target folder, create a ".envrc" file and add some export(1) directives in it.

Note that the contents of the .envrc file must be valid bash syntax, regardless of the shell you are using. This is because direnv always executes the .envrc with bash (a sort of lowest common denominator of UNIX shells) so that direnv can work across shells. If you try to use some syntax that doesn't work in bash (like zsh's nested expansions), you will run into trouble.

On the next prompt you will notice that direnv complains about the ".envrc" being blocked. This is the security mechanism to avoid loading new files automatically. Otherwise any git repo that you pull, or tar archive that you unpack, would be able to wipe your hard drive once you cd into it.

So here we are pretty sure that it won't do anything bad. Type direnv allow . and watch direnv loading your new environment. Note that direnv edit . is a handy shortcut that opens the file in your $EDITOR and automatically allows it if the file's modification time has changed.

Now that the environment is loaded, you will notice that once you cd out of the directory it automatically gets unloaded. If you cd back into it, it's loaded again. That's the basis of the mechanism that allows you to build cool things.

The stdlib

Exporting variables by hand is a bit repetitive so direnv provides a set of utility functions that are made available in the context of the ".envrc" file.

As an example, the PATH_add function is used to expand and prepend a path to the $PATH environment variable. Instead of export $PATH=$PWD/bin:$PATH you can write PATH_add bin. It's shorter and avoids a common mistake where $PATH=bin.

To find the documentation for all available functions check the direnv-stdlib(1) man page.

It's also possible to create your own extensions by creating a bash file at ~/.config/direnv/direnvrc or ~/.direnvrc. This file is loaded before your ".envrc" and thus allows you to make your own extensions to direnv.

Loading layered .envrc

NOTE: the authorization framework doesn't apply here and all the .envrc will be loaded without verification

Let's say you have the following structure:

  • "/a/.envrc"
  • "/a/b/.envrc"

If you add the following line in "/a/b/.envrc", you can load both of the ".envrc" files when you are in /a/b:

source_env ..

In the general case source_up will load any .envrc higher up in the folder structure. This allows you to truly enable arbitrary hierarchical stuctures of .envrc usage.

source_up

Common things people don't know

Based on GitHub issues interactions, here are the top things that have been confusing for users:

  1. direnv has a standard library of functions, a collection of utilities that I found useful to have and accumulated over the years. If you know how to read bash, you can find it here: https://github.com/direnv/direnv/blob/master/stdlib.sh

  2. It's possible to override the stdlib with your own set of function by adding a bash file to either ~/.config/direnv/direnvrc or ~/.direnvrc. These will become available to all your .envrc files.

  3. direnv is actually creating a new bash process to load the stdlib, direnvrc and .envrc, and only exports the environment diff back to the original shell. This allows direnv to record the environment changes accurately and also work with all sorts of shells. It also means that aliases and functions are not exportable right now.

Similar projects

  • Environment Modules - one of the oldest (in a good way) environment-loading systems
  • autoenv - lightweight; doesn't support unloads
  • zsh-autoenv - a feature-rich mixture of autoenv and smartcd: enter/leave events, nesting, stashing (Zsh-only).
  • asdf - a pure bash solution that has a plugin system

Contribute

Bug reports, contributions and forks are welcome.

All bugs or other forms of discussion happen on http://github.com/direnv/direnv/issues.

There is a wiki available where you can share your usage patterns or other tips and tricks https://github.com/direnv/direnv/wiki

For longer form discussions you can also write to mailto:direnv-discuss@googlegroups.com

Or drop by on IRC (#direnv on freenode) to have a chat. If you ask a question make sure to stay around as not everyone is active all day.

COPYRIGHT

Copyright (C) 2014 shared by all contributors under the MIT licence.

You can’t perform that action at this time.