1DIRENV-STDLIB 1 "2019" direnv "User Manuals" 2============================================ 3 4NAME 5---- 6 7direnv-stdlib - functions for the `.envrc` 8 9SYNOPSIS 10-------- 11 12`direnv stdlib` 13 14DESCRIPTION 15----------- 16 17Outputs a bash script called the *stdlib*. The following commands are included in that script and loaded in the context of an `.envrc`. In addition, it also loads the file in `~/.direnvrc` if it exists. 18 19STDLIB 20------ 21 22### `has <command>` 23 24Returns 0 if the *command* is available. Returns 1 otherwise. It can be a binary in the PATH or a shell function. 25 26Example: 27 28 if has curl; then 29 echo "Yes we do" 30 fi 31 32### `expand_path <rel_path> [<relative_to>]` 33 34Outputs the absolute path of *rel_path* relative to *relative_to* or the current directory. 35 36Example: 37 38 cd /usr/local/games 39 expand_path ../foo 40 # output: /usr/local/foo 41 42### `dotenv [<dotenv_path>]` 43 44Loads a ".env" file into the current environment. 45 46### `dotenv_if_exists [<dotenv_path>]` 47 48Loads a ".env" file into the current environment, but only if it exists. 49 50### `user_rel_path <abs_path>` 51 52Transforms an absolute path *abs_path* into a user-relative path if possible. 53 54Example: 55 56 echo $HOME 57 # output: /home/user 58 user_rel_path /home/user/my/project 59 # output: ~/my/project 60 user_rel_path /usr/local/lib 61 # output: /usr/local/lib 62 63### `find_up <filename>` 64 65Outputs the path of *filename* when searched from the current directory up to /. Returns 1 if the file has not been found. 66 67Example: 68 69 cd /usr/local/my 70 mkdir -p project/foo 71 touch bar 72 cd project/foo 73 find_up bar 74 # output: /usr/local/my/bar 75 76### `source_env <file_or_dir_path>` 77 78Loads another `.envrc` either by specifying its path or filename. 79 80NOTE: the other `.envrc` is not checked by the security framework. 81 82### `source_env_if_exists <filename>` 83 84Loads another ".envrc", but only if it exists. 85 86NOTE: contrary to `source_env`, this only works when passing a path to a file, 87 not a directory. 88 89Example: 90 91 source_env_if_exists .envrc.private 92 93### `source_up [<filename>]` 94 95Loads another `.envrc` if found when searching from the parent directory up to /. 96 97NOTE: the other `.envrc` is not checked by the security framework. 98 99### `source_url <url> <integrity-hash>` 100 101Loads another script from the given `url`. Before loading it it will check the 102integrity using the provided `integrity-hash`. 103 104To find the value of the `integrity-hash`, call `direnv fetchurl <url>` and 105extract the hash from the outputted message. 106 107See also `direnv-fetchurl(1)` for more details. 108 109### `fetchurl <url> [<integrity-hash>]` 110 111Fetches the given `url` onto disk and outputs it's path location on stdout. 112 113If the `integrity-hash` argument is provided, it will also check the integrity 114of the script. 115 116See also `direnv-fetchurl(1)` for more details. 117 118### `direnv_apply_dump <file>` 119 120Loads the output of `direnv dump` that was stored in a file. 121 122### `direnv_load [<command-generating-dump-output>]` 123 124Applies the environment generated by running *argv* 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. 125 126Example: 127 128 direnv_load opam-env exec -- direnv dump 129 130### `PATH_add <path>` 131 132Prepends the expanded *path* to the PATH environment variable. It prevents a common mistake where PATH is replaced by only the new *path*. 133 134Example: 135 136 pwd 137 # output: /home/user/my/project 138 PATH_add bin 139 echo $PATH 140 # output: /home/user/my/project/bin:/usr/bin:/bin 141 142### `MANPATH_add <path>` 143 144Prepends the expanded *path* to the MANPATH environment variable. It takes care of man-specific heuritic. 145 146### `path_add <varname> <path>` 147 148Works like `PATH_add` except that it's for an arbitrary *varname*. 149 150### `PATH_rm <pattern> [<pattern> ...]` 151 152Removes 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. 153 154Bash pattern syntax: 155 https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html 156 157Example: 158 159 echo $PATH 160 # output: /dontremove/me:/remove/me:/usr/local/bin/:... 161 PATH_rm '/remove/*' 162 echo $PATH 163 # output: /dontremove/me:/usr/local/bin/:... 164 165 166### `load_prefix <prefix_path>` 167 168Expands some common path variables for the given *prefix_path* prefix. This is useful if you installed something in the *prefix_path* using `./configure --prefix=$prefix_path && make install` and want to use it in the project. 169 170Variables set: 171 172 CPATH 173 LD_LIBRARY_PATH 174 LIBRARY_PATH 175 MANPATH 176 PATH 177 PKG_CONFIG_PATH 178 179Example: 180 181 ./configure --prefix=$HOME/rubies/ruby-1.9.3 182 make && make install 183 # Then in the .envrc 184 load_prefix ~/rubies/ruby-1.9.3 185 186 187### `semver_search <directory> <folder_prefix> <partial_version>` 188 189Search a directory for the highest version number in SemVer format (X.Y.Z). 190 191Examples: 192 193 $ tree . 194 . 195 |-- dir 196 |-- program-1.4.0 197 |-- program-1.4.1 198 |-- program-1.5.0 199 $ semver_search "dir" "program-" "1.4.0" 200 1.4.0 201 $ semver_search "dir" "program-" "1.4" 202 1.4.1 203 $ semver_search "dir" "program-" "1" 204 1.5.0 205 206### `layout <type>` 207 208A semantic dispatch used to describe common project layouts. 209 210### `layout go` 211 212Adds "$(direnv_layout_dir)/go" to the GOPATH environment variable. 213And also adds "$PWD/bin" to the PATH environment variable. 214 215### `layout julia` 216 217Sets the `JULIA_PROJECT` environment variable to the current directory. 218 219### `layout node` 220 221Adds "$PWD/node_modules/.bin" to the PATH environment variable. 222 223### `layout php` 224 225Adds "$PWD/vendor/bin" to the PATH environment variable. 226 227### `layout perl` 228 229Setup environment variables required by perl's local::lib See http://search.cpan.org/dist/local-lib/lib/local/lib.pm for more details. 230 231### `layout python [<python_exe>]` 232 233Creates and loads a virtualenv environment under `$PWD/.direnv/python-$python_version`. This forces the installation of any egg into the project's sub-folder. 234 235It's possible to specify the python executable if you want to use different versions of python (eg: `layout python python3`). 236 237Note that previously virtualenv was located under `$PWD/.direnv/virtualenv` and will be re-used by direnv if it exists. 238 239### `layout python3` 240 241A shortcut for `layout python python3` 242 243### `layout ruby` 244 245Sets the GEM_HOME environment variable to `$PWD/.direnv/ruby/RUBY_VERSION`. 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 `bundle exec` prefix. 246 247### `use <program_name> [<version>]` 248 249A semantic command dispatch intended for loading external dependencies into the environment. 250 251Example: 252 253 use_ruby() { 254 echo "Ruby $1" 255 } 256 use ruby 1.9.3 257 # output: Ruby 1.9.3 258 259### `use julia <version>` 260 261Loads the specified Julia version. You must specify a path to the directory with 262installed Julia versions using $JULIA_VERSIONS. You can optionally override the 263prefix for folders inside $JULIA_VERSIONS (default `julia-`) using $JULIA_VERSION_PREFIX. 264If no exact match for `<version>` is found a search will be performed and the latest 265version will be loaded. 266 267Examples (.envrc): 268 269 use julia 1.5.1 # loads $JULIA_VERSIONS/julia-1.5.1 270 use julia 1.5 # loads $JULIA_VERSIONS/julia-1.5.1 271 use julia master # loads $JULIA_VERSIONS/julia-master 272 273### `use rbenv` 274 275Loads rbenv which add the ruby wrappers available on the PATH. 276 277### `use nix [...]` 278 279Load environment variables from `nix-shell`. 280 281If you have a `default.nix` or `shell.nix` these will be used by default, but you can also specify packages directly (e.g `use nix -p ocaml`). 282 283See http://nixos.org/nix/manual/#sec-nix-shell 284 285### `use guix [...]` 286 287Load environment variables from `guix environment`. 288 289Any arguments given will be passed to guix environment. For example, `use guix hello` would setup an environment with the dependencies of the hello package. To create an environment including hello, the `--ad-hoc` flag is used `use guix --ad-hoc hello`. Other options include `--load` which allows loading an environment from a file. 290 291See https://www.gnu.org/software/guix/manual/html_node/Invoking-guix-environment.html 292 293### `rvm [...]` 294 295Should work just like in the shell if you have rvm installed. 296 297### `use node [<version>]`: 298 299Loads NodeJS version from a `.node-version` or `.nvmrc` file. 300 301If you specify a partial NodeJS version (i.e. `4.2`), a fuzzy match is performed and the highest matching version installed is selected. 302 303Example (.envrc): 304 305 set -e 306 use node 307 308Example (.node-version): 309 310 4.2 311 312### `use node <version>` 313 314Loads specified NodeJS version. 315 316Example (.envrc): 317 318 set -e 319 use node 4.2.2 320 321### `use vim [<vimrc_file>]` 322 323Prepends the specified vim script (or .vimrc.local by default) to the 324`DIRENV_EXTRA_VIMRC` environment variable. 325 326This variable is understood by the direnv/direnv.vim extension. When found, 327it will source it after opening files in the directory. 328 329### `watch_file <path> [<path> ...]` 330 331Adds each file to direnv's watch-list. If the file changes direnv will reload the environment on the next prompt. 332 333Example (.envrc): 334 335 watch_file Gemfile 336 337### `direnv_version <version_at_least>` 338 339Checks that the direnv version is at least old as `version_at_least`. This can 340be useful when sharing an `.envrc` and to make sure that the users are up to 341date. 342 343### `strict_env [<command> ...]` 344 345Turns on shell execution strictness. This will force the .envrc 346evaluation context to exit immediately if: 347 348- any command in a pipeline returns a non-zero exit status that is not 349 otherwise handled as part of `if`, `while`, or `until` tests, 350 return value negation (`!`), or part of a boolean (`&&` or `||`) 351 chain. 352- any variable that has not explicitly been set or declared (with 353 either `declare` or `local`) is referenced. 354 355If followed by a command-line, the strictness applies for the duration 356of the command. 357 358Example (Whole Script): 359 360 strict_env 361 has curl 362 363Example (Command): 364 365 strict_env has curl 366 367#### `unstrict_env [<command> ...]` 368 369Turns off shell execution strictness. If followed by a command-line, the 370strictness applies for the duration of the command. 371 372Example (Whole Script): 373 374 unstrict_env 375 has curl 376 377Example (Command): 378 379 unstrict_env has curl 380 381### `on_git_branch [<branch_name>]` 382 383Returns 0 if within a git repository with given `branch_name`. If no branch name 384is provided, then returns 0 when within _any_ branch. Requires the git command 385to be installed. Returns 1 otherwise. 386 387When a branch is specified, then `.git/HEAD` is watched so that entering/exiting 388a branch triggers a reload. 389 390Example (.envrc): 391 392 if on_git_branch child_changes; then 393 export MERGE_BASE_BRANCH=parent_changes 394 fi 395 396 if on_git_branch; then 397 echo "Thanks for contributing to a GitHub project!" 398 fi 399 400 401COPYRIGHT 402--------- 403 404MIT licence - Copyright (C) 2019 @zimbatm and contributors 405 406SEE ALSO 407-------- 408 409direnv(1), direnv.toml(1) 410