README.rst

emacs-direnv

this package provides direnv integration for emacs.

it works by invoking direnv to obtain the environment for the current file, then updating the emacs variables process-environment and exec-path.

the result is that programs started from within emacs, such as inferior shells, linters, compilers, and test runners, will be looked up in the correct $PATH, and will be started with the correct environment variables set.

to get started, add this to your init.el:

(use-package direnv
 :config
 (direnv-mode))

installation

direnv.el is available from melpa.

with use-package:

(use-package direnv)

manually:

M-x package-install RET direnv RET

alternatively, put the elisp file somewhere in the loading path and load it explicitly:

(require 'direnv)

also make sure that the direnv version (direnv version) is at least 2.8.0 since this package uses the json export capabilities (direnv export json).

usage

the command direnv-update-environment provides the core functionality of this package: it updates the emacs environment to the direnv environment for the current file. the minibuffer will show a message with a summary of the changes made to the environment, similar to what direnv does in a shell. its sibling command direnv-update-directory-environment does the same for buffers that don't have an associated file.

the global minor mode direnv-mode does the same, but automatically updates the emacs environment when the active buffer changes, so that the environment always matches the current file. to automatically enable this behaviour when emacs starts, put this in your ~/.emacs/init.el:

(direnv-mode)

or use the use-package :config block:

(use-package direnv
 :config
 (direnv-mode))

finally, the direnv-allow command acts like direnv allow from a shell: it allows loading the .envrc file associated with the current directory or one of its parent directories. this command is useful for new projects (always check whether the .envrc file is trustworthy), or after editing the .envrc file within emacs itself.

configuration

this packages offers various configuration settings. these settings can be set in a use-package :custom block, using (setq), or via the customize interface:

M-x customize-group RET direnv RET

the available settings are outlined below.

• direnv-always-show-summary

  when direnv-mode automatically changes the environment, a summary message will be shown in the minibuffer. summary messages of automatic changes can be suppressed by setting direnv-always-show-summary to nil. interactive calls, e.g. direnv-update-environment, will still show a summary message.

• direnv-show-paths-in-summary

  the summary message contains the paths of the old and new directories, which may be a bit too verbose for your taste. the direnv-show-paths-in-summary variable controls whether the summary includes path names. to get shorter summary messages, use nil.

• direnv-use-faces-in-summary

  the summary message uses different font faces for added, changed, and removed environment variables. depending on your theme, this usually results in different colours. this behaviour can be disabled by setting direnv-use-faces-in-summary to nil.

• direnv-non-file-modes

  this is a list of modes where direnv will update even if the buffer has no file. examples include shells and interactive compilation (comint) buffers. example usage (with use-package):

  (use-package foobar
   :config
   (add-to-list 'direnv-non-file-modes 'foobar-mode))

• warning-suppress-types

  this is an emacs variable with a list of warning types which are not displayed immediately. use it to hide error messages from direnv. example usage (with use-package):

  (use-package direnv
   :config
   (add-to-list 'warning-suppress-types '(direnv)))

troubleshooting

if you experience problems, first check the buffer named *direnv*. this buffer contains the output of the last direnv invocation, which will likely contain more information about the source of the problem.

when an error happens, the direnv stderr will be automatically shown in the message area, but for non-fatal problems such as incorrect .envrc files you may have to open this buffer manually for inspection of the full output of the last direnv call.

to hide direnv errors such as .envrc is blocked, customize the variable warning-suppress-types.

contributing

praise? complaints? bugs? questions? ideas?

please use the github issue tracker.

credits

this emacs package was created by wouter bolsterlee (@wbolster).

it incorporates ideas from earlier packages created by jonathan lange (@jml) and christian romney (@christianromney).

history

• 2.2.0 (2021-10-11)
  • depend on emacs 25.1+
  • allow user to hide warnings and errors from direnv #61
  • use both post-command-hook and before-hack-local-variables-hook when direnv-mode is used. this should cause direnv to load earlier which can avoid certain issues when opening a file in a direnv controlled directory for the first time. see #61 and #17
  • load diff-mode to avoid ‘invalid face reference’ warnings #69
  • explicitly set json-object-type when parsing json to avoid potential conflicts with other packages #72
• 2.1.0 (2020-02-29)
  • require emacs 25+ (it's 3 years old) #42
  • fix emacs 25 compatibility issues
  • also consider derived modes for direnv-non-file-modes #49
  • use direnv in magit-mode by default #50
  • try to avoid opening remote connections #46
  • prevent eshell-path-env getting out-of-sync with $PATH #55
  • use base buffer mode directories for indirect buffers #51
  • include comint-mode and compilation-mode in direnv-non-file-modes by default #58
• 2.0.0 (2019-05-11)
  • add direnv-allow command; see #43
  • use friendlier path formatting in summary message; see #44
  • improve handling of direnv output and improve error reporting; see #41 and #42
  • remove broken direnv-edit command #20
• 1.5.0 (2019-03-19)
  • handle indirect buffers correctly; see #25
  • display direnv errors in the message area; see #34
  • make the *direnv* buffer easier to find by removing the leading space
  • add eshell and dired to list of non-file-modes; see #36 and #33
• 1.4.0 (2018-03-01)
  • smarter default behaviour of summary messages on environment change; see #23
• 1.3.0 (2018-02-13)
  • improved operation with non-file modes, such as shells and compilation buffers. see direnv-non-file-modes.
• 1.2.1 (2017-06-22)
  • direnv-mode no longer fails when opening a file in a directory that does not (yet) exist.
• 1.2.0 (2017-05-01)
  • summary message now uses custom font faces (colours!)
  • improved error handling
• 1.1.0 (2017-03-09)
  • implemented summary message after updating environment, and configuration variables to tweak how it works.
  • expanded docs
• 1.0.1 (2017-03-08)
  • initial release with basic functionality

license

3-clause new bsd license; see LICENSE.rst.