An Emacs package that provides some helpful functions for working with environment variables and env files.

This package uses a bash subprocess to fully expand variables, which means you can leverage the power of bash to define variables.

• Example Usage
• API
  • environ-set-file (file-path)
  • environ-unset-file (file-path)
  • environ-set-str (str)
  • environ-unset-str (str)
  • environ-get-pairs
  • environ-set-pairs (pairs)
  • environ-unset-pairs (pairs)
  • environ-get-names
  • environ-unset-names (names)
  • environ-unset-name (name)
• Configuration
  • environ-dir
  • environ-pre-eval-functions
  • environ-post-eval-functions
• File Format
• Usage from org-mode
• How it Works
• See Also

Create an env file with the following contents at ~/.env/foo:

FOO=~/foo
BAR=$FOO/bar
BAZ=$(pwd)

Now, run M-x environ-set-file, which will prompt for a file. Navigate to ~/.env/foo and press Enter. Voilà, you have three new environment variables set in Emacs. Verify you can retrieve them with M-x getenv. Unset them with M-x environ-unset-file (this will again prompt for a file).

Besides setting (and unsetting) environment variables from env files, this package provides an API for common operations with environment variables. Examples below.

[interactive] Set environment variables defined in the file at FILE-PATH.

When used interactively, prompts for the file to load. The prompt begins in environ-dir. When used from elisp, FILE-PATH can either be absolute or relative to default-directory.

(environ-set-file (expand-file-name "~/.env/foo"))

[interactive] Unset the environment variables defined in FILE-PATH.

See the documentation for environ-set-file.

(environ-unset-file (expand-file-name "~/.env/foo"))

Set environment variables defined in the given string STR.

Parse STR like an env file. STR is split into newline-delimited lines, where each line is a key/value pair.

(environ-set-str "A=foo\nB=$A-bar")
(getenv "A") ;; => "foo"
(getenv "B") ;; => "foo-bar"

Unset environment variables defined in string STR.

Parse STR like an env file. STR is split into newline-delimited pairs, where the key of each pair is the environment variable name. The value of each pair is discarded, as the environment variable will be unset regardless of its value.

(environ-unset-str "A=foo\nB=$A-bar")
(getenv "FOO") ;; => nil
(getenv "BAR") ;; => nil

Return all current environment variables as a list of pairs.

(environ-get-pairs)
;; => (("LANG" "en_US.UTF-8")
;;     ("HOME" "/Users/cfclrk")
;;     ...)

Set the environment variables defined by the given PAIRS.

PAIRS is a list of pairs, where each pair is an environment variable name and value.

(environ-set-pairs '(("A" "foo")
                     ("B" "$A-bar")))
(getenv "A") ;; => "foo"
(getenv "B") ;; => "foo-bar"

;; Prevent interpolation using single quotes
(environ-set-pairs '(("A" "foo")
                     ("B" "'$A-bar'")))
(getenv "A") ;; => "foo"
(getenv "B") ;; => "$A-bar"

Unset the environment variables defined in the given PAIRS.

PAIRS is a list of pairs, where each pair is an environment variable name and value. The value in each pair doesn't matter; each environment variable will be unset regardless of its value.

(getenv "A") ;; => "foo"
(environ-unset-pairs '(("A" "foo")
                       ("B" "bar")))
(getenv "A") ;; => nil

Return a list of all current environment variable names.

(environ-get-names)
;; => ("HOME" "FOO" "BAR" ...)

Unset environment variables with the given NAMES.

NAMES is a list of environment variable names which may or may not be currently set. This function removes each name from process-environment if it is set.

(getenv "A") ;; => "foo"
(environ-unset-names '("A" "B"))
(getenv "A") ;; => nil

[interactive] Unset the environment variable NAME.

Unset the given environment variable by removing it from process-environment if it is there. Note that calling setenv with a prefix argument can unset a variable by setting its value to nil, but the variable remains in process-environment. This function completely removes the variable from process-environment.

Directory to prompt for env files.

This variable is only used by environ-set-file and environ-unset-file when they are run interactively. Defaults to (expand-file-name "~/").

(setq environ-dir (expand-file-name "~/.env"))

A list of functions to run before shell evaluation.

Each function takes a list of pairs and returns an updated list of pairs. Defaults to nil.

(setq environ-pre-eval-functions
      '((lambda (pairs)
          (cons '("A" "a") pairs))
        (lambda (pairs)
          (cons '("B" "b") pairs))))

A list of functions to run after shell evaluation.

Each function takes a list of pairs and returns an updated list of pairs. Defaults to '(environ-ignore-bash-vars).

(setq environ-post-eval-functions
      '((lambda (pairs)
          (cons '("A" "a") pairs))
        (lambda (pairs)
          (cons '("B" "b") pairs))))

Each line in an env file must be in a KEY=VALUE format, with one entry per line. This package invokes an bash shell to interpret the file, so shellisms should work (like ~ expansion or using single quotes to prevent variable interpolation).

For example:

A=foo
B="bar"
C='R$%!$KP$'
D=$A-bar
E=~/cats

This example shows one way to set environment variables in an org document using a table:

#+NAME: env
| Var  | Value           |
|------+-----------------|
| FOO  | ~/foo           |
| BAR  | $FOO/bar        |
| BAZ  | '$FOO/bar'      |

#+begin_src emacs-lisp :var env=env
  (environ-set-pairs env)
#+end_src

This package works by evaluating the provided input in a bash subprocess, and then returning the difference between current environment and the subprocess environment.

You can think of each function in terms of two phases: the way in, and the way out. On the way in, input is parsed into a list of pairs (the IR) if it isn't already in that form. Then, all pre-eval-functions (if any) are run, which may update the IR. The IR is then assembled into a bash script, executed, and then the result of running printenv in the bash subprocess is returned.

flowchart LR
    env-file[env file] -- parse --> IR
    IR -- pre-eval-functions --> IR
    IR -- build script --> script[bash script]
    script -- run script --> stdout

On the way out, we start with two things: the stdout that was produced by running printenv in the bash process, and the current process-environment in Emacs. The bash stdout is parsed back into a list of pairs (IR_1) and all post-eval functions (if any) are run, which may update IR_1. Emacs' current process-environment is parsed into a separate list of pairs (IR_2). Then, the two IRs are compared, and only elements in IR_1 that are not in IR_2 are kept (IR_3). Finally, each pair in IR_3 is set in the current process-environment.

flowchart LR
  stdout -- parse --> IR_1
  IR_1 -- post-eval-functions --> IR_1
  cur[current environment] -- parse --> IR_2
  IR_1 -- diff --> IR_3
  IR_2 -- diff --> IR_3
  IR_3 -- setenv each pair --> done

• emacs-direnv
• envrc
• parsenv