1DIRENV-STDLIB(1) User Manuals DIRENV-STDLIB(1)
2
6 direnv-stdlib - functions for the .envrc
7
10 direnv stdlib
11
14 Outputs a bash script called the stdlib. The following commands are in‐
15 cluded in that script and loaded in the context of an .envrc. In addi‐
16 tion, it also loads the file in ~/.config/direnv/direnvrc if it exists.
17
20 has <command>
21 Returns 0 if the command is available. Returns 1 otherwise. It can be a
22 binary in the PATH or a shell function.
23 Example:
26 if has curl; then
29 echo "Yes we do"
30 fi
31 expand_path <rel_path> [<relative_to>]
35 Outputs the absolute path of rel_path relative to relative_to or the
36 current directory.
37 Example:
40 cd /usr/local/games
43 expand_path ../foo
44 # output: /usr/local/foo
45 dotenv [<dotenv_path>]
49 Loads a ".env" file into the current environment.
50 dotenv_if_exists [<dotenv_path>]
53 Loads a ".env" file into the current environment, but only if it ex‐
54 ists.
55 user_rel_path <abs_path>
58 Transforms an absolute path abs_path into a user-relative path if pos‐
59 sible.
60 Example:
63 echo $HOME
66 # output: /home/user
67 user_rel_path /home/user/my/project
68 # output: ~/my/project
69 user_rel_path /usr/local/lib
70 # output: /usr/local/lib
71 find_up <filename>
75 Outputs the path of filename when searched from the current directory
76 up to /. Returns 1 if the file has not been found.
77 Example:
80 cd /usr/local/my
83 mkdir -p project/foo
84 touch bar
85 cd project/foo
86 find_up bar
87 # output: /usr/local/my/bar
88 source_env <file_or_dir_path>
92 Loads another .envrc either by specifying its path or filename.
93 NOTE: the other .envrc is not checked by the security framework.
96 source_env_if_exists <filename>
99 Loads another ".envrc", but only if it exists.
100 NOTE: contrary to source_env, this only works when passing a path to a
103 file,
104 not a directory.
105 Example:
108 source_env_if_exists .envrc.private
111 env_vars_required <varname> [<varname> ...]
115 Logs error for every variable not present in the environment or having
116 an empty value.
117 Typically this is used in combination with source_env and
118 source_env_if_exists.
119 Example:
122 # expect .envrc.private to provide tokens
125 source_env .envrc.private
126 # check presence of tokens
127 env_vars_required GITHUB_TOKEN OTHER_TOKEN
128 source_up [<filename>]
132 Loads another .envrc if found with the find_up command. Returns 1 if no
133 file is found.
134 NOTE: the other .envrc is not checked by the security framework.
137 source_up_if_exists [<filename>]
140 Loads another .envrc if found with the find_up command. If one is not
141 found, nothing happens.
142 NOTE: the other .envrc is not checked by the security framework.
145 source_url <url> <integrity-hash>
148 Loads another script from the given url. Before loading it it will
149 check the integrity using the provided integrity-hash.
150 To find the value of the integrity-hash, call direnv fetchurl <url> and
153 extract the hash from the outputted message.
154 See also direnv-fetchurl(1) for more details.
157 fetchurl <url> [<integrity-hash>]
160 Fetches the given url onto disk and outputs it's path location on std‐
161 out.
162 If the integrity-hash argument is provided, it will also check the in‐
165 tegrity of the script.
166 See also direnv-fetchurl(1) for more details.
169 direnv_apply_dump <file>
172 Loads the output of direnv dump that was stored in a file.
173 direnv_load [<command-generating-dump-output>]
176 Applies the environment generated by running argv as a command. This is
177 useful for adopting the environment of a child process - cause that
178 process to run "direnv dump" and then wrap the results with di‐
179 renv_load.
180 Example:
183 direnv_load opam-env exec -- direnv dump
186 PATH_add <path>
190 Prepends the expanded path to the PATH environment variable. It pre‐
191 vents a common mistake where PATH is replaced by only the new path.
192 Example:
195 pwd
198 # output: /home/user/my/project
199 PATH_add bin
200 echo $PATH
201 # output: /home/user/my/project/bin:/usr/bin:/bin
202 MANPATH_add <path>
206 Prepends the expanded path to the MANPATH environment variable. It
207 takes care of man-specific heuritic.
208 path_add <varname> <path>
211 Works like PATH_add except that it's for an arbitrary varname.
212 PATH_rm <pattern> [<pattern> ...]
215 Removes directories that match any of the given shell patterns from the
216 PATH environment variable. Order of the remaining directories is pre‐
217 served in the resulting PATH.
218 Bash pattern syntax:
221 https://www.gnu.org/software/bash/manual/html_node/Pattern-Match‐
222 ing.html
223 Example:
226 echo $PATH
229 # output: /dontremove/me:/remove/me:/usr/local/bin/:...
230 PATH_rm '/remove/*'
231 echo $PATH
232 # output: /dontremove/me:/usr/local/bin/:...
233 load_prefix <prefix_path>
237 Expands some common path variables for the given prefix_path prefix.
238 This is useful if you installed something in the prefix_path using
239 ./configure --prefix=$prefix_path && make install and want to use it in
240 the project.
241 Variables set:
244 CPATH
247 LD_LIBRARY_PATH
248 LIBRARY_PATH
249 MANPATH
250 PATH
251 PKG_CONFIG_PATH
252 Example:
256 ./configure --prefix=$HOME/rubies/ruby-1.9.3
259 make && make install
260 # Then in the .envrc
261 load_prefix ~/rubies/ruby-1.9.3
262 semver_search <directory> <folder_prefix> <partial_version>
266 Search a directory for the highest version number in SemVer format
267 (X.Y.Z).
268 Examples:
271 $ tree .
274 |-- dir
275 |-- program-1.4.0
276 |-- program-1.4.1
277 |-- program-1.5.0
278 $ semver_search "dir" "program-" "1.4.0"
279 1.4.0
280 $ semver_search "dir" "program-" "1.4"
281 1.4.1
282 $ semver_search "dir" "program-" "1"
283 1.5.0
284 layout <type>
288 A semantic dispatch used to describe common project layouts.
289 layout go
292 Adds "$(direnv_layout_dir)/go" to the GOPATH environment variable. And
293 also adds "$PWD/bin" to the PATH environment variable.
294 layout julia
297 Sets the JULIA_PROJECT environment variable to the current directory.
298 layout node
301 Adds "$PWD/node_modules/.bin" to the PATH environment variable.
302 layout php
305 Adds "$PWD/vendor/bin" to the PATH environment variable.
306 layout perl
309 Setup environment variables required by perl's local::lib See
310 http://search.cpan.org/dist/local-lib/lib/local/lib.pm for more de‐
311 tails.
312 layout pipenv
315 Similar to layout python, but uses Pipenv to build a virtualenv from
316 the Pipfile located in the same directory. The path can be overridden
317 by the PIPENV_PIPFILE environment variable.
318 Note that unlike invoking Pipenv manually, this does not load environ‐
321 ment variables from a .env file automatically. You may want to add
322 dotenv .env to copy that behavior.
323 layout pyenv [<version> ...]
326 Similar to layout python, but uses pyenv to build a virtualenv with the
327 specified Python interpreter version.
328 Multiple versions may be specified separated by spaces; please refer to
331 the pyenv documentation for more information.
332 layout python [<python_exe>]
335 Creates and loads a virtualenv environment under $PWD/.di‐
336 renv/python-$python_version. This forces the installation of any egg
337 into the project's sub-folder.
338 It's possible to specify the python executable if you want to use dif‐
341 ferent versions of python (eg: layout python python3).
342 Note that previously virtualenv was located under $PWD/.direnv/vir‐
345 tualenv and will be re-used by direnv if it exists.
346 layout python3
349 A shortcut for layout python python3
350 layout ruby
353 Sets the GEM_HOME environment variable to $PWD/.direnv/ruby/RUBY_VER‐
354 SION. This forces the installation of any gems into the project's sub-
355 folder. If you're using bundler it will create wrapper programs that
356 can be invoked directly instead of using the bundle exec prefix.
357 use <program_name> [<version>]
360 A semantic command dispatch intended for loading external dependencies
361 into the environment.
362 Example:
365 use_ruby() {
368 echo "Ruby $1"
369 }
370 use ruby 1.9.3
371 # output: Ruby 1.9.3
372 use julia <version>
376 Loads the specified Julia version. You must specify a path to the di‐
377 rectory with installed Julia versions using $JULIA_VERSIONS. You can
378 optionally override the prefix for folders inside $JULIA_VERSIONS (de‐
379 fault julia-) using $JULIA_VERSION_PREFIX. If no exact match for <ver‐
380 sion> is found a search will be performed and the latest version will
381 be loaded.
382 Examples (.envrc):
385 use julia 1.5.1 # loads $JULIA_VERSIONS/julia-1.5.1
388 use julia 1.5 # loads $JULIA_VERSIONS/julia-1.5.1
389 use julia master # loads $JULIA_VERSIONS/julia-master
390 use rbenv
394 Loads rbenv which add the ruby wrappers available on the PATH.
395 use nix [...]
398 Load environment variables from nix-shell.
399 If you have a default.nix or shell.nix these will be used by default,
402 but you can also specify packages directly (e.g use nix -p ocaml).
403 See http://nixos.org/nix/manual/#sec-nix-shell
406 use flake [<installable>]
409 Load the build environment of a derivation similar to nix develop.
410 By default it will load the current folder flake.nix devShell attri‐
413 bute. Or pass an "installable" like "nixpkgs#hello" to load all the
414 build dependencies of the hello package from the latest nixpkgs.
415 Note that the flakes feature is hidden behind an experimental flag,
418 which you will have to enable on your own. Flakes is not considered
419 stable yet.
420 use guix [...]
423 Load environment variables from guix shell.
424 Any arguments given will be passed to guix shell. For example, use guix
427 hello would setup an environment including the hello package. To create
428 an environment with the hello dependencies, the --development flag is
429 used use guix --development hello. Other options include --file which
430 allows loading an environment from a file.
431 See https://guix.gnu.org/en/manual/en/guix.html#Invoking-guix-shell
434 rvm [...]
437 Should work just like in the shell if you have rvm installed.
438 use node [<version>]:
441 Loads the specified NodeJS version into the environment.
442 If a partial NodeJS version is passed (i.e. 4.2), a fuzzy match is per‐
445 formed and the highest matching version installed is selected.
446 If no version is passed, it will look at the '.nvmrc' or '.node-ver‐
449 sion' files in the current directory if they exist.
450 Environment Variables:
453 • $NODE_VERSIONS (required) Points to a folder that contains all
456 the installed Node versions. That folder must exist.
457 • $NODE_VERSION_PREFIX (optional) [default="node-v"] Overrides
459 the default version prefix.
460 use vim [<vimrc_file>]
464 Prepends the specified vim script (or .vimrc.local by default) to the
465 DIRENV_EXTRA_VIMRC environment variable.
466 This variable is understood by the direnv/direnv.vim extension. When
469 found, it will source it after opening files in the directory.
470 watch_file <path> [<path> ...]
473 Adds each file to direnv's watch-list. If the file changes direnv will
474 reload the environment on the next prompt.
475 Example (.envrc):
478 watch_file Gemfile
481 direnv_version <version_at_least>
485 Checks that the direnv version is at least old as version_at_least.
486 This can be useful when sharing an .envrc and to make sure that the
487 users are up to date.
488 strict_env [<command> ...]
491 Turns on shell execution strictness. This will force the .envrc evalua‐
492 tion context to exit immediately if:
493 • any command in a pipeline returns a non-zero exit status that
496 is not otherwise handled as part of if, while, or until tests,
497 return value negation (!), or part of a boolean (&& or ||)
498 chain.
499 • any variable that has not explicitly been set or declared
501 (with either declare or local) is referenced.
502 If followed by a command-line, the strictness applies for the duration
506 of the command.
507 Example (Whole Script):
510 strict_env
513 has curl
514 Example (Command):
518 strict_env has curl
521 unstrict_env [<command> ...]
525 Turns off shell execution strictness. If followed by a command-line,
526 the strictness applies for the duration of the command.
527 Example (Whole Script):
530 unstrict_env
533 has curl
534 Example (Command):
538 unstrict_env has curl
541 on_git_branch [<branch_name>]
545 Returns 0 if within a git repository with given branch_name. If no
546 branch name is provided, then returns 0 when within any branch. Re‐
547 quires the git command to be installed. Returns 1 otherwise.
548 When a branch is specified, then .git/HEAD is watched so that enter‐
551 ing/exiting a branch triggers a reload.
552 Example (.envrc):
555 if on_git_branch child_changes; then
558 export MERGE_BASE_BRANCH=parent_changes
559 fi
560 if on_git_branch; then
562 echo "Thanks for contributing to a GitHub project!"
563 fi
564
568 MIT licence - Copyright (C) 2019 @zimbatm and contributors
569
572 direnv(1), direnv.toml(1)
573direnv 2019 DIRENV-STDLIB(1)