Open-sourcing dotenv-linter: a lightning-fast tool to lint .env files

When developing applications, we always try to stick to the Manifesto of Twelve Factors. This approach helps you to avoid a number of the problems associated with the ongoing support of applications throughout their lifecycle. 

One of the principles of the manifesto is that all settings should be stored in environment variables, allowing you to alter them for different environments (development, automated testing, staging/QA, production) without changing the code.

However, during development, dealing with all of these variables can quickly become cumbersome. As a project grows, it's typical for the list of environment variables it uses to grow with it, resulting in unwieldy command lines such as these:

$ RAILS_ENV=development REDIS_URL=redis://redis:6379 DATABASE_URL=postgres://postgres:postgres@db:5432 bundle exec rails server

Fortunately, there's a solution: .env files. They provide a convenient way to store all environment variables in one place, and there are straightforward libraries in many languages (including Ruby, Elixir, Python, Go, and Rust) for working with them: all they do is load the variables from the file when the application starts.

However, it's not always plain sailing. Just like in the real world, your environment needs looking after. Sometimes, problems creep in without you noticing which may impact how your application works. What kind of problems? Well, for example:

• Key duplication. The more variables that you need to set for your application, the higher the chances you have of accidentally setting the same variable twice — when this happens, the new variables will typically overwrite the old values, but which one did you mean? And when you need to make a change, will you spot the duplicate?
• Incorrect word delimiter. Multi-word environment variable names use an underscore as a separator character (if one is used at all) — but it's easy to accidentally type a hyphen instead of an underscore and not notice it until much later.
• Key without value. A common tactic is to add a placeholder to a .env file — a variable with no value, to be filled in later; this works great, as long as you remember to go back and add the value in!
• Invalid first character. Environment variables should begin with a upper-case letter or an underscore.
• Lowercase keys. By convention, application environment variables are always all-uppercase.
• Spaces. Stray spaces, especially between the variable name and equals sign, can cause problems depending on how the variables are loaded.
• Sorting by key. It's not a technical requirement for libraries to use .env files properly, but we've found that when they're sorted by key, it's a lot easier to spot some of the errors described above.

All of the problems described are situations we've run into working on real projects. For that reason, dotenv-linter was created, a tool to check .env files for problems, that could be used as part of your day-to-day workflow! A lightning-fast checking tool, or "linter", for .env files, is developed as an open source project by Mikhail Grachev, Evrone’s software engineer.

Linter tools are named after the pieces of fluff that you sometimes find stuck to your clothes and use a lint roller or sticky tape to remove: they don't necessarily do any harm, but they're not especially desirable, either.

In contrast to looking for real-life lint on clothes, linter tools often look for things which can do harm, or at the very least are ambiguous enough to be firmly recommended against — such as our list above, which of course dotenv-linter handles all of (and blazingly quickly).

Installation

dotenv-linter is written in Rust, but you don't need to have anything to do with Rust to use it — it works with any project with .env files. Pre-built binaries are available for Linux and macOS, which you can download from Github. Instructions for fetching and unpacking the releases are shown below:

# Linux / macOS / Windows (MINGW and etc). Installs it into ./bin/ by default.
$ curl -sSfL https://raw.githubusercontent.com/dotenv-linter/dotenv-linter/master/install.sh | sh -s
# Specify installation directory and version.
$ curl -sSfL https://raw.githubusercontent.com/dotenv-linter/dotenv-linter/master/install.sh | sh -s -- -b usr/local/bin v2.0.0
# Alpine Linux (wget)
$ wget -q -O - https://raw.githubusercontent.com/dotenv-linter/dotenv-linter/master/install.sh | sh -s

If you prefer, you can install dotenv-linter on macOS using Homebrew:

$ brew install dotenv-linter/tap/dotenv-linter

Alternatively, you can use Docker to run it in a container:

$ docker run --rm -v `pwd`:/app -w /app dotenvlinter/dotenv-linter

Usage

With no parameters, dotenv-linter checks all .env files in the current directory:

$ dotenv-linter
.env:2 DuplicatedKey: The FOO key is duplicated
.env:3 UnorderedKey: The BAR key should go before the FOO key
.env.test:1 LeadingCharacter: Invalid leading character detected

To check a different directory, or a specific file, just specify their paths on the command-line to check all of them:

$ dotenv-linter dir1 dir2/.my-env-file
dir1/.env:1 LeadingCharacter: Invalid leading character detected
dir1/.env:3 IncorrectDelimiter: The FOO-BAR key has incorrect delimiter
dir2/.my-env-file:1 LowercaseKey: The bar key should be in uppercase

You can exclude files from the scan using the --exclude argument:

$ dotenv-linter --exclude .env.test
.env:2 DuplicatedKey: The FOO key is duplicated
.env:3 UnorderedKey: The BAR key should go before the FOO key

 dotenv-linter + reviewdog

You can easily integrate dotenv-linter with reviewdog, the automated code-review tool that works with GitHub and GitLab. Just pipe the output of dotenv-linter into reviewdog using the dotenv-linter format:

$ dotenv-linter | reviewdog -f=dotenv-linter -diff="git diff master"

On GitHub, you can easily enable dotenv-linter and reviewdog on your project with a ready-made GitHub Action.

 Evrone: supporting open-source

We're very happy to support the open-source projects our developers work on in any way that we can, and dotenv-linter is of course no exception, and we're pleased to have contributed the logo and brand identity to the project of our software developer Mikhail Grachev. The logo consists of an upturned letter “L”, reshaped to resemble lightning — representing the sheer speed of dotenv-linter — and we've used a red-orange hue that symbolises Rust, the language the linter's written in.

We've recently released the version v2.0.0 of dotenv-linter with:

• 4 new checks
• Ability to disable checks using the --skip argument
• Performance improvement
• Error correction

Also, GitHub released a Super-Linter, a source code repository that's packaged into a Docker container and called up by GitHub Actions. We're proud to have our dotenv-linter included in the list of supported linters, with which the developers can call the GitHub Action to lint their code base.

If you know Rust, and can think of ways that dotenv-linter can be improved, we'd be very happy to see you join us and help make it better for everyone. And, if you find yourself in need of developing a new useful tool, like a linter for checking code for your project, just reach out to us!