1DIRENV-STDLIB(1)                 User Manuals                 DIRENV-STDLIB(1)
2
3
4

NAME

6       direnv-stdlib - functions for the .envrc
7
8

SYNOPSIS

10       direnv stdlib
11
12

DESCRIPTION

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

STDLIB

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 pyenv [<version> ...]
326       Similar to layout python, but uses pyenv to build a virtualenv with the
327       specified Python interpreter version.
328
329
330       Multiple versions may be specified separated by spaces; please refer to
331       the pyenv documentation for more information.
332
333
334   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
339
340       It's possible to specify the python executable if you want to use  dif‐
341       ferent versions of python (eg: layout python python3).
342
343
344       Note  that  previously  virtualenv  was located under $PWD/.direnv/vir‐
345       tualenv and will be re-used by direnv if it exists.
346
347
348   layout python3
349       A shortcut for layout python python3
350
351
352   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
358
359   use <program_name> [<version>]
360       A  semantic command dispatch intended for loading external dependencies
361       into the environment.
362
363
364       Example:
365
366
367              use_ruby() {
368                echo "Ruby $1"
369              }
370              use ruby 1.9.3
371              # output: Ruby 1.9.3
372
373
374
375   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
383
384       Examples (.envrc):
385
386
387              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
391
392
393   use rbenv
394       Loads rbenv which add the ruby wrappers available on the PATH.
395
396
397   use nix [...]
398       Load environment variables from nix-shell.
399
400
401       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
404
405       See http://nixos.org/nix/manual/#sec-nix-shell
406
407
408   use flake [<installable>]
409       Load the build environment of a derivation similar to nix develop.
410
411
412       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
416
417       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
421
422   use guix [...]
423       Load environment variables from guix shell.
424
425
426       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
432
433       See https://guix.gnu.org/en/manual/en/guix.html#Invoking-guix-shell
434
435
436   rvm [...]
437       Should work just like in the shell if you have rvm installed.
438
439
440   use node [<version>]:
441       Loads the specified NodeJS version into the environment.
442
443
444       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
447
448       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
451
452       Environment Variables:
453
454
455              • $NODE_VERSIONS (required) Points to a folder that contains all
456                the installed Node versions. That folder must exist.
457
458              • $NODE_VERSION_PREFIX  (optional)  [default="node-v"] Overrides
459                the default version prefix.
460
461
462
463   use vim [<vimrc_file>]
464       Prepends the specified vim script (or .vimrc.local by default)  to  the
465       DIRENV_EXTRA_VIMRC environment variable.
466
467
468       This  variable  is  understood by the direnv/direnv.vim extension. When
469       found, it will source it after opening files in the directory.
470
471
472   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
476
477       Example (.envrc):
478
479
480              watch_file Gemfile
481
482
483
484   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
489
490   strict_env [<command> ...]
491       Turns on shell execution strictness. This will force the .envrc evalua‐
492       tion context to exit immediately if:
493
494
495              • 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
500              • any  variable  that  has  not  explicitly been set or declared
501                (with either declare or local) is referenced.
502
503
504
505       If followed by a command-line, the strictness applies for the  duration
506       of the command.
507
508
509       Example (Whole Script):
510
511
512              strict_env
513              has curl
514
515
516
517       Example (Command):
518
519
520              strict_env has curl
521
522
523
524   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
528
529       Example (Whole Script):
530
531
532              unstrict_env
533              has curl
534
535
536
537       Example (Command):
538
539
540              unstrict_env has curl
541
542
543
544   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
549
550       When a branch is specified, then .git/HEAD is watched  so  that  enter‐
551       ing/exiting a branch triggers a reload.
552
553
554       Example (.envrc):
555
556
557              if on_git_branch child_changes; then
558                export MERGE_BASE_BRANCH=parent_changes
559              fi
560
561              if on_git_branch; then
562                echo "Thanks for contributing to a GitHub project!"
563              fi
564
565
566
568       MIT licence - Copyright (C) 2019 @zimbatm and contributors
569
570

SEE ALSO

572       direnv(1), direnv.toml(1)
573
574
575
576direnv                               2019                     DIRENV-STDLIB(1)
Impressum