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 /.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 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 in‐
140 tegrity 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 di‐
154 renv_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‐
197 ing.html
198 Example:
201 echo $PATH
204 # output: /dontremove/me:/remove/me:/usr/local/bin/:...
205 PATH_rm '/remove/*'
206 echo $PATH
207 # output: /dontremove/me:/usr/local/bin/:...
208 load_prefix <prefix_path>
212 Expands some common path variables for the given prefix_path prefix.
213 This is useful if you installed something in the prefix_path using
214 ./configure --prefix=$prefix_path make install and want to use it in
215 the project.
216 Variables set:
219 CPATH
222 LD_LIBRARY_PATH
223 LIBRARY_PATH
224 MANPATH
225 PATH
226 PKG_CONFIG_PATH
227 Example:
231 ./configure --prefix=$HOME/rubies/ruby-1.9.3
234 make make install
235 # Then in the .envrc
236 load_prefix /rubies/ruby-1.9.3
237 semver_search <directory> <folder_prefix> <partial_version>
241 Search a directory for the highest version number in SemVer format
242 (X.Y.Z).
243 Examples:
246 $ tree .
249 |-- dir
250 |-- program-1.4.0
251 |-- program-1.4.1
252 |-- program-1.5.0
253 $ semver_search "dir" "program-" "1.4.0"
254 1.4.0
255 $ semver_search "dir" "program-" "1.4"
256 1.4.1
257 $ semver_search "dir" "program-" "1"
258 1.5.0
259 layout <type>
263 A semantic dispatch used to describe common project layouts.
264 layout go
267 Adds "$(direnv_layout_dir)/go" to the GOPATH environment variable. And
268 also adds "$PWD/bin" to the PATH environment variable.
269 layout julia
272 Sets the JULIA_PROJECT environment variable to the current directory.
273 layout node
276 Adds "$PWD/node_modules/.bin" to the PATH environment variable.
277 layout php
280 Adds "$PWD/vendor/bin" to the PATH environment variable.
281 layout perl
284 Setup environment variables required by perl's local::lib See
285 http://search.cpan.org/dist/local-lib/lib/local/lib.pm for more de‐
286 tails.
287 layout python [<python_exe>]
290 Creates and loads a virtualenv environment under $PWD/.di‐
291 renv/python-$python_version. This forces the installation of any egg
292 into the project's sub-folder.
293 It's possible to specify the python executable if you want to use dif‐
296 ferent versions of python (eg: layout python python3).
297 Note that previously virtualenv was located under $PWD/.direnv/vir‐
300 tualenv and will be re-used by direnv if it exists.
301 layout python3
304 A shortcut for layout python python3
305 layout ruby
308 Sets the GEM_HOME environment variable to $PWD/.direnv/ruby/RUBY_VER‐
309 SION. This forces the installation of any gems into the project's
310 sub-folder. If you're using bundler it will create wrapper programs
311 that can be invoked directly instead of using the bundle exec prefix.
312 use <program_name> [<version>]
315 A semantic command dispatch intended for loading external dependencies
316 into the environment.
317 Example:
320 use_ruby() {
323 echo "Ruby $1"
324 }
325 use ruby 1.9.3
326 # output: Ruby 1.9.3
327 use julia <version>
331 Loads the specified Julia version. You must specify a path to the di‐
332 rectory with installed Julia versions using $JULIA_VERSIONS. You can
333 optionally override the prefix for folders inside $JULIA_VERSIONS (de‐
334 fault julia-) using $JULIA_VERSION_PREFIX. If no exact match for <ver‐
335 sion> is found a search will be performed and the latest version will
336 be loaded.
337 Examples (.envrc):
340 use julia 1.5.1 # loads $JULIA_VERSIONS/julia-1.5.1
343 use julia 1.5 # loads $JULIA_VERSIONS/julia-1.5.1
344 use julia master # loads $JULIA_VERSIONS/julia-master
345 use rbenv
349 Loads rbenv which add the ruby wrappers available on the PATH.
350 use nix [...]
353 Load environment variables from nix-shell.
354 If you have a default.nix or shell.nix these will be used by default,
357 but you can also specify packages directly (e.g use nix -p ocaml).
358 See http://nixos.org/nix/manual/#sec-nix-shell
361 use guix [...]
364 Load environment variables from guix environment.
365 Any arguments given will be passed to guix environment. For example,
368 use guix hello would setup an environment with the dependencies of the
369 hello package. To create an environment including hello, the --ad-hoc
370 flag is used use guix --ad-hoc hello. Other options include --load
371 which allows loading an environment from a file.
372 See https://www.gnu.org/software/guix/manual/html_node/Invok‐
375 ing-guix-environment.html
376 rvm [...]
379 Should work just like in the shell if you have rvm installed.
380 use node [<version>]:
383 Loads the specified NodeJS version into the environment.
384 If a partial NodeJS version is passed (i.e. 4.2), a fuzzy match is per‐
387 formed and the highest matching version installed is selected.
388 If no version is passed, it will look at the '.nvmrc' or '.node-ver‐
391 sion' files in the current directory if they exist.
392 Environment Variables:
395 • $NODE_VERSIONS (required) Points to a folder that contains all
398 the installed Node versions. That folder must exist.
399 • $NODE_VERSION_PREFIX (optional) [default="node-v"] Overrides
401 the default version prefix.
402 use vim [<vimrc_file>]
406 Prepends the specified vim script (or .vimrc.local by default) to the
407 DIRENV_EXTRA_VIMRC environment variable.
408 This variable is understood by the direnv/direnv.vim extension. When
411 found, it will source it after opening files in the directory.
412 watch_file <path> [<path> ...]
415 Adds each file to direnv's watch-list. If the file changes direnv will
416 reload the environment on the next prompt.
417 Example (.envrc):
420 watch_file Gemfile
423 direnv_version <version_at_least>
427 Checks that the direnv version is at least old as version_at_least.
428 This can be useful when sharing an .envrc and to make sure that the
429 users are up to date.
430 strict_env [<command> ...]
433 Turns on shell execution strictness. This will force the .envrc evalua‐
434 tion context to exit immediately if:
435 • any command in a pipeline returns a non-zero exit status that
438 is not otherwise handled as part of if, while, or until tests,
439 return value negation (!), or part of a boolean ( or ||)
440 chain.
441 • any variable that has not explicitly been set or declared
443 (with either declare or local) is referenced.
444 If followed by a command-line, the strictness applies for the duration
448 of the command.
449 Example (Whole Script):
452 strict_env
455 has curl
456 Example (Command):
460 strict_env has curl
463 unstrict_env [<command> ...]
467 Turns off shell execution strictness. If followed by a command-line,
468 the strictness applies for the duration of the command.
469 Example (Whole Script):
472 unstrict_env
475 has curl
476 Example (Command):
480 unstrict_env has curl
483 on_git_branch [<branch_name>]
487 Returns 0 if within a git repository with given branch_name. If no
488 branch name is provided, then returns 0 when within any branch. Re‐
489 quires the git command to be installed. Returns 1 otherwise.
490 When a branch is specified, then .git/HEAD is watched so that enter‐
493 ing/exiting a branch triggers a reload.
494 Example (.envrc):
497 if on_git_branch child_changes; then
500 export MERGE_BASE_BRANCH=parent_changes
501 fi
502 if on_git_branch; then
504 echo "Thanks for contributing to a GitHub project!"
505 fi
506
510 MIT licence - Copyright (C) 2019 @zimbatm and contributors
511
514 direnv(1), direnv.toml(1)
515direnv 2019 DIRENV-STDLIB(1)