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
15 included in that script and loaded in the context of an .envrc. In
16 addition, it also loads the file in /.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
54 exists.
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 source_up [<filename>]
115 Loads another .envrc if found when searching from the parent directory
116 up to /.
117 NOTE: the other .envrc is not checked by the security framework.
120 source_url <url> <integrity-hash>
123 Loads another script from the given url. Before loading it it will
124 check the integrity using the provided integrity-hash.
125 To find the value of the integrity-hash, call direnv fetchurl <url> and
128 extract the hash from the outputted message.
129 See also direnv-fetchurl(1) for more details.
132 fetchurl <url> [<integrity-hash>]
135 Fetches the given url onto disk and outputs it's path location on std‐
136 out.
137 If the integrity-hash argument is provided, it will also check the
140 integrity of the script.
141 See also direnv-fetchurl(1) for more details.
144 direnv_apply_dump <file>
147 Loads the output of direnv dump that was stored in a file.
148 direnv_load [<command-generating-dump-output>]
151 Applies the environment generated by running argv as a command. This is
152 useful for adopting the environment of a child process - cause that
153 process to run "direnv dump" and then wrap the results with
154 direnv_load.
155 Example:
158 direnv_load opam-env exec -- direnv dump
161 PATH_add <path>
165 Prepends the expanded path to the PATH environment variable. It pre‐
166 vents a common mistake where PATH is replaced by only the new path.
167 Example:
170 pwd
173 # output: /home/user/my/project
174 PATH_add bin
175 echo $PATH
176 # output: /home/user/my/project/bin:/usr/bin:/bin
177 MANPATH_add <path>
181 Prepends the expanded path to the MANPATH environment variable. It
182 takes care of man-specific heuritic.
183 path_add <varname> <path>
186 Works like PATH_add except that it's for an arbitrary varname.
187 PATH_rm <pattern> [<pattern> ...]
190 Removes directories that match any of the given shell patterns from the
191 PATH environment variable. Order of the remaining directories is pre‐
192 served in the resulting PATH.
193 Bash pattern syntax:
196 ⟨https://www.gnu.org/software/bash/manual/html_node/Pattern-Match‐
198 ing.html⟩
199 Example:
202 echo $PATH
205 # output: /dontremove/me:/remove/me:/usr/local/bin/:...
206 PATH_rm '/remove/*'
207 echo $PATH
208 # output: /dontremove/me:/usr/local/bin/:...
209 load_prefix <prefix_path>
213 Expands some common path variables for the given prefix_path prefix.
214 This is useful if you installed something in the prefix_path using
215 ./configure --prefix=$prefix_path make install and want to use it in
216 the project.
217 Variables set:
220 CPATH
223 LD_LIBRARY_PATH
224 LIBRARY_PATH
225 MANPATH
226 PATH
227 PKG_CONFIG_PATH
228 Example:
232 ./configure --prefix=$HOME/rubies/ruby-1.9.3
235 make make install
236 # Then in the .envrc
237 load_prefix /rubies/ruby-1.9.3
238 semver_search <directory> <folder_prefix> <partial_version>
242 Search a directory for the highest version number in SemVer format
243 (X.Y.Z).
244 Examples:
247 $ tree .
250 |-- dir
251 |-- program-1.4.0
252 |-- program-1.4.1
253 |-- program-1.5.0
254 $ semver_search "dir" "program-" "1.4.0"
255 1.4.0
256 $ semver_search "dir" "program-" "1.4"
257 1.4.1
258 $ semver_search "dir" "program-" "1"
259 1.5.0
260 layout <type>
264 A semantic dispatch used to describe common project layouts.
265 layout go
268 Adds "$(direnv_layout_dir)/go" to the GOPATH environment variable. And
269 also adds "$PWD/bin" to the PATH environment variable.
270 layout julia
273 Sets the JULIA_PROJECT environment variable to the current directory.
274 layout node
277 Adds "$PWD/node_modules/.bin" to the PATH environment variable.
278 layout php
281 Adds "$PWD/vendor/bin" to the PATH environment variable.
282 layout perl
285 Setup environment variables required by perl's local::lib See
286 ⟨http://search.cpan.org/dist/local-lib/lib/local/lib.pm⟩ for more
287 details.
288 layout python [<python_exe>]
291 Creates and loads a virtualenv environment under
292 $PWD/.direnv/python-$python_version. This forces the installation of
293 any egg into the project's sub-folder.
294 It's possible to specify the python executable if you want to use dif‐
297 ferent versions of python (eg: layout python python3).
298 Note that previously virtualenv was located under $PWD/.direnv/vir‐
301 tualenv and will be re-used by direnv if it exists.
302 layout python3
305 A shortcut for layout python python3
306 layout ruby
309 Sets the GEM_HOME environment variable to $PWD/.direnv/ruby/RUBY_VER‐
310 SION. This forces the installation of any gems into the project's
311 sub-folder. If you're using bundler it will create wrapper programs
312 that can be invoked directly instead of using the bundle exec prefix.
313 use <program_name> [<version>]
316 A semantic command dispatch intended for loading external dependencies
317 into the environment.
318 Example:
321 use_ruby() {
324 echo "Ruby $1"
325 }
326 use ruby 1.9.3
327 # output: Ruby 1.9.3
328 use julia <version>
332 Loads the specified Julia version. You must specify a path to the
333 directory with installed Julia versions using $JULIA_VERSIONS. You can
334 optionally override the prefix for folders inside $JULIA_VERSIONS
335 (default julia-) using $JULIA_VERSION_PREFIX. If no exact match for
336 <version> is found a search will be performed and the latest version
337 will be loaded.
338 Examples (.envrc):
341 use julia 1.5.1 # loads $JULIA_VERSIONS/julia-1.5.1
344 use julia 1.5 # loads $JULIA_VERSIONS/julia-1.5.1
345 use julia master # loads $JULIA_VERSIONS/julia-master
346 use rbenv
350 Loads rbenv which add the ruby wrappers available on the PATH.
351 use nix [...]
354 Load environment variables from nix-shell.
355 If you have a default.nix or shell.nix these will be used by default,
358 but you can also specify packages directly (e.g use nix -p ocaml).
359 See ⟨http://nixos.org/nix/manual/#sec-nix-shell⟩
362 use guix [...]
365 Load environment variables from guix environment.
366 Any arguments given will be passed to guix environment. For example,
369 use guix hello would setup an environment with the dependencies of the
370 hello package. To create an environment including hello, the --ad-hoc
371 flag is used use guix --ad-hoc hello. Other options include --load
372 which allows loading an environment from a file.
373 See ⟨https://www.gnu.org/software/guix/manual/html_node/Invoking-guix-
376 environment.html⟩
377 rvm [...]
380 Should work just like in the shell if you have rvm installed.
381 use node [<version>]:
384 Loads NodeJS version from a .node-version or .nvmrc file.
385 If you specify a partial NodeJS version (i.e. 4.2), a fuzzy match is
388 performed and the highest matching version installed is selected.
389 Example (.envrc):
392 set -e
395 use node
396 Example (.node-version):
400 4.2
403 use node <version>
407 Loads specified NodeJS version.
408 Example (.envrc):
411 set -e
414 use node 4.2.2
415 use vim [<vimrc_file>]
419 Prepends the specified vim script (or .vimrc.local by default) to the
420 DIRENV_EXTRA_VIMRC environment variable.
421 This variable is understood by the direnv/direnv.vim extension. When
424 found, it will source it after opening files in the directory.
425 watch_file <path> [<path> ...]
428 Adds each file to direnv's watch-list. If the file changes direnv will
429 reload the environment on the next prompt.
430 Example (.envrc):
433 watch_file Gemfile
436 direnv_version <version_at_least>
440 Checks that the direnv version is at least old as version_at_least.
441 This can be useful when sharing an .envrc and to make sure that the
442 users are up to date.
443 strict_env [<command> ...]
446 Turns on shell execution strictness. This will force the .envrc evalua‐
447 tion context to exit immediately if:
448 · any command in a pipeline returns a non-zero exit status that is not
450 otherwise handled as part of if, while, or until tests, return value
451 negation (!), or part of a boolean ( or ||) chain.
452 · any variable that has not explicitly been set or declared (with
454 either declare or local) is referenced.
455 If followed by a command-line, the strictness applies for the duration
458 of the command.
459 Example (Whole Script):
462 strict_env
465 has curl
466 Example (Command):
470 strict_env has curl
473 unstrict_env [<command> ...]
477 Turns off shell execution strictness. If followed by a command-line,
478 the strictness applies for the duration of the command.
479 Example (Whole Script):
482 unstrict_env
485 has curl
486 Example (Command):
490 unstrict_env has curl
493 on_git_branch [<branch_name>]
497 Returns 0 if within a git repository with given branch_name. If no
498 branch name is provided, then returns 0 when within any branch.
499 Requires the git command to be installed. Returns 1 otherwise.
500 When a branch is specified, then .git/HEAD is watched so that enter‐
503 ing/exiting a branch triggers a reload.
504 Example (.envrc):
507 if on_git_branch child_changes; then
510 export MERGE_BASE_BRANCH=parent_changes
511 fi
512 if on_git_branch; then
514 echo "Thanks for contributing to a GitHub project!"
515 fi
516
520 MIT licence - Copyright (C) 2019 @zimbatm and contributors
521
524 direnv(1), direnv.toml(1)
525direnv 2019 DIRENV-STDLIB(1)