1DIRENV-STDLIB(1) User Manuals DIRENV-STDLIB(1)
2
3
4
6 direnv-stdlib - functions for the .envrc
7
8
10 direnv stdlib
11
12
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
18
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
24
25 Example:
26
27
28 if has curl; then
29 echo "Yes we do"
30 fi
31
32
33
34 expand_path <rel_path> [<relative_to>]
35 Outputs the absolute path of rel_path relative to relative_to or the
36 current directory.
37
38
39 Example:
40
41
42 cd /usr/local/games
43 expand_path ../foo
44 # output: /usr/local/foo
45
46
47
48 dotenv [<dotenv_path>]
49 Loads a ".env" file into the current environment.
50
51
52 dotenv_if_exists [<dotenv_path>]
53 Loads a ".env" file into the current environment, but only if it ex‐
54 ists.
55
56
57 user_rel_path <abs_path>
58 Transforms an absolute path abs_path into a user-relative path if pos‐
59 sible.
60
61
62 Example:
63
64
65 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
72
73
74 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
78
79 Example:
80
81
82 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
89
90
91 source_env <file_or_dir_path>
92 Loads another .envrc either by specifying its path or filename.
93
94
95 NOTE: the other .envrc is not checked by the security framework.
96
97
98 source_env_if_exists <filename>
99 Loads another ".envrc", but only if it exists.
100
101
102 NOTE: contrary to source_env, this only works when passing a path to a
103 file,
104 not a directory.
105
106
107 Example:
108
109
110 source_env_if_exists .envrc.private
111
112
113
114 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
120
121 Example:
122
123
124 # 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
129
130
131 source_up [<filename>]
132 Loads another .envrc if found with the find_up command. Returns 1 if no
133 file is found.
134
135
136 NOTE: the other .envrc is not checked by the security framework.
137
138
139 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
143
144 NOTE: the other .envrc is not checked by the security framework.
145
146
147 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
151
152 To find the value of the integrity-hash, call direnv fetchurl <url> and
153 extract the hash from the outputted message.
154
155
156 See also direnv-fetchurl(1) for more details.
157
158
159 fetchurl <url> [<integrity-hash>]
160 Fetches the given url onto disk and outputs it's path location on std‐
161 out.
162
163
164 If the integrity-hash argument is provided, it will also check the in‐
165 tegrity of the script.
166
167
168 See also direnv-fetchurl(1) for more details.
169
170
171 direnv_apply_dump <file>
172 Loads the output of direnv dump that was stored in a file.
173
174
175 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
181
182 Example:
183
184
185 direnv_load opam-env exec -- direnv dump
186
187
188
189 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
193
194 Example:
195
196
197 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
203
204
205 MANPATH_add <path>
206 Prepends the expanded path to the MANPATH environment variable. It
207 takes care of man-specific heuritic.
208
209
210 path_add <varname> <path>
211 Works like PATH_add except that it's for an arbitrary varname.
212
213
214 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
219
220 Bash pattern syntax:
221 https://www.gnu.org/software/bash/manual/html_node/Pattern-Match‐
222 ing.html
223
224
225 Example:
226
227
228 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
234
235
236 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
242
243 Variables set:
244
245
246 CPATH
247 LD_LIBRARY_PATH
248 LIBRARY_PATH
249 MANPATH
250 PATH
251 PKG_CONFIG_PATH
252
253
254
255 Example:
256
257
258 ./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
263
264
265 semver_search <directory> <folder_prefix> <partial_version>
266 Search a directory for the highest version number in SemVer format
267 (X.Y.Z).
268
269
270 Examples:
271
272
273 $ 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
285
286
287 layout <type>
288 A semantic dispatch used to describe common project layouts.
289
290
291 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
295
296 layout julia
297 Sets the JULIA_PROJECT environment variable to the current directory.
298
299
300 layout node
301 Adds "$PWD/node_modules/.bin" to the PATH environment variable.
302
303
304 layout php
305 Adds "$PWD/vendor/bin" to the PATH environment variable.
306
307
308 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
313
314 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
319
320 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
324
325 layout python [<python_exe>]
326 Creates and loads a virtualenv environment under $PWD/.di‐
327 renv/python-$python_version. This forces the installation of any egg
328 into the project's sub-folder.
329
330
331 It's possible to specify the python executable if you want to use dif‐
332 ferent versions of python (eg: layout python python3).
333
334
335 Note that previously virtualenv was located under $PWD/.direnv/vir‐
336 tualenv and will be re-used by direnv if it exists.
337
338
339 layout python3
340 A shortcut for layout python python3
341
342
343 layout ruby
344 Sets the GEM_HOME environment variable to $PWD/.direnv/ruby/RUBY_VER‐
345 SION. This forces the installation of any gems into the project's sub-
346 folder. If you're using bundler it will create wrapper programs that
347 can be invoked directly instead of using the bundle exec prefix.
348
349
350 use <program_name> [<version>]
351 A semantic command dispatch intended for loading external dependencies
352 into the environment.
353
354
355 Example:
356
357
358 use_ruby() {
359 echo "Ruby $1"
360 }
361 use ruby 1.9.3
362 # output: Ruby 1.9.3
363
364
365
366 use julia <version>
367 Loads the specified Julia version. You must specify a path to the di‐
368 rectory with installed Julia versions using $JULIA_VERSIONS. You can
369 optionally override the prefix for folders inside $JULIA_VERSIONS (de‐
370 fault julia-) using $JULIA_VERSION_PREFIX. If no exact match for <ver‐
371 sion> is found a search will be performed and the latest version will
372 be loaded.
373
374
375 Examples (.envrc):
376
377
378 use julia 1.5.1 # loads $JULIA_VERSIONS/julia-1.5.1
379 use julia 1.5 # loads $JULIA_VERSIONS/julia-1.5.1
380 use julia master # loads $JULIA_VERSIONS/julia-master
381
382
383
384 use rbenv
385 Loads rbenv which add the ruby wrappers available on the PATH.
386
387
388 use nix [...]
389 Load environment variables from nix-shell.
390
391
392 If you have a default.nix or shell.nix these will be used by default,
393 but you can also specify packages directly (e.g use nix -p ocaml).
394
395
396 See http://nixos.org/nix/manual/#sec-nix-shell
397
398
399 use flake [<installable>]
400 Load the build environment of a derivation similar to nix develop.
401
402
403 By default it will load the current folder flake.nix devShell attri‐
404 bute. Or pass an "installable" like "nixpkgs#hello" to load all the
405 build dependencies of the hello package from the latest nixpkgs.
406
407
408 Note that the flakes feature is hidden behind an experimental flag,
409 which you will have to enable on your own. Flakes is not considered
410 stable yet.
411
412
413 use guix [...]
414 Load environment variables from guix environment.
415
416
417 Any arguments given will be passed to guix environment. For example,
418 use guix hello would setup an environment with the dependencies of the
419 hello package. To create an environment including hello, the --ad-hoc
420 flag is used use guix --ad-hoc hello. Other options include --load
421 which allows loading an environment from a file.
422
423
424 See https://www.gnu.org/software/guix/manual/html_node/Invoking-guix-
425 environment.html
426
427
428 rvm [...]
429 Should work just like in the shell if you have rvm installed.
430
431
432 use node [<version>]:
433 Loads the specified NodeJS version into the environment.
434
435
436 If a partial NodeJS version is passed (i.e. 4.2), a fuzzy match is per‐
437 formed and the highest matching version installed is selected.
438
439
440 If no version is passed, it will look at the '.nvmrc' or '.node-ver‐
441 sion' files in the current directory if they exist.
442
443
444 Environment Variables:
445
446
447 • $NODE_VERSIONS (required) Points to a folder that contains all
448 the installed Node versions. That folder must exist.
449
450 • $NODE_VERSION_PREFIX (optional) [default="node-v"] Overrides
451 the default version prefix.
452
453
454
455 use vim [<vimrc_file>]
456 Prepends the specified vim script (or .vimrc.local by default) to the
457 DIRENV_EXTRA_VIMRC environment variable.
458
459
460 This variable is understood by the direnv/direnv.vim extension. When
461 found, it will source it after opening files in the directory.
462
463
464 watch_file <path> [<path> ...]
465 Adds each file to direnv's watch-list. If the file changes direnv will
466 reload the environment on the next prompt.
467
468
469 Example (.envrc):
470
471
472 watch_file Gemfile
473
474
475
476 direnv_version <version_at_least>
477 Checks that the direnv version is at least old as version_at_least.
478 This can be useful when sharing an .envrc and to make sure that the
479 users are up to date.
480
481
482 strict_env [<command> ...]
483 Turns on shell execution strictness. This will force the .envrc evalua‐
484 tion context to exit immediately if:
485
486
487 • any command in a pipeline returns a non-zero exit status that
488 is not otherwise handled as part of if, while, or until tests,
489 return value negation (!), or part of a boolean (&& or ||)
490 chain.
491
492 • any variable that has not explicitly been set or declared
493 (with either declare or local) is referenced.
494
495
496
497 If followed by a command-line, the strictness applies for the duration
498 of the command.
499
500
501 Example (Whole Script):
502
503
504 strict_env
505 has curl
506
507
508
509 Example (Command):
510
511
512 strict_env has curl
513
514
515
516 unstrict_env [<command> ...]
517 Turns off shell execution strictness. If followed by a command-line,
518 the strictness applies for the duration of the command.
519
520
521 Example (Whole Script):
522
523
524 unstrict_env
525 has curl
526
527
528
529 Example (Command):
530
531
532 unstrict_env has curl
533
534
535
536 on_git_branch [<branch_name>]
537 Returns 0 if within a git repository with given branch_name. If no
538 branch name is provided, then returns 0 when within any branch. Re‐
539 quires the git command to be installed. Returns 1 otherwise.
540
541
542 When a branch is specified, then .git/HEAD is watched so that enter‐
543 ing/exiting a branch triggers a reload.
544
545
546 Example (.envrc):
547
548
549 if on_git_branch child_changes; then
550 export MERGE_BASE_BRANCH=parent_changes
551 fi
552
553 if on_git_branch; then
554 echo "Thanks for contributing to a GitHub project!"
555 fi
556
557
558
560 MIT licence - Copyright (C) 2019 @zimbatm and contributors
561
562
564 direnv(1), direnv.toml(1)
565
566
567
568direnv 2019 DIRENV-STDLIB(1)