Dotenv File Format
This implementation cleaves closely to the original dotenv package, but it is not a direct match (by design).
Typically, a dotenv (.env
) file is formatted into simple key-value pairs:
S3_BUCKET=YOURS3BUCKET
SECRET_KEY=YOURSECRETKEYGOESHERE
You may add export
in front of each line so you can source
the file in bash (see Dotenvy.source/2
):
export S3_BUCKET=YOURS3BUCKET
export SECRET_KEY=YOURSECRETKEYGOESHERE
Variable Names
For the sake of portability (and sanity), environment variable names must
consist solely of letters, digits, and the >underscore< ( _
) and
must not begin with a digit. In regex-speak:
[a-zA-Z_]+[a-zA-Z0-9_]*
Example variable names
DATABASE_URL
foobar
NO-WORK # <-- invalid !!!
ÜBER # <-- invalid !!!
2MUCH # <-- invalid !!!
Values
Values are what's to the right of the equals sign. They may be quoted. Using single quotes will prevent variables from being interpolated.
SIMPLE=xyz123
INTERPOLATED="Multiple\\nLines and variable substitution: ${SIMPLE}"
NON_INTERPOLATED='raw text without variable interpolation'
MULTILINE = """
long text here,
e.g. a private SSH key
"""
Escape Sequences
When wrapped in quotes, the following character strings will be interpreted (i.e. escaped) as specific codepoints in the same way you would expect if the values were assigned inside a script.
\n
Linefeed (aka newline); -> codepoint10
\r
Carriage return; -> codepoint13
\t
Tab; -> codepoint9
\f
Form feed; -> codepoint12
\b
Backspace; -> codepoint92
\"
Double-quote; -> codepoint34
\'
Single-quote; -> codepoint39
\\
Backslash; -> codepoint92
\uFFFF
Unicode escape (4 hex characters to denote the codepoint)
If a backslash precedes any other character, that character will be interpretted literally: the backslash will essentially be ignored and removed from output.
Interpolation (a.k.a. Variable Substitution)
Values left unquoted or wrapped in double-quotes will interpolate variables
that are in the the ${VAR}
syntax. This can be useful to reference existing
system ENV values or to reference values previously set in a parsed file.
For example:
USER=admin
EMAIL=${USER}@example.org
DATABASE_URL="postgres://${USER}@localhost/my_database"
CACHE_DIR=${PWD}/cache
If a value must retain ${}
in its output and should not be substituted with
a value, wrap it in single quotes (see below).
Multi-line values (e.g. private keys) can use the triple-quoted heredoc syntax:
PRIVATE_KEY="""
-----BEGIN RSA PRIVATE KEY-----
...
HkVN9...
...
-----END DSA PRIVATE KEY-----
"""
Non-Interpolated
If your values must retain ${}
in their output, wrap the value in single quotes, e.g.:
PASSWORD='!@\\nG0${k}k'
MESSAGE_TEMPLATE='''
Hello ${PERSON},
Nice to meet you!
'''
Comments
The hash-tag #
symbol denotes comments, either on their own line or at the end
of a line, but not inside quotes.
# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # also a comment
SECRET_HASH="something-with-a-hash-#-this-is-not-a-comment"