.nh
.TH DIRENV\-STDLIB 1 "2019" direnv "User Manuals"
.SH NAME
.PP
direnv\-stdlib \- functions for the \fB\fC\&.envrc\fR

.SH SYNOPSIS
.PP
\fB\fCdirenv stdlib\fR

.SH DESCRIPTION
.PP
Outputs a bash script called the \fIstdlib\fP\&. The following commands are included in that script and loaded in the context of an \fB\fC\&.envrc\fR\&. In addition, it also loads the file in \fB\fC\~/.direnvrc\fR if it exists.

.SH STDLIB
.SS \fB\fChas <command>\fR
.PP
Returns 0 if the \fIcommand\fP is available. Returns 1 otherwise. It can be a binary in the PATH or a shell function.

.PP
Example:

.PP
.RS

.nf
if has curl; then
  echo "Yes we do"
fi

.fi
.RE

.SS \fB\fCexpand\_path <rel\_path> [<relative\_to>]\fR
.PP
Outputs the absolute path of \fIrel\_path\fP relative to \fIrelative\_to\fP or the current directory.

.PP
Example:

.PP
.RS

.nf
cd /usr/local/games
expand\_path ../foo
# output: /usr/local/foo

.fi
.RE

.SS \fB\fCdotenv [<dotenv\_path>]\fR
.PP
Loads a ".env" file into the current environment

.SS \fB\fCuser\_rel\_path <abs\_path>\fR
.PP
Transforms an absolute path \fIabs\_path\fP into a user\-relative path if possible.

.PP
Example:

.PP
.RS

.nf
echo $HOME
# output: /home/user
user\_rel\_path /home/user/my/project
# output: \~/my/project
user\_rel\_path /usr/local/lib
# output: /usr/local/lib

.fi
.RE

.SS \fB\fCfind\_up <filename>\fR
.PP
Outputs the path of \fIfilename\fP when searched from the current directory up to /. Returns 1 if the file has not been found.

.PP
Example:

.PP
.RS

.nf
cd /usr/local/my
mkdir \-p project/foo
touch bar
cd project/foo
find\_up bar
# output: /usr/local/my/bar

.fi
.RE

.SS \fB\fCsource\_env <file\_or\_dir\_path>\fR
.PP
Loads another \fB\fC\&.envrc\fR either by specifying its path or filename.

.PP
NOTE: the other \fB\fC\&.envrc\fR is not checked by the security framework.

.SS \fB\fCsource\_env\_if\_exists <filename>\fR
.PP
Loads another ".envrc", but only if it exists.

.PP
NOTE: contrary to \fB\fCsource\_env\fR, this only works when passing a path to a file,
      not a directory.

.PP
Example:

.PP
.RS

.nf
source\_env\_if\_exists .envrc.private

.fi
.RE

.SS \fB\fCsource\_up [<filename>]\fR
.PP
Loads another \fB\fC\&.envrc\fR if found when searching from the parent directory up to /.

.PP
NOTE: the other \fB\fC\&.envrc\fR is not checked by the security framework.

.SS \fB\fCsource\_url <url> <integrity\-hash>\fR
.PP
Loads another script from the given \fB\fCurl\fR\&. Before loading it it will check the
integrity using the provided \fB\fCintegrity\-hash\fR\&.

.PP
To find the value of the \fB\fCintegrity\-hash\fR, call \fB\fCdirenv fetchurl <url>\fR and
extract the hash from the outputted message.

.PP
See also \fB\fCdirenv\-fetchurl(1)\fR for more details.

.SS \fB\fCfetchurl <url> [<integrity\-hash>]\fR
.PP
Fetches the given \fB\fCurl\fR onto disk and outputs it's path location on stdout.

.PP
If the \fB\fCintegrity\-hash\fR argument is provided, it will also check the integrity
of the script.

.PP
See also \fB\fCdirenv\-fetchurl(1)\fR for more details.

.SS \fB\fCdirenv\_apply\_dump <file>\fR
.PP
Loads the output of \fB\fCdirenv dump\fR that was stored in a file.

.SS \fB\fCdirenv\_load [<command\-generating\-dump\-output>]\fR
.PP
Applies the environment generated by running \fIargv\fP as a command. This is useful for adopting the environment of a child process \- cause that process to run "direnv dump" and then wrap the results with direnv\_load.

.PP
Example:

.PP
.RS

.nf
direnv\_load opam\-env exec \-\- direnv dump

.fi
.RE

.SS \fB\fCPATH\_add <path>\fR
.PP
Prepends the expanded \fIpath\fP to the PATH environment variable. It prevents a common mistake where PATH is replaced by only the new \fIpath\fP\&.

.PP
Example:

.PP
.RS

.nf
pwd
# output: /home/user/my/project
PATH\_add bin
echo $PATH
# output: /home/user/my/project/bin:/usr/bin:/bin

.fi
.RE

.SS \fB\fCMANPATH\_add <path>\fR
.PP
Prepends the expanded \fIpath\fP to the MANPATH environment variable. It takes care of man\-specific heuritic.

.SS \fB\fCpath\_add <varname> <path>\fR
.PP
Works like \fB\fCPATH\_add\fR except that it's for an arbitrary \fIvarname\fP\&.

.SS \fB\fCPATH\_rm <pattern> [<pattern> ...]\fR
.PP
Removes directories that match any of the given shell patterns from the PATH environment variable. Order of the remaining directories is preserved in the resulting PATH.

.PP
Bash pattern syntax:
  https://www.gnu.org/software/bash/manual/html\_node/Pattern\-Matching.html

.PP
Example:

.PP
.RS

.nf
echo $PATH
# output: /dontremove/me:/remove/me:/usr/local/bin/:...
PATH\_rm '/remove/*'
echo $PATH
# output: /dontremove/me:/usr/local/bin/:...

.fi
.RE

.SS \fB\fCload\_prefix <prefix\_path>\fR
.PP
Expands some common path variables for the given \fIprefix\_path\fP prefix. This is useful if you installed something in the \fIprefix\_path\fP using \fB\fC\&./configure \-\&\-\&prefix=$prefix\_\&path \&\&\&\& make install\fR and want to use it in the project.

.PP
Variables set:

.PP
.RS

.nf
CPATH
LD\_LIBRARY\_PATH
LIBRARY\_PATH
MANPATH
PATH
PKG\_CONFIG\_PATH

.fi
.RE

.PP
Example:

.PP
.RS

.nf
\&./configure \-\&\-\&prefix=$HOME/rubies/ruby\-\&1.9.3
make \&\&\&\& make install
# Then in the .envrc
load\_\&prefix \~\&/rubies/ruby\-\&1.9.3

.fi
.RE

.SS \fB\fCsemver\_search <directory> <folder\_prefix> <partial\_version>\fR
.PP
Search a directory for the highest version number in SemVer format (X.Y.Z).

.PP
Examples:

.PP
.RS

.nf
$ tree .
.
|\-\- dir
    |\-\- program\-1.4.0
    |\-\- program\-1.4.1
    |\-\- program\-1.5.0
$ semver\_search "dir" "program\-" "1.4.0"
1.4.0
$ semver\_search "dir" "program\-" "1.4"
1.4.1
$ semver\_search "dir" "program\-" "1"
1.5.0

.fi
.RE

.SS \fB\fClayout <type>\fR
.PP
A semantic dispatch used to describe common project layouts.

.SS \fB\fClayout go\fR
.PP
Adds "$(direnv\_layout\_dir)/go" to the GOPATH environment variable.
And also adds "$PWD/bin" to the PATH environment variable.

.SS \fB\fClayout julia\fR
.PP
Sets the \fB\fCJULIA\_PROJECT\fR environment variable to the current directory.

.SS \fB\fClayout node\fR
.PP
Adds "$PWD/node\_modules/.bin" to the PATH environment variable.

.SS \fB\fClayout php\fR
.PP
Adds "$PWD/vendor/bin" to the PATH environment variable.

.SS \fB\fClayout perl\fR
.PP
Setup environment variables required by perl's local::lib See http://search.cpan.org/dist/local\-lib/lib/local/lib.pm for more details.

.SS \fB\fClayout python [<python\_exe>]\fR
.PP
Creates and loads a virtualenv environment under \fB\fC$PWD/.direnv/python\-$python\_version\fR\&. This forces the installation of any egg into the project's sub\-\&folder.

.PP
It's possible to specify the python executable if you want to use different versions of python (eg: \fB\fClayout python python3\fR).

.PP
Note that previously virtualenv was located under \fB\fC$PWD/.direnv/virtualenv\fR and will be re\-used by direnv if it exists.

.SS \fB\fClayout python3\fR
.PP
A shortcut for \fB\fClayout python python3\fR

.SS \fB\fClayout ruby\fR
.PP
Sets the GEM\_HOME environment variable to \fB\fC$PWD/.direnv/ruby/RUBY\_VERSION\fR\&. This forces the installation of any gems into the project's sub\-\&folder. If you're using bundler it will create wrapper programs that can be invoked directly instead of using the \fB\fCbundle exec\fR prefix.

.SS \fB\fCuse <program\_name> [<version>]\fR
.PP
A semantic command dispatch intended for loading external dependencies into the environment.

.PP
Example:

.PP
.RS

.nf
use\_ruby() {
  echo "Ruby $1"
}
use ruby 1.9.3
# output: Ruby 1.9.3

.fi
.RE

.SS \fB\fCuse julia <version>\fR
.PP
Loads the specified Julia version. You must specify a path to the directory with
installed Julia versions using $JULIA\_VERSIONS. You can optionally override the
prefix for folders inside $JULIA\_VERSIONS (default \fB\fCjulia\-\fR) using $JULIA\_VERSION\_PREFIX.
If no exact match for \fB\fC<version>\fR is found a search will be performed and the latest
version will be loaded.

.PP
Examples (.envrc):

.PP
.RS

.nf
use julia 1.5.1   # loads $JULIA\_VERSIONS/julia\-1.5.1
use julia 1.5     # loads $JULIA\_VERSIONS/julia\-1.5.1
use julia master  # loads $JULIA\_VERSIONS/julia\-master

.fi
.RE

.SS \fB\fCuse rbenv\fR
.PP
Loads rbenv which add the ruby wrappers available on the PATH.

.SS \fB\fCuse nix [...]\fR
.PP
Load environment variables from \fB\fCnix\-shell\fR\&.

.PP
If you have a \fB\fCdefault.nix\fR or \fB\fCshell.nix\fR these will be used by default, but you can also specify packages directly (e.g \fB\fCuse nix \-p ocaml\fR).

.PP
See http://nixos.org/nix/manual/#sec\-nix\-shell

.SS \fB\fCuse guix [...]\fR
.PP
Load environment variables from \fB\fCguix environment\fR\&.

.PP
Any arguments given will be passed to guix environment. For example, \fB\fCuse guix hello\fR would setup an environment with the dependencies of the hello package. To create an environment including hello, the \fB\fC\-\-ad\-hoc\fR flag is used \fB\fCuse guix \-\-ad\-hoc hello\fR\&. Other options include \fB\fC\-\-load\fR which allows loading an environment from a file.

.PP
See https://www.gnu.org/software/guix/manual/html\_node/Invoking\-guix\-environment.html

.SS \fB\fCrvm [...]\fR
.PP
Should work just like in the shell if you have rvm installed.

.SS \fB\fCuse node [<version>]\fR:
.PP
Loads NodeJS version from a \fB\fC\&.node\-\&version\fR or \fB\fC\&.nvmrc\fR file.

.PP
If you specify a partial NodeJS version (i.e. \fB\fC4.2\fR), a fuzzy match is performed and the highest matching version installed is selected.

.PP
Example (.envrc):

.PP
.RS

.nf
set \-e
use node

.fi
.RE

.PP
Example (.node\-version):

.PP
.RS

.nf
4.2

.fi
.RE

.SS \fB\fCuse node <version>\fR
.PP
Loads specified NodeJS version.

.PP
Example (.envrc):

.PP
.RS

.nf
set \-e
use node 4.2.2

.fi
.RE

.SS \fB\fCuse vim [<vimrc\_file>]\fR
.PP
Prepends the specified vim script (or .vimrc.local by default) to the
\fB\fCDIRENV\_EXTRA\_VIMRC\fR environment variable.

.PP
This variable is understood by the direnv/direnv.vim extension. When found,
it will source it after opening files in the directory.

.SS \fB\fCwatch\_file <path> [<path> ...]\fR
.PP
Adds each file to direnv's watch\-list. If the file changes direnv will reload the environment on the next prompt.

.PP
Example (.envrc):

.PP
.RS

.nf
watch\_file Gemfile

.fi
.RE

.SS \fB\fCdirenv\_version <version\_at\_least>\fR
.PP
Checks that the direnv version is at least old as \fB\fCversion\_at\_least\fR\&. This can
be useful when sharing an \fB\fC\&.envrc\fR and to make sure that the users are up to
date.

.SS \fB\fCstrict\_env [<command> ...]\fR
.PP
Turns on shell execution strictness. This will force the .envrc
evaluation context to exit immediately if:

.RS
.IP \(bu 2
any command in a pipeline returns a non\-zero exit status that is not
otherwise handled as part of \fB\fCif\fR, \fB\fCwhile\fR, or \fB\fCuntil\fR tests,
return value negation (\fB\fC!\fR), or part of a boolean (\fB\fC\&\&\fR or \fB\fC||\fR)
chain.
.IP \(bu 2
any variable that has not explicitly been set or declared (with
either \fB\fCdeclare\fR or \fB\fClocal\fR) is referenced.

.RE

.PP
If followed by a command\-line, the strictness applies for the duration
of the command.

.PP
Example (Whole Script):

.PP
.RS

.nf
strict\_env
has curl

.fi
.RE

.PP
Example (Command):

.PP
.RS

.nf
strict\_env has curl

.fi
.RE

.SS \fB\fCunstrict\_env [<command> ...]\fR
.PP
Turns off shell execution strictness. If followed by a command\-line, the
strictness applies for the duration of the command.

.PP
Example (Whole Script):

.PP
.RS

.nf
unstrict\_env
has curl

.fi
.RE

.PP
Example (Command):

.PP
.RS

.nf
unstrict\_env has curl

.fi
.RE

.SS \fB\fCon\_git\_branch [<branch\_name>]\fR
.PP
Returns 0 if within a git repository with given \fB\fCbranch\_name\fR\&. If no branch name
is provided, then returns 0 when within \fIany\fP branch. Requires the git command
to be installed. Returns 1 otherwise.

.PP
When a branch is specified, then \fB\fC\&.git/HEAD\fR is watched so that entering/exiting
a branch triggers a reload.

.PP
Example (.envrc):

.PP
.RS

.nf
if on\_git\_branch child\_changes; then
  export MERGE\_BASE\_BRANCH=parent\_changes
fi

if on\_git\_branch; then
  echo "Thanks for contributing to a GitHub project!"
fi

.fi
.RE

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

.SH SEE ALSO
.PP
direnv(1), direnv.toml(1)