Dotenv 3.0

[bkeepers]

Update: 3.0.0 release is officially out now. Thanks to everyone who tried out the beta.

👋 after years of minimal changes, Dotenv 3.0 introduces several updates and improvements.

gem "dotenv", "~> 3.0.0"

Read the full 3.0.0 changelog, but I'll summarize a few of the more important or exciting parts.

Autorestore ENV (#472, #475)

ENV will be automatically restored between tests in Rails apps using both ActiveSupport::TestCase and Rspec. This means you can modify ENV in your tests without fear of leaking state to other tests.

test "does a thing if ENVAR is set" do
  ENV["ENVAR"] = "it's fine"
  # …
end

test "doesn't do a thing if ENVAR is not set" do
  assert_nil ENV["ENVAR"]
  # …
end

You can also manually modify and restore ENV using the modify method and passing a block:

Dotenv.modify(NEW_VAR: "value") do
  assert_equal "value", ENV["NEW_VAR"]
end
assert_nil ENV["NEW_VAR"]

See Dotenv.save, Dotenv.restore, and Dotenv.modify(hash) { ... } for manual usage.

To disable autorestore, set config.dotenv.autorestore = false in config/application.rb or config/environments/test.rb. To use this behavior outside of a Rails app, just require "dotenv/autorestore" in your test suite.

Ruby >= 3.0 and Rails >= 6.1 are now required. (#466, #471)

Going forward, the latest release of dotenv will drop support for EOL versions of Ruby and Rails. Lock dotenv to ~> 2.0 if you are using an outdated Ruby or Rails version.

Shell compatability (#423 by @nitsujri)

\n is no longer expanded into a newline in quoted strings. Use multi-line strings with real line breaks, or set DOTENV_LINEBREAK_MODE=legacy to preserve the old behavior.

- MY_MULTILINE_VAR="line1\nline2"
+ MY_MULTILINE_VAR="line1
+ line2"

Logging (#473)

All changes that dotenv performs to ENV will now be logged in Rails apps.

$ rails console
…
$ tail log/development.rb

$ rails console
> Dotenv.save
…
> ENV.update("PWD" => "/tmp", "NEW_VAR" => "foo")
…
> Dotenv.restore
…
$ tail log/development.rb

Other niceties

• Add -i/--ignore option to dotenv CLI to optionally ignore missing files. @stevenharman Optionally ignore missing files from cli #463
• You can customize which files get loaded by setting Dotenv::Rails.files. Include Rails integration in dotenv gem and refactor #468

Bug Fixes

Here's a few other important fixes:

• Fixed precedence when using Dotenv::Rails.overload. So now .env.development.local will overwrite .env.local, which will overwrite .env.development, which will overwrite .env. @eriklovmo - fix: always respect file importance order #460
• Fixed an issue where rake loaded development files (.env*development) for test-related tasks. Fix environment run running rake test #470

"Deprecations"

• Dotenv::Railtie has been renamed to Dotenv::Rails. Include Rails integration in dotenv gem and refactor #468
• The dotenv-rails gem is now superfluous. It's not technically deprecated yet and will continue to work, but the dotenv gem does the same thing. Include Rails integration in dotenv gem and refactor #468
• Dotenv.overload has been replaced with overwrite. overload will still work and is not technically deprecated, but documentation refers to Dotenv.overwrite now. Consistently use "overwrite" in place of "overload" and "override" #469

New Contributors

Thanks to these fine folks who made their first contribution:

• @stevenharman made their first contribution in Optionally ignore missing files from cli #463
• @eriklovmo made their first contribution in fix: always respect file importance order #460
• @nitsujri made their first contribution in Allow dotenv to load multiline strings like Ruby #423

Full Changelog: v2.8.1...v3.0.0.beta

[bkeepers]

I mentioned ClimateControl and IceAge in the original PR.

[mattbrictson]

Thanks for this! I'm using 3.0.0.beta in production for a couple projects; so far, so good.

[mvz]

I'm having a problem when using dotenv with a gem that implements a Rails engine and uses a dummy Rails app for testing: The dotenv paths are now fixed before Rails.root is set in the dummy application, so dotenv can't find the .env file anymore. Is this an expected change in behavior?

[bkeepers]

:wave @mvz,

I'm guessing this change is what's causing issues for you. Previously the paths were not determinuted until before_configuration callback, but now they become fixed when the Railtie is initialized. One idea here is to wait to join the paths with root at load time. I'll work up a PR and ping you on it.