.nh
.TH DIRENV 1 "2019" direnv "User Manuals"
.SH NAME
direnv \- unclutter your .profile

.SH SYNOPSIS
\fBdirenv\fR \fIcommand\fP ...

.SH DESCRIPTION
\fBdirenv\fR is an environment variable manager for your shell. It knows how to
hook into bash, zsh and fish shell to load or unload environment variables
depending on your current directory. This allows you to have project-specific
environment variables and not clutter the "~/.profile" file.

.PP
Before each prompt it checks for the existence of an \fB\&.envrc\fR file in the
current and parent directories. If the file exists, it is loaded into a bash
sub-shell and all exported variables are then captured by direnv and then made
available to your current shell, while unset variables are removed.

.PP
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, phpenv, ...

.SH EXAMPLE
.EX
$ 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
.EE

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

.SS BASH
Add the following line at the end of the \fB~/.bashrc\fR file:

.EX
eval "$(direnv hook bash)"
.EE

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

.SS ZSH
Add the following line at the end of the \fB~/.zshrc\fR file:

.EX
eval "$(direnv hook zsh)"
.EE

.SS FISH
Add the following line at the end of the \fB$XDG_CONFIG_HOME/fish/config.fish\fR file:

.EX
direnv hook fish | source
.EE

.PP
Fish supports 3 modes you can set with the global environment variable \fBdirenv_fish_mode\fR:

.EX
set -g direnv_fish_mode eval_on_arrow    # trigger direnv at prompt, and on every arrow-based directory change (default)
set -g direnv_fish_mode eval_after_arrow # trigger direnv at prompt, and only after arrow-based directory changes before executing command
set -g direnv_fish_mode disable_arrow    # trigger direnv at prompt only, this is similar functionality to the original behavior
.EE

.SS TCSH
Add the following line at the end of the \fB~/.cshrc\fR file:

.EX
eval `direnv hook tcsh`
.EE

.SS Elvish
Run:

.EX
~> mkdir -p ~/.config/elvish/lib
~> direnv hook elvish > ~/.config/elvish/lib/direnv.elv
.EE

.PP
and add the following line to your \fB~/.config/elvish/rc.elv\fR file:

.EX
use direnv
.EE

.SS PowerShell
Add the following line to your \fB$PROFILE\fR:

.EX
Invoke-Expression "$(direnv hook pwsh)"
.EE

.SS Murex
Add the following line to your \fB~/.murex_profile\fR:

.EX
direnv hook murex -> source
.EE

.SH COMMANDS
.TP
\fBdirenv allow [PATH_TO_RC]\fR
Grants direnv permission to load the given .envrc or .env file.

.TP
\fBdirenv deny [PATH_TO_RC]\fR
Revokes the authorization of a given .envrc or .env file.

.TP
\fBdirenv edit [PATH_TO_RC]\fR
Opens PATH_TO_RC or the current .envrc or .env into an $EDITOR and allow the file to be loaded afterwards.

.TP
\fBdirenv exec DIR COMMAND [...ARGS]\fR
Executes a command after loading the first .envrc or .env found in DIR.

.TP
\fBdirenv export SHELL\fR
Loads an .envrc or .env and prints the diff in terms of exports. Supported shells: bash, zsh, fish, tcsh, elvish, pwsh, murex, json, vim, gha (GitHub Actions), gzenv, systemd.

.TP
\fBdirenv fetchurl <url> [<integrity-hash>]\fR
Fetches a given URL into direnv's CAS.

.TP
\fBdirenv help\fR
Shows this help.

.TP
\fBdirenv hook SHELL\fR
Used to setup the shell hook.

.TP
\fBdirenv prune\fR
Removes old allowed files.

.TP
\fBdirenv reload\fR
Triggers an env reload.

.TP
\fBdirenv status\fR
Prints some debug status information.

.TP
\fBdirenv stdlib\fR
Displays the stdlib available in the .envrc execution context.

.TP
\fBdirenv version\fR
Prints the version or checks that direnv is older than VERSION_AT_LEAST.

.SH USAGE
In some target folder, create an \fB\&.envrc\fR file and add some export(1)
and unset(1) directives in it.

.PP
On the next prompt you will notice that direnv complains about the \fB\&.envrc\fR
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 \fBcd\fR into it.

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

.PP
Now that the environment is loaded you can notice that once you \fBcd\fR out
of the directory it automatically gets unloaded. If you \fBcd\fR back into it it's
loaded again. That's the base of the mechanism that allows you to build cool
things.

.PP
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 \fB\&.envrc\fR file.
Check the direnv-stdlib(1) man page for more details. You can also define your
own extensions inside \fB$XDG_CONFIG_HOME/direnv/direnvrc\fR or
\fB$XDG_CONFIG_HOME/direnv/lib/*.sh\fR files.

.PP
Hopefully this is enough to get you started.

.SH ENVIRONMENT
.TP
\fBXDG_CONFIG_HOME\fR
Defaults to \fB$HOME/.config\fR\&.

.TP
\fBXDG_DATA_HOME\fR
Defaults to \fB$HOME/.local/share\fR\&.

.SH FILES
.TP
\fB$XDG_CONFIG_HOME/direnv/direnv.toml\fR
Direnv configuration. See direnv.toml(1).

.TP
\fB$XDG_CONFIG_HOME/direnv/direnvrc\fR
Bash code loaded before every \fB\&.envrc\fR\&. Good for personal extensions.

.TP
\fB$XDG_CONFIG_HOME/direnv/lib/*.sh\fR
Bash code loaded before every \fB\&.envrc\fR\&. Good for third-party extensions.

.TP
\fB$XDG_DATA_HOME/direnv/allow\fR
Records which \fB\&.envrc\fR files have been \fBdirenv allow\fRed.

.SH CONTRIBUTE
Bug reports, contributions and forks are welcome.

.PP
All bugs or other forms of discussion happen on

\[la]http://github.com/direnv/direnv/issues\[ra]

.PP
There is also a wiki available where you can share your usage patterns or
other tips and tricks 
\[la]https://github.com/direnv/direnv/wiki\[ra]

.PP
Or drop by on the #direnv channel on FreeNode
\[la]irc://#direnv@FreeNode\[ra] to
have a chat.

.SH COPYRIGHT
MIT licence - Copyright (C) 2019 @zimbatm and contributors

.SH SEE ALSO
direnv-stdlib(1), direnv.toml(1), direnv-fetchurl(1)