We have developed dotenv-linter — a useful tool for checking .env files. It helps to find problems in .env files that you might miss at first, but which later may result in incorrect work of applications. We made the tool universal, it can be connected to any project regardless of the programming language. Dotenv-linter is developed as an open-source project by Mikhail Grachev, Evrone’s software engineer.

What is a .env file?

A .env file or dotenv file is a simple text file that contains all the environment variables of a project. Storing configuration in the environment variables is one of the tenets of the Manifesto of Twelve-Factor App. The .env file has a simple key-value format, for example: FOO=BAR

We already wrote about the dotenv-linter v2.2.0 release. Two and a half months have passed since that moment, and we are ready to present you a new version of dotenv-linter — v3.0.0. Here's an overview of the key changes made in this release!

API improvements 👍

In the previous version, dotenv-linter had several flags, which were essentially separate commands  --fix and --show-checks:

FLAGS:
    -f, --fix            Automatically fixes warnings
    -h, --help           Prints help information
        --no-backup      Prevents .env files from being backed up when modified by -f/--fix
    -q, --quiet          Doesn't display additional information
    -r, --recursive      Recursively search and check .env files
        --show-checks    Shows list of available checks
    -v, --version        Prints version information

This has been leading to a bit of confusion. These flags clashed and did not work with each other well:

$ dotenv-linter --fix --show-checks

In the new version we have fixed this and moved the --fix and --show-checks flags into separate fix and list commands:

FLAGS:
    -h, --help         Prints help information
    -q, --quiet        Doesn't display additional information
    -r, --recursive    Recursively searches and checks .env files
    -v, --version      Prints version information


SUBCOMMANDS:
    fix        Automatically fixes warnings [aliases: f]
    list       Shows list of available checks [aliases: l]

Comparing .env files 🤲

Also, in the new version we added a new compare command, which allows you to compare keys in .env files:

$ dotenv-linter compare .env .env.example
Comparing .env
Comparing .env.example
.env is missing keys: BAR
.env.example is missing keys: FOO

Displaying scanned files 👀

With multiple .envfiles, it was not always clear which ones were checked by dotenv-linter and which ones weren't. This could be happening due to a non-standard file name, or the absence of any problems in these files. In the new version, we have added the display of scanned files:

$ dotenv-linter
Checking .env
.env:1 LeadingCharacter: Invalid leading character detected

Checking .env.example
Checking .env.test

Found 1 problem

You can disable this using the--quiet/-q flag:

$ dotenv-linter --quiet
.env:1 LeadingCharacter: Invalid leading character detected

Colored output 🌈

To improve usability, we have added a colored warning display:

You can disable color output using the --no-color flag.

Support for multi-line values 💪

Multi-line values can be stored in .envfiles. One of the options looks like this:

# .env
MULTILINE="new\nline"

But when checking such values, dotenv-linterused to display a warning:

$ dotenv-linter
.env:1 QuoteCharacter: The value has quote characters (', ")

Found 1 problem

We have fixed this and now dotenv-linter does not display warnings for multiline values wrapped in quotes.

Support for the export prefix 🔥

Some libraries for working with .env files, such as dotenv, godotenv and python-dotenvsupport the export prefix:

# .env
export S3_BUCKET=YOURS3BUCKET
export SECRET_KEY=YOURSECRETKEYGOESHERE

The exportprefix makes it possible to export environment variables from a file using the source command:

$ source .env

When checking such files, dotenv-linter always displayed warnings:

$ dotenv-linter
.env:1 IncorrectDelimiter: The export S3_BUCKET key has incorrect delimiter
.env:1 LowercaseKey: The export S3_BUCKET key should be in uppercase
.env:2 IncorrectDelimiter: The export SECRET_KEY key has incorrect delimiter
.env:2 LowercaseKey: The export SECRET_KEY key should be in uppercase

Found 4 problems

In the new version we added support for the export prefix and now dotenv-linter does not display any warnings.

Support for spaces 🙌

Another improvement is the support for spaces in values, wrapped in quotes:

# .env
WHITESPACES="a b c"

Now, for such values, dotenv-linter will not display warnings.

Improved validation 👌

Also, we fixed an issue where dotenv-linter did not display all warnings at once:

$ dotenv-linter fix .env
Fixing .env
Original file was backed up to: ".env_1606422805"

.env:1 KeyWithoutValue: The test key should be with a value or have an equal sign

All warnings are fixed. Total: 1

$ dotenv-linter .env
Checking .env
.env:1 LowercaseKey: The test key should be in uppercase

Found 1 problem

Performance improvements 🚀

Last but not least, we have improved the performance of the already fast dotenv-linter. The maximum start time has decreased from 9.3 ms to 4.3 ms (by more than 50%).

To check this, we made a benchmark using the hyperfine utility:

Command	                                Mean [ms]	Min [ms]    Max [ms]	Relative
dotenv-linter/dotenv-linter .env	2.7 ± 0.4	2.0	    4.3	        1.00
wemake-services/dotenv-linter .env	162.6 ± 12.1	153.0	    201.3	60.83 ± 10.20

These are all the key changes that are included in the new v3.0.0 release. Thanks to everyone who contributed! You can support the project by starring or sponsoring it on GitHub.

You can become a sponsor on GitHub Sponsors or OpenCollective ❤️