.nh .TH DIRENV-STDLIB 1 "2019" direnv "User Manuals" .SH NAME direnv-stdlib \- functions for the \fB\&.envrc\fR .SH SYNOPSIS \fBdirenv stdlib\fR .SH DESCRIPTION Outputs a bash script called the \fIstdlib\fP\&. The following commands are included in that script and loaded in the context of an \fB\&.envrc\fR\&. In addition, it also loads the file in \fB~/.config/direnv/direnvrc\fR if it exists. .SH STDLIB .SS \fBhas \fR 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: .EX if has curl; then echo "Yes we do" fi .EE .SS \fBexpand_path []\fR Outputs the absolute path of \fIrel_path\fP relative to \fIrelative_to\fP or the current directory. .PP Example: .EX cd /usr/local/games expand_path ../foo # output: /usr/local/foo .EE .SS \fBdotenv []\fR Loads a ".env" file into the current environment. .SS \fBdotenv_if_exists []\fR Loads a ".env" file into the current environment, but only if it exists. .SS \fBuser_rel_path \fR Transforms an absolute path \fIabs_path\fP into a user-relative path if possible. .PP Example: .EX 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 .EE .SS \fBfind_up \fR 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: .EX cd /usr/local/my mkdir -p project/foo touch bar cd project/foo find_up bar # output: /usr/local/my/bar .EE .SS \fBsource_env \fR Loads another \fB\&.envrc\fR either by specifying its path or filename. .PP NOTE: the other \fB\&.envrc\fR is not checked by the security framework. .SS \fBsource_env_if_exists \fR Loads another ".envrc", but only if it exists. .PP NOTE: contrary to \fBsource_env\fR, this only works when passing a path to a file, not a directory. .PP Example: .EX source_env_if_exists .envrc.private .EE .SS \fBenv_vars_required [ ...]\fR Logs error for every variable not present in the environment or having an empty value. .br Typically this is used in combination with source_env and source_env_if_exists. .PP Example: .EX # expect .envrc.private to provide tokens source_env .envrc.private # check presence of tokens env_vars_required GITHUB_TOKEN OTHER_TOKEN .EE .SS \fBsource_up []\fR Loads another \fB\&.envrc\fR if found with the find_up command. Returns 1 if no file is found. .PP NOTE: the other \fB\&.envrc\fR is not checked by the security framework. .SS \fBsource_up_if_exists []\fR Loads another \fB\&.envrc\fR if found with the find_up command. If one is not found, nothing happens. .PP NOTE: the other \fB\&.envrc\fR is not checked by the security framework. .SS \fBsource_url \fR Loads another script from the given \fBurl\fR\&. Before loading it will check the integrity using the provided \fBintegrity-hash\fR\&. .PP To find the value of the \fBintegrity-hash\fR, call \fBdirenv fetchurl \fR and extract the hash from the outputted message. .PP See also \fBdirenv-fetchurl(1)\fR for more details. .SS \fBfetchurl []\fR Fetches the given \fBurl\fR onto disk and outputs its path location on stdout. .PP If the \fBintegrity-hash\fR argument is provided, it will also check the integrity of the script. .PP See also \fBdirenv-fetchurl(1)\fR for more details. .SS \fBdirenv_apply_dump \fR Loads the output of \fBdirenv dump\fR that was stored in a file. .SS \fBdirenv_load []\fR 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: .EX direnv_load opam exec direnv dump .EE .SS \fBPATH_add \fR 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: .EX pwd # output: /home/user/my/project PATH_add bin echo $PATH # output: /home/user/my/project/bin:/usr/bin:/bin .EE .SS \fBMANPATH_add \fR Prepends the expanded \fIpath\fP to the MANPATH environment variable. It takes care of man-specific heuritic. .SS \fBpath_add \fR Works like \fBPATH_add\fR except that it's for an arbitrary \fIvarname\fP\&. .SS \fBPATH_rm [ ...]\fR 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: .EX echo $PATH # output: /dontremove/me:/remove/me:/usr/local/bin/:... PATH_rm '/remove/*' echo $PATH # output: /dontremove/me:/usr/local/bin/:... .EE .SS \fBload_prefix \fR 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\&./configure --prefix=$prefix_path && make install\fR and want to use it in the project. .PP Variables set: .EX CPATH LD_LIBRARY_PATH LIBRARY_PATH MANPATH PATH PKG_CONFIG_PATH .EE .PP Example: .EX \&./configure --prefix=$HOME/rubies/ruby-1.9.3 make && make install # Then in the .envrc load_prefix ~/rubies/ruby-1.9.3 .EE .SS \fBsemver_search \fR Search a directory for the highest version number in SemVer format (X.Y.Z). .PP Examples: .EX $ 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 .EE .SS \fBlayout \fR A semantic dispatch used to describe common project layouts. .SS \fBlayout go\fR Adds "$(direnv_layout_dir)/go" to the GOPATH environment variable. And also adds "$PWD/bin" to the PATH environment variable. .SS \fBlayout julia\fR Sets the \fBJULIA_PROJECT\fR environment variable to the current directory. .SS \fBlayout node\fR Adds "$PWD/node_modules/.bin" to the PATH environment variable. .SS \fBlayout opam\fR Sets environment variables from \fBopam env\fR\&. .SS \fBlayout php\fR Adds "$PWD/vendor/bin" to the PATH environment variable. .SS \fBlayout perl\fR 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 \fBlayout pipenv\fR Similar to \fBlayout python\fR, but uses Pipenv to build a virtualenv from the \fBPipfile\fR located in the same directory. The path can be overridden by the \fBPIPENV_PIPFILE\fR environment variable. .PP Note that unlike invoking Pipenv manually, this does not load environment variables from a \fB\&.env\fR file automatically. You may want to add \fBdotenv .env\fR to copy that behavior. .SS \fBlayout pyenv [ ...]\fR Similar to \fBlayout python\fR, but uses pyenv to build a virtualenv with the specified Python interpreter version. .PP Multiple versions may be specified separated by spaces; please refer to the pyenv documentation for more information. .SS \fBlayout python []\fR Creates and loads a virtualenv environment under \fB$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: \fBlayout python python3\fR). .PP Note that previously virtualenv was located under \fB$PWD/.direnv/virtualenv\fR and will be re-used by direnv if it exists. .SS \fBlayout python3\fR A shortcut for \fBlayout python python3\fR .SS \fBlayout ruby\fR Sets the GEM_HOME environment variable to \fB$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 \fBbundle exec\fR prefix. .SS \fBuse []\fR A semantic command dispatch intended for loading external dependencies into the environment. .PP Example: .EX use_ruby() { echo "Ruby $1" } use ruby 1.9.3 # output: Ruby 1.9.3 .EE .SS \fBuse julia \fR 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 \fBjulia-\fR) using $JULIA_VERSION_PREFIX. If no exact match for \fB\fR is found a search will be performed and the latest version will be loaded. .PP Examples (.envrc): .EX 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 .EE .SS \fBuse rbenv\fR Loads rbenv which add the ruby wrappers available on the PATH. .SS \fBuse nix [...]\fR Load environment variables from \fBnix-shell\fR\&. .PP If you have a \fBdefault.nix\fR or \fBshell.nix\fR these will be used by default, but you can also specify packages directly (e.g \fBuse nix -p ocaml\fR). .PP See http://nixos.org/nix/manual/#sec-nix-shell .SS \fBuse flake []\fR Load the build environment of a derivation similar to \fBnix develop\fR\&. .PP By default it will load the current folder flake.nix devShell attribute. Or pass an "installable" like "nixpkgs#hello" to load all the build dependencies of the hello package from the latest nixpkgs. .PP Note that the flakes feature is hidden behind an experimental flag, which you will have to enable on your own. Flakes is not considered stable yet. .SS \fBuse guix [...]\fR Load environment variables from \fBguix shell\fR\&. .PP Any arguments given will be passed to guix shell. For example, \fBuse guix hello\fR would setup an environment including the hello package. To create an environment with the hello dependencies, the \fB--development\fR flag is used \fBuse guix --development hello\fR\&. Other options include \fB--file\fR which allows loading an environment from a file. .PP See https://guix.gnu.org/manual/en/guix.html#Invoking-guix-shell .SS \fBrvm [...]\fR Should work just like in the shell if you have rvm installed. .SS \fBuse node []\fR: Loads the specified NodeJS version into the environment. .PP If a partial NodeJS version is passed (i.e. \fB4.2\fR), a fuzzy match is performed and the highest matching version installed is selected. .PP If no version is passed, it will look at the '.nvmrc' or '.node-version' files in the current directory if they exist. .PP Environment Variables: .IP \(bu 2 $NODE_VERSIONS (required) Points to a folder that contains all the installed Node versions. That folder must exist. .IP \(bu 2 $NODE_VERSION_PREFIX (optional) [default="node-v"] Overrides the default version prefix. .SS \fBuse vim []\fR Prepends the specified vim script (or .vimrc.local by default) to the \fBDIRENV_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 \fBwatch_file [ ...]\fR Adds each file to direnv's watch-list. If the file changes direnv will reload the environment on the next prompt. .PP Example (.envrc): .EX watch_file Gemfile .EE .SS \fBdirenv_version \fR Checks that the direnv version is at least old as \fBversion_at_least\fR\&. This can be useful when sharing an \fB\&.envrc\fR and to make sure that the users are up to date. .SS \fBstrict_env [ ...]\fR Turns on shell execution strictness. This will force the .envrc evaluation context to exit immediately if: .IP \(bu 2 any command in a pipeline returns a non-zero exit status that is not otherwise handled as part of \fBif\fR, \fBwhile\fR, or \fBuntil\fR tests, return value negation (\fB!\fR), or part of a boolean (\fB&&\fR or \fB||\fR) chain. .IP \(bu 2 any variable that has not explicitly been set or declared (with either \fBdeclare\fR or \fBlocal\fR) is referenced. .PP If followed by a command-line, the strictness applies for the duration of the command. .PP Example (Whole Script): .EX strict_env has curl .EE .PP Example (Command): .EX strict_env has curl .EE .SS \fBunstrict_env [ ...]\fR Turns off shell execution strictness. If followed by a command-line, the strictness applies for the duration of the command. .PP Example (Whole Script): .EX unstrict_env has curl .EE .PP Example (Command): .EX unstrict_env has curl .EE .SS \fBon_git_branch []\fR Returns 0 if within a git repository with given \fBbranch_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\&.git/HEAD\fR is watched so that entering/exiting a branch triggers a reload. .PP Example (.envrc): .EX 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 .EE .SH COPYRIGHT MIT licence - Copyright (C) 2019 @zimbatm and contributors .SH SEE ALSO direnv(1), direnv.toml(1)