dotenv 2.8.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac1a9e8e04f95f111da23bf2541070f2617864fc3c55ac4e11e6b91c78d11a9b
-  data.tar.gz: 24bf24be5be7020e72877e32d8cd2d9cf022a74b182569c77b2c81c0d482696b
+  metadata.gz: 1dc708aad5fcaf487b064451b8f47d5b0e402a7c250385f234306ab3c77fcf20
+  data.tar.gz: e939eca5e64f2aef9aeb784bd9765e20a3201057d4ed69c1ea46b1405625920e
 SHA512:
-  metadata.gz: 1f8d6ae3bfd67c1b57bc4d72346d670c02570d07cee953930d6b7f9018cc053ac42624d1bc4d59dd112abe5ba711d551199ff92a2672d5434577356b0a24d0c0
-  data.tar.gz: 38488d0f24d6f6014f87415775f94969cd56236bcb848c77b5dd4d066285ec47993006f87f1ab1afb50a033db101fe206741ec8e561de602a88717ad6fff3bdf
+  metadata.gz: 3c7a9b929e7b419a1df9c07bd2dfa7959deea186bc6de9e0e8bdfdc671b7d4c183104715206ac956e81d4689b76d14907dd0a644eb995f4cd48437047e307ad1
+  data.tar.gz: de3d64ad2bf4fbec40e7c253c71de40cf1cab82875293f168c73a5098e7419554362014e6eb0c6339d485c41c12cccad82e0f854fee30f7fef18e7cc4afc26ef

data/README.md

@@ -1,4 +1,4 @@
-# dotenv [![Gem Version](https://badge.fury.io/rb/dotenv.svg)](https://badge.fury.io/rb/dotenv) [![Join the chat at https://gitter.im/bkeepers/dotenv](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/bkeepers/dotenv?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+# dotenv [![Gem Version](https://badge.fury.io/rb/dotenv.svg)](https://badge.fury.io/rb/dotenv)
 
 Shim to load environment variables from `.env` into `ENV` in *development*.
 
@@ -8,52 +8,36 @@ But it is not always practical to set environment variables on development machi
 
 ## Installation
 
-### Rails
-
-Add this line to the top of your application's Gemfile:
+Add this line to the top of your application's Gemfile and run `bundle install`:
 
 ```ruby
-gem 'dotenv-rails', groups: [:development, :test]
+gem 'dotenv', groups: [:development, :test]
 ```
 
-And then execute:
+## Usage
+
+Add your application configuration to your `.env` file in the root of your project:
 
 ```shell
-$ bundle
+S3_BUCKET=YOURS3BUCKET
+SECRET_KEY=YOURSECRETKEYGOESHERE
 ```
 
-#### Note on load order
-
-dotenv is initialized in your Rails app during the `before_configuration` callback, which is fired when the `Application` constant is defined in `config/application.rb` with `class Application < Rails::Application`. If you need it to be initialized sooner, you can manually call `Dotenv::Railtie.load`.
+Whenever your application loads, these variables will be available in `ENV`:
 
 ```ruby
-# config/application.rb
-Bundler.require(*Rails.groups)
-
-# Load dotenv only in development or test environment
-if ['development', 'test'].include? ENV['RAILS_ENV']
-  Dotenv::Railtie.load
-end
-
-HOSTNAME = ENV['HOSTNAME']
+config.fog_directory = ENV['S3_BUCKET']
 ```
 
-If you use gems that require environment variables to be set before they are loaded, then list `dotenv-rails` in the `Gemfile` before those other gems and require `dotenv/rails-now`.
+See the [API Docs](https://rubydoc.info/github/bkeepers/dotenv/main) for more.
 
-```ruby
-gem 'dotenv-rails', require: 'dotenv/rails-now'
-gem 'gem-that-requires-env-variables'
-```
-
-### Sinatra or Plain ol' Ruby
+### Rails
 
-Install the gem:
+Dotenv will automatically load when your Rails app boots. See [Customizing Rails](#customizing-rails) to change which files are loaded and when.
 
-```shell
-$ gem install dotenv
-```
+### Sinatra / Ruby
 
-As early as possible in your application bootstrap process, load `.env`:
+Load Dotenv as early as possible in your application bootstrap process:
 
 ```ruby
 require 'dotenv/load'
@@ -70,17 +54,17 @@ require 'dotenv'
 Dotenv.load('file1.env', 'file2.env')
 ```
 
-Alternatively, you can use the `dotenv` executable to launch your application:
+### Autorestore in tests
 
-```shell
-$ dotenv ./script.rb
-```
+Since 3.0, dotenv in a Rails app will automatically restore `ENV` after each test. This means you can modify `ENV` in your tests without fear of leaking state to other tests. It works with both `ActiveSupport::TestCase` and `Rspec`.
 
-The `dotenv` executable also accepts a single flag, `-f`. Its value should be a comma-separated list of configuration files, in the order of most important to least. All of the files must exist. There _must_ be a space between the flag and its value.
+To disable this behavior, set `config.dotenv.autorestore = false` in `config/application.rb` or `config/environments/test.rb`. It is disabled by default if your app uses [climate_control](https://github.com/thoughtbot/climate_control) or [ice_age](https://github.com/dpep/ice_age_rb).
 
-```
-$ dotenv -f ".env.local,.env" ./script.rb
-```
+To use this behavior outside of a Rails app, just `require "dotenv/autorestore"` in your test suite.
+
+See [`Dotenv.save`](https://rubydoc.info/github/bkeepers/dotenv/main/Dotenv:save), [Dotenv.restore](https://rubydoc.info/github/bkeepers/dotenv/main/Dotenv:restore), and [`Dotenv.modify(hash) { ... }`](https://rubydoc.info/github/bkeepers/dotenv/main/Dotenv:modify) for manual usage.
+
+### Rake
 
 To ensure `.env` is loaded in rake, load the tasks:
 
@@ -88,41 +72,121 @@ To ensure `.env` is loaded in rake, load the tasks:
 require 'dotenv/tasks'
 
 task mytask: :dotenv do
-    # things that require .env
+  # things that require .env
 end
 ```
 
-## Usage
+### CLI
 
-Add your application configuration to your `.env` file in the root of your project:
+You can use the `dotenv` executable load `.env` before launching your application:
 
-```shell
-S3_BUCKET=YOURS3BUCKET
-SECRET_KEY=YOURSECRETKEYGOESHERE
+```console
+$ dotenv ./script.rb
 ```
 
-Whenever your application loads, these variables will be available in `ENV`:
+The `dotenv` executable also accepts the flag `-f`. Its value should be a comma-separated list of configuration files, in the order of most important to least. All of the files must exist. There _must_ be a space between the flag and its value.
 
-```ruby
-config.fog_directory  = ENV['S3_BUCKET']
+```console
+$ dotenv -f ".env.local,.env" ./script.rb
 ```
 
-You may also add `export` in front of each line so you can `source` the file in bash:
+The `dotenv` executable can optionally ignore missing files with the `-i` or `--ignore` flag. For example, if the `.env.local` file does not exist, the following will ignore the missing file and only load the `.env` file.
 
-```shell
-export S3_BUCKET=YOURS3BUCKET
-export SECRET_KEY=YOURSECRETKEYGOESHERE
+```console
+$ dotenv -i -f ".env.local,.env" ./script.rb
 ```
 
-### Multi-line values
+### Load Order
 
-If you need multiline variables, for example private keys, you can double quote strings and use the `\n` character for newlines:
+If you use gems that require environment variables to be set before they are loaded, then list `dotenv` in the `Gemfile` before those other gems and require `dotenv/load`.
 
-```shell
-PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
+```ruby
+gem 'dotenv', require: 'dotenv/load'
+gem 'gem-that-requires-env-variables'
+```
+
+### Customizing Rails
+
+Dotenv will load the following files depending on `RAILS_ENV`, with the first file having the highest precedence, and `.env` having the lowest precedence:
+
+<table>
+  <thead>
+    <tr>
+      <th>Priority</th>
+      <th colspan="3">Environment</th>
+      <th><code>.gitignore</code>it?</th>
+      <th>Notes</th>
+    </tr>
+    <tr>
+      <th></th>
+      <th>development</th>
+      <th>test</th>
+      <th>production</th>
+      <th></th>
+      <th></th>
+    </tr>
+  </thead>
+  <tr>
+    <td>highest</td>
+    <td><code>.env.development.local</code></td>
+    <td><code>.env.test.local</code></td>
+    <td><code>.env.production.local</code></td>
+    <td>Yes</td>
+    <td>Environment-specific local overrides</td>
+  </tr>
+  <tr>
+    <td>2nd</td>
+    <td><code>.env.local</code></td>
+    <td><strong>N/A</strong></td>
+    <td><code>.env.local</code></td>
+    <td>Yes</td>
+    <td>Local overrides</td>
+  </tr>
+  <tr>
+    <td>3rd</td>
+    <td><code>.env.development</code></td>
+    <td><code>.env.test</code></td>
+    <td><code>.env.production</code></td>
+    <td>No</td>
+    <td>Shared environment-specific variables</td>
+  </tr>
+  <tr>
+    <td>last</td>
+    <td><code>.env</code></td>
+    <td><code>.env</code></td>
+    <td><code>.env</code></td>
+    <td><a href="#should-i-commit-my-env-file">Maybe</a></td>
+    <td>Shared for all environments</td>
+  </tr>
+</table>
+
+
+These files are loaded during the `before_configuration` callback, which is fired when the `Application` constant is defined in `config/application.rb` with `class Application < Rails::Application`. If you need it to be initialized sooner, or need to customize the loading process, you can do so at the top of `application.rb`
+
+```ruby
+# config/application.rb
+Bundler.require(*Rails.groups)
+
+# Load .env.local in test
+Dotenv::Rails.files.unshift(".env.local") if ENV["RAILS_ENV"] == "test"
+
+module YourApp
+  class Application < Rails::Application
+    # ...
+  end
+end
 ```
 
-Alternatively, multi-line values with line breaks are now supported for quoted values.
+Available options:
+
+* `Dotenv::Rails.files` - list of files to be loaded, in order of precedence.
+* `Dotenv::Rails.overwrite` - Overwrite exiting `ENV` variables with contents of `.env*` files
+* `Dotenv::Rails.logger` - The logger to use for dotenv's logging. Defaults to `Rails.logger`
+* `Dotenv::Rails.autorestore` - Enable or disable [autorestore](#autorestore-in-tests)
+
+### Multi-line values
+
+Multi-line values with line breaks must be surrounded with double quotes.
 
 ```shell
 PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
@@ -132,7 +196,12 @@ HkVN9...
 -----END DSA PRIVATE KEY-----"
 ```
 
-This is particularly helpful when using the Heroku command line plugin [`heroku-config`](https://github.com/xavdid/heroku-config) to pull configuration variables down that may have line breaks.
+Prior to 3.0, dotenv would replace `\n` in quoted strings with a newline, but that behavior is deprecated. To use the old behavior, set `DOTENV_LINEBREAK_MODE=legacy` before any variables that include `\n`:
+
+```shell
+DOTENV_LINEBREAK_MODE=legacy
+PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
+```
 
 ### Command Substitution
 
@@ -166,6 +235,15 @@ SECRET_KEY=YOURSECRETKEYGOESHERE # comment
 SECRET_HASH="something-with-a-#-hash"
 ```
 
+### Exports
+
+For compatability, you may also add `export` in front of each line so you can `source` the file in bash:
+
+```shell
+export S3_BUCKET=YOURS3BUCKET
+export SECRET_KEY=YOURSECRETKEYGOESHERE
+```
+
 ### Required Keys
 
 If a particular configuration value is required but not set, it's appropriate to raise an error.
@@ -191,39 +269,11 @@ Dotenv.parse(".env.local", ".env")
 
 This method returns a hash of the ENV var name/value pairs.
 
-## Frequently Answered Questions
-
-### Can I use dotenv in production?
-
-dotenv was originally created to load configuration variables into `ENV` in *development*. There are typically better ways to manage configuration in production environments - such as `/etc/environment` managed by [Puppet](https://github.com/puppetlabs/puppet) or [Chef](https://github.com/chef/chef), `heroku config`, etc.
-
-However, some find dotenv to be a convenient way to configure Rails applications in staging and production environments, and you can do that by defining environment-specific files like `.env.production` or `.env.test`.
-
-If you use this gem to handle env vars for multiple Rails environments (development, test, production, etc.), please note that env vars that are general to all environments should be stored in `.env`. Then, environment specific env vars should be stored in `.env.<that environment's name>`.
-
-### What other .env* files can I use?
-
-`dotenv-rails` will override in the following order (highest defined variable overrides lower):
-
-| Hierarchy Priority | Filename                 | Environment          | Should I `.gitignore`it?                            | Notes                                                        |
-| ------------------ | ------------------------ | -------------------- | --------------------------------------------------- | ------------------------------------------------------------ |
-| 1st (highest)      | `.env.development.local` | Development          | Yes!                                                | Local overrides of environment-specific settings.            |
-| 1st                | `.env.test.local`        | Test                 | Yes!                                                | Local overrides of environment-specific settings.            |
-| 1st                | `.env.production.local`  | Production           | Yes!                                                | Local overrides of environment-specific settings.            |
-| 2nd                | `.env.local`             | Wherever the file is | Definitely.                                         | Local overrides. This file is loaded for all environments _except_ `test`. |
-| 3rd                | `.env.development`       | Development          | No.                                                 | Shared environment-specific settings                         |
-| 3rd                | `.env.test`              | Test                 | No.                                                 | Shared environment-specific settings                         |
-| 3rd                | `.env.production`        | Production           | No.                                                 | Shared environment-specific settings                         |
-| Last               | `.env`                   | All Environments     | Depends (See [below](#should-i-commit-my-env-file)) | The Original®                                                |
-
-
-### Should I commit my .env file?
-
-Credentials should only be accessible on the machines that need access to them. Never commit sensitive information to a repository that is not needed by every development machine and server.
-
+### Templates
 
 You can use the `-t` or `--template` flag on the dotenv cli to create a template of your `.env` file.
-```shell
+
+```console
 $ dotenv -t .env
 ```
 A template will be created in your working directory named `{FINAME}.template`. So in the above example, it would create a `.env.template` file.
@@ -244,14 +294,29 @@ S3_BUCKET=S3_BUCKET
 SECRET_KEY=SECRET_KEY
 ```
 
+## Frequently Answered Questions
+
+### Can I use dotenv in production?
+
+dotenv was originally created to load configuration variables into `ENV` in *development*. There are typically better ways to manage configuration in production environments - such as `/etc/environment` managed by [Puppet](https://github.com/puppetlabs/puppet) or [Chef](https://github.com/chef/chef), `heroku config`, etc.
+
+However, some find dotenv to be a convenient way to configure Rails applications in staging and production environments, and you can do that by defining environment-specific files like `.env.production` or `.env.test`.
+
+If you use this gem to handle env vars for multiple Rails environments (development, test, production, etc.), please note that env vars that are general to all environments should be stored in `.env`. Then, environment specific env vars should be stored in `.env.<that environment's name>`.
+
+### Should I commit my .env file?
+
+Credentials should only be accessible on the machines that need access to them. Never commit sensitive information to a repository that is not needed by every development machine and server.
+
 Personally, I prefer to commit the `.env` file with development-only settings. This makes it easy for other developers to get started on the project without compromising credentials for other environments. If you follow this advice, make sure that all the credentials for your development environment are different from your other deployments and that the development credentials do not have access to any confidential data.
 
-### Why is it not overriding existing `ENV` variables?
+### Why is it not overwriting existing `ENV` variables?
 
-By default, it **won't** overwrite existing environment variables as dotenv assumes the deployment environment has more knowledge about configuration than the application does. To overwrite existing environment variables you can use `Dotenv.overload`.
+By default, it **won't** overwrite existing environment variables as dotenv assumes the deployment environment has more knowledge about configuration than the application does. To overwrite existing environment variables you can use `Dotenv.load files, overwrite: true`.
 
-You can also use the `-o` or `--overload` flag on the dotenv cli to override existing `ENV` variables.
-```shell
+You can also use the `-o` or `--overwrite` flag on the dotenv cli to overwrite existing `ENV` variables.
+
+```console
 $ dotenv -o -f ".env.local,.env"
 ```
 

data/lib/dotenv/autorestore.rb

@@ -0,0 +1,29 @@
+# Automatically restore `ENV` to its original state after
+
+if defined?(RSpec.configure)
+  RSpec.configure do |config|
+    # Save ENV before the suite starts
+    config.before(:suite) { Dotenv.save }
+
+    # Restore ENV after each example
+    config.after { Dotenv.restore }
+  end
+end
+
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:active_support_test_case) do
+    ActiveSupport::TestCase.class_eval do
+      # Save ENV before each test
+      setup { Dotenv.save }
+
+      # Restore ENV after each test
+      teardown do
+        Dotenv.restore
+      rescue ThreadError => e
+        # Restore will fail if running tests in parallel.
+        warn e.message
+        warn "Set `config.dotenv.autorestore = false` in `config/initializers/test.rb`" if defined?(Dotenv::Rails)
+      end
+    end
+  end
+end

data/lib/dotenv/cli.rb

@@ -4,26 +4,32 @@ require "dotenv/template"
 require "optparse"
 
 module Dotenv
-  # The command line interface
+  # The `dotenv` command line interface. Run `$ dotenv --help` to see usage.
   class CLI < OptionParser
-    attr_reader :argv, :filenames, :overload
+    attr_reader :argv, :filenames, :overwrite
 
     def initialize(argv = [])
       @argv = argv.dup
       @filenames = []
-      @overload = false
+      @ignore = false
+      @overwrite = false
 
-      super "Usage: dotenv [options]"
+      super("Usage: dotenv [options]")
       separator ""
 
       on("-f FILES", Array, "List of env files to parse") do |list|
         @filenames = list
       end
 
-      on("-o", "--overload", "override existing ENV variables") do
-        @overload = true
+      on("-i", "--ignore", "ignore missing env files") do
+        @ignore = true
       end
 
+      on("-o", "--overwrite", "overwrite existing ENV variables") do
+        @overwrite = true
+      end
+      on("--overload") { @overwrite = true }
+
       on("-h", "--help", "Display help") do
         puts self
         exit
@@ -43,11 +49,7 @@ module Dotenv
     end
 
     def run
-      if @overload
-        Dotenv.overload!(*@filenames)
-      else
-        Dotenv.load!(*@filenames)
-      end
+      Dotenv.load(*@filenames, overwrite: @overwrite, ignore: @ignore)
     rescue Errno::ENOENT => e
       abort e.message
     else

data/lib/dotenv/diff.rb

@@ -0,0 +1,56 @@
+module Dotenv
+  # A diff between multiple states of ENV.
+  class Diff
+    # The initial state
+    attr_reader :a
+
+    # The final or current state
+    attr_reader :b
+
+    # Create a new diff. If given a block, the state of ENV after the block will be preserved as
+    # the final state for comparison. Otherwise, the current ENV will be the final state.
+    #
+    # @param a [Hash] the initial state, defaults to a snapshot of current ENV
+    # @param b [Hash] the final state, defaults to the current ENV
+    # @yield [diff] a block to execute before recording the final state
+    def initialize(a: snapshot, b: ENV, &block)
+      @a, @b = a, b
+      block&.call self
+    ensure
+      @b = snapshot if block
+    end
+
+    # Return a Hash of keys added with their new values
+    def added
+      b.slice(*(b.keys - a.keys))
+    end
+
+    # Returns a Hash of keys removed with their previous values
+    def removed
+      a.slice(*(a.keys - b.keys))
+    end
+
+    # Returns of Hash of keys changed with an array of their previous and new values
+    def changed
+      (b.slice(*a.keys).to_a - a.to_a).map do |(k, v)|
+        [k, [a[k], v]]
+      end.to_h
+    end
+
+    # Returns a Hash of all added, changed, and removed keys and their new values
+    def env
+      b.slice(*(added.keys + changed.keys)).merge(removed.transform_values { |v| nil })
+    end
+
+    # Returns true if any keys were added, removed, or changed
+    def any?
+      [added, removed, changed].any?(&:any?)
+    end
+
+    private
+
+    def snapshot
+      ENV.to_h.freeze
+    end
+  end
+end

data/lib/dotenv/environment.rb

@@ -1,28 +1,25 @@
 module Dotenv
-  # This class inherits from Hash and represents the environment into which
-  # Dotenv will load key value pairs from a file.
+  # A `.env` file that will be read and parsed into a Hash
   class Environment < Hash
-    attr_reader :filename
+    attr_reader :filename, :overwrite
 
-    def initialize(filename, is_load = false)
+    # Create a new Environment
+    #
+    # @param filename [String] the path to the file to read
+    # @param overwrite [Boolean] whether the parser should assume existing values will be overwritten
+    def initialize(filename, overwrite: false)
+      super()
       @filename = filename
-      load(is_load)
+      @overwrite = overwrite
+      load
     end
 
-    def load(is_load = false)
-      update Parser.call(read, is_load)
+    def load
+      update Parser.call(read, overwrite: overwrite)
     end
 
     def read
       File.open(@filename, "rb:bom|utf-8", &:read)
     end
-
-    def apply
-      each { |k, v| ENV[k] ||= v }
-    end
-
-    def apply!
-      each { |k, v| ENV[k] = v }
-    end
   end
 end

data/lib/dotenv/load.rb

@@ -1,2 +1,3 @@
 require "dotenv"
-Dotenv.load
+
+defined?(Dotenv::Rails) ? Dotenv::Rails.load : Dotenv.load

data/lib/dotenv/log_subscriber.rb

@@ -0,0 +1,61 @@
+require "active_support/log_subscriber"
+
+module Dotenv
+  # Logs instrumented events
+  #
+  # Usage:
+  #   require "active_support/notifications"
+  #   require "dotenv/log_subscriber"
+  #   Dotenv.instrumenter = ActiveSupport::Notifications
+  #
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    attach_to :dotenv
+
+    def logger
+      Dotenv::Rails.logger
+    end
+
+    def load(event)
+      env = event.payload[:env]
+
+      info "Loaded #{color_filename(env.filename)}"
+    end
+
+    def update(event)
+      diff = event.payload[:diff]
+      changed = diff.env.keys.map { |key| color_var(key) }
+      debug "Set #{changed.to_sentence}" if diff.any?
+    end
+
+    def save(event)
+      info "Saved a snapshot of #{color_env_constant}"
+    end
+
+    def restore(event)
+      diff = event.payload[:diff]
+
+      removed = diff.removed.keys.map { |key| color(key, :RED) }
+      restored = (diff.changed.keys + diff.added.keys).map { |key| color_var(key) }
+
+      if removed.any? || restored.any?
+        info "Restored snapshot of #{color_env_constant}"
+        debug "Unset #{removed.to_sentence}" if removed.any?
+        debug "Restored #{restored.to_sentence}" if restored.any?
+      end
+    end
+
+    private
+
+    def color_filename(filename)
+      color(Pathname.new(filename).relative_path_from(Dotenv::Rails.root.to_s).to_s, :YELLOW)
+    end
+
+    def color_var(name)
+      color(name, :CYAN)
+    end
+
+    def color_env_constant
+      color("ENV", :GREEN)
+    end
+  end
+end

data/lib/dotenv/missing_keys.rb

@@ -3,7 +3,7 @@ module Dotenv
 
   class MissingKeys < Error # :nodoc:
     def initialize(keys)
-      key_word = "key#{keys.size > 1 ? "s" : ""}"
+      key_word = "key#{(keys.size > 1) ? "s" : ""}"
       super("Missing required configuration #{key_word}: #{keys.inspect}")
     end
   end

data/lib/dotenv/parser.rb

@@ -2,11 +2,11 @@ require "dotenv/substitutions/variable"
 require "dotenv/substitutions/command" if RUBY_VERSION > "1.8.7"
 
 module Dotenv
+  # Error raised when encountering a syntax error while parsing a .env file.
   class FormatError < SyntaxError; end
 
-  # This class enables parsing of a string for key value pairs to be returned
-  # and stored in the Environment. It allows for variable substitutions and
-  # exporting of variables.
+  # Parses the `.env` file format into key/value pairs.
+  # It allows for variable substitutions, command substitutions, and exporting of variables.
   class Parser
     @substitutions =
       [Dotenv::Substitutions::Variable, Dotenv::Substitutions::Command]
@@ -32,15 +32,15 @@ module Dotenv
     class << self
       attr_reader :substitutions
 
-      def call(string, is_load = false)
-        new(string, is_load).call
+      def call(...)
+        new(...).call
       end
     end
 
-    def initialize(string, is_load = false)
+    def initialize(string, overwrite: false)
       @string = string
       @hash = {}
-      @is_load = is_load
+      @overwrite = overwrite
     end
 
     def call
@@ -80,11 +80,15 @@ module Dotenv
     end
 
     def expand_newlines(value)
-      value.gsub('\n', "\n").gsub('\r', "\r")
+      if (@hash["DOTENV_LINEBREAK_MODE"] || ENV["DOTENV_LINEBREAK_MODE"]) == "legacy"
+        value.gsub('\n', "\n").gsub('\r', "\r")
+      else
+        value.gsub('\n', "\\\\\\n").gsub('\r', "\\\\\\r")
+      end
     end
 
     def variable_not_set?(line)
-      !line.split[1..-1].all? { |var| @hash.member?(var) }
+      !line.split[1..].all? { |var| @hash.member?(var) }
     end
 
     def unescape_value(value, maybe_quote)
@@ -100,7 +104,7 @@ module Dotenv
     def perform_substitutions(value, maybe_quote)
       if maybe_quote != "'"
         self.class.substitutions.each do |proc|
-          value = proc.call(value, @hash, @is_load)
+          value = proc.call(value, @hash, overwrite: @overwrite)
         end
       end
       value

data/lib/dotenv/rails-now.rb

@@ -0,0 +1,10 @@
+# If you use gems that require environment variables to be set before they are
+# loaded, then list `dotenv` in the `Gemfile` before those other gems and
+# require `dotenv/load`.
+#
+#     gem "dotenv", require: "dotenv/load"
+#     gem "gem-that-requires-env-variables"
+#
+
+require "dotenv/load"
+warn '[DEPRECATION] `require "dotenv/rails-now"` is deprecated. Use `require "dotenv/load"` instead.', caller(1..1).first

data/lib/dotenv/rails.rb

@@ -0,0 +1,114 @@
+# Since rubygems doesn't support optional dependencies, we have to manually check
+unless Gem::Requirement.new(">= 6.1").satisfied_by?(Gem::Version.new(Rails.version))
+  warn "dotenv 3.0 only supports Rails 6.1 or later. Use dotenv ~> 2.0."
+  return
+end
+
+require "dotenv/replay_logger"
+require "dotenv/log_subscriber"
+
+Dotenv.instrumenter = ActiveSupport::Notifications
+
+# Watch all loaded env files with Spring
+begin
+  require "spring/commands"
+  ActiveSupport::Notifications.subscribe("load.dotenv") do |*args|
+    event = ActiveSupport::Notifications::Event.new(*args)
+    Spring.watch event.payload[:env].filename if Rails.application
+  end
+rescue LoadError, ArgumentError
+  # Spring is not available
+end
+
+module Dotenv
+  # Rails integration for using Dotenv to load ENV variables from a file
+  class Rails < ::Rails::Railtie
+    delegate :files, :files=, :overwrite, :overwrite=, :autorestore, :autorestore=, :logger, to: "config.dotenv"
+
+    def initialize
+      super()
+      config.dotenv = ActiveSupport::OrderedOptions.new.update(
+        # Rails.logger is not available yet, so we'll save log messages and replay them when it is
+        logger: Dotenv::ReplayLogger.new,
+        overwrite: false,
+        files: [
+          ".env.#{env}.local",
+          (".env.local" unless env.test?),
+          ".env.#{env}",
+          ".env"
+        ].compact,
+        autorestore: env.test? && !defined?(ClimateControl) && !defined?(IceAge)
+      )
+    end
+
+    # Public: Load dotenv
+    #
+    # This will get called during the `before_configuration` callback, but you
+    # can manually call `Dotenv::Rails.load` if you needed it sooner.
+    def load
+      Dotenv.load(*files.map { |file| root.join(file).to_s }, overwrite: overwrite)
+    end
+
+    def overload
+      deprecator.warn("Dotenv::Rails.overload is deprecated. Set `Dotenv::Rails.overwrite = true` and call Dotenv::Rails.load instead.")
+      Dotenv.load(*files.map { |file| root.join(file).to_s }, overwrite: true)
+    end
+
+    # Internal: `Rails.root` is nil in Rails 4.1 before the application is
+    # initialized, so this falls back to the `RAILS_ROOT` environment variable,
+    # or the current working directory.
+    def root
+      ::Rails.root || Pathname.new(ENV["RAILS_ROOT"] || Dir.pwd)
+    end
+
+    # Set a new logger and replay logs
+    def logger=(new_logger)
+      logger.replay new_logger if logger.is_a?(ReplayLogger)
+      config.dotenv.logger = new_logger
+    end
+
+    # The current environment that the app is running in.
+    #
+    # When running `rake`, the Rails application is initialized in development, so we have to
+    # check which rake tasks are being run to determine the environment.
+    #
+    # See https://github.com/bkeepers/dotenv/issues/219
+    def env
+      @env ||= if defined?(Rake.application) && Rake.application.top_level_tasks.grep(TEST_RAKE_TASKS).any?
+        env = Rake.application.options.show_tasks ? "development" : "test"
+        ActiveSupport::EnvironmentInquirer.new(env)
+      else
+        ::Rails.env
+      end
+    end
+    TEST_RAKE_TASKS = /^(default$|test(:|$)|parallel:spec|spec(:|$))/
+
+    def deprecator # :nodoc:
+      @deprecator ||= ActiveSupport::Deprecation.new
+    end
+
+    # Rails uses `#method_missing` to delegate all class methods to the
+    # instance, which means `Kernel#load` gets called here. We don't want that.
+    def self.load
+      instance.load
+    end
+
+    initializer "dotenv", after: :initialize_logger do |app|
+      if logger.is_a?(ReplayLogger)
+        self.logger = ActiveSupport::TaggedLogging.new(::Rails.logger).tagged("dotenv")
+      end
+    end
+
+    initializer "dotenv.deprecator" do |app|
+      app.deprecators[:dotenv] = deprecator if app.respond_to?(:deprecators)
+    end
+
+    initializer "dotenv.autorestore" do |app|
+      require "dotenv/autorestore" if autorestore
+    end
+
+    config.before_configuration { load }
+  end
+
+  Railtie = ActiveSupport::Deprecation::DeprecatedConstantProxy.new("Dotenv::Railtie", "Dotenv::Rails", Dotenv::Rails.deprecator)
+end

data/lib/dotenv/replay_logger.rb

@@ -0,0 +1,20 @@
+module Dotenv
+  # A logger that can be used before the apps real logger is initialized.
+  class ReplayLogger < Logger
+    def initialize
+      super(nil) # Doesn't matter what this is, it won't be used.
+      @logs = []
+    end
+
+    # Override the add method to store logs so we can replay them to a real logger later.
+    def add(*args, &block)
+      @logs.push([args, block])
+    end
+
+    # Replay the store logs to a real logger.
+    def replay(logger)
+      @logs.each { |args, block| logger.add(*args, &block) }
+      @logs.clear
+    end
+  end
+end

data/lib/dotenv/substitutions/command.rb

@@ -20,7 +20,7 @@ module Dotenv
           )
         /x
 
-        def call(value, _env, _is_load)
+        def call(value, _env, overwrite: false)
           # Process interpolated shell commands
           value.gsub(INTERPOLATED_SHELL_COMMAND) do |*|
             # Eliminate opening and closing parentheses
@@ -28,7 +28,7 @@ module Dotenv
 
             if $LAST_MATCH_INFO[:backslash]
               # Command is escaped, don't replace it.
-              $LAST_MATCH_INFO[0][1..-1]
+              $LAST_MATCH_INFO[0][1..]
             else
               # Execute the command and return the value
               `#{command}`.chomp

data/lib/dotenv/substitutions/variable.rb

@@ -18,8 +18,8 @@ module Dotenv
           \}?           # closing brace
         /xi
 
-        def call(value, env, is_load)
-          combined_env = is_load ? env.merge(ENV) : ENV.to_h.merge(env)
+        def call(value, env, overwrite: false)
+          combined_env = overwrite ? ENV.to_h.merge(env) : env.merge(ENV)
           value.gsub(VARIABLE) do |variable|
             match = $LAST_MATCH_INFO
             substitute(match, variable, combined_env)
@@ -30,7 +30,7 @@ module Dotenv
 
         def substitute(match, variable, env)
           if match[1] == "\\"
-            variable[1..-1]
+            variable[1..]
           elsif match[3]
             env.fetch(match[3], "")
           else

data/lib/dotenv/template.rb

@@ -20,7 +20,7 @@ module Dotenv
       var, value = line.split("=")
       template = var.gsub(EXPORT_COMMAND, "")
       is_a_comment = var.strip[0].eql?("#")
-      value.nil? || is_a_comment ? line : "#{var}=#{template}"
+      (value.nil? || is_a_comment) ? line : "#{var}=#{template}"
     end
   end
 end

data/lib/dotenv/version.rb

@@ -1,3 +1,3 @@
 module Dotenv
-  VERSION = "2.8.1".freeze
+  VERSION = "3.1.0".freeze
 end

data/lib/dotenv.rb

@@ -1,75 +1,121 @@
 require "dotenv/parser"
 require "dotenv/environment"
 require "dotenv/missing_keys"
+require "dotenv/diff"
 
-# The top level Dotenv module. The entrypoint for the application logic.
+# Shim to load environment variables from `.env files into `ENV`.
 module Dotenv
-  class << self
-    attr_accessor :instrumenter
-  end
+  extend self
+
+  # An internal monitor to synchronize access to ENV in multi-threaded environments.
+  SEMAPHORE = Monitor.new
+  private_constant :SEMAPHORE
 
-  module_function
+  attr_accessor :instrumenter
 
-  def load(*filenames)
-    with(*filenames) do |f|
-      ignoring_nonexistent_files do
-        env = Environment.new(f, true)
-        instrument("dotenv.load", env: env) { env.apply }
+  # Loads environment variables from one or more `.env` files. See `#parse` for more details.
+  def load(*filenames, overwrite: false, ignore: true)
+    parse(*filenames, overwrite: overwrite, ignore: ignore) do |env|
+      instrument(:load, env: env) do |payload|
+        update(env, overwrite: overwrite)
       end
     end
   end
 
-  # same as `load`, but raises Errno::ENOENT if any files don't exist
+  # Same as `#load`, but raises Errno::ENOENT if any files don't exist
   def load!(*filenames)
-    with(*filenames) do |f|
-      env = Environment.new(f, true)
-      instrument("dotenv.load", env: env) { env.apply }
-    end
+    load(*filenames, ignore: false)
+  end
+
+  # same as `#load`, but will overwrite existing values in `ENV`
+  def overwrite(*filenames)
+    load(*filenames, overwrite: true)
+  end
+  alias_method :overload, :overwrite
+
+  # same as `#overwrite`, but raises Errno::ENOENT if any files don't exist
+  def overwrite!(*filenames)
+    load(*filenames, overwrite: true, ignore: false)
   end
+  alias_method :overload!, :overwrite!
 
-  # same as `load`, but will override existing values in `ENV`
-  def overload(*filenames)
-    with(*filenames) do |f|
-      ignoring_nonexistent_files do
-        env = Environment.new(f, false)
-        instrument("dotenv.overload", env: env) { env.apply! }
+  # Parses the given files, yielding for each file if a block is given.
+  #
+  # @param filenames [String, Array<String>] Files to parse
+  # @param overwrite [Boolean] Overwrite existing `ENV` values
+  # @param ignore [Boolean] Ignore non-existent files
+  # @param block [Proc] Block to yield for each parsed `Dotenv::Environment`
+  # @return [Hash] parsed key/value pairs
+  def parse(*filenames, overwrite: false, ignore: true, &block)
+    filenames << ".env" if filenames.empty?
+    filenames = filenames.reverse if overwrite
+
+    filenames.reduce({}) do |hash, filename|
+      begin
+        env = Environment.new(File.expand_path(filename), overwrite: overwrite)
+        env = block.call(env) if block
+      rescue Errno::ENOENT
+        raise unless ignore
       end
+
+      hash.merge! env || {}
     end
   end
 
-  # same as `overload`, but raises Errno::ENOENT if any files don't exist
-  def overload!(*filenames)
-    with(*filenames) do |f|
-      env = Environment.new(f, false)
-      instrument("dotenv.overload", env: env) { env.apply! }
+  # Save the current `ENV` to be restored later
+  def save
+    instrument(:save) do |payload|
+      @diff = payload[:diff] = Dotenv::Diff.new
     end
   end
 
-  # returns a hash of parsed key/value pairs but does not modify ENV
-  def parse(*filenames)
-    with(*filenames) do |f|
-      ignoring_nonexistent_files do
-        Environment.new(f, false)
-      end
+  # Restore `ENV` to a given state
+  #
+  # @param env [Hash] Hash of keys and values to restore, defaults to the last saved state
+  # @param safe [Boolean] Is it safe to modify `ENV`? Defaults to `true` in the main thread, otherwise raises an error.
+  def restore(env = @diff&.a, safe: Thread.current == Thread.main)
+    diff = Dotenv::Diff.new(b: env)
+    return unless diff.any?
+
+    unless safe
+      raise ThreadError, <<~EOE.tr("\n", " ")
+        Dotenv.restore is not thread safe. Use `Dotenv.modify { }` to update ENV for the duration
+        of the block in a thread safe manner, or call `Dotenv.restore(safe: true)` to ignore
+        this error.
+      EOE
     end
+    instrument(:restore, diff: diff) { ENV.replace(env) }
   end
 
-  # Internal: Helper to expand list of filenames.
+  # Update `ENV` with the given hash of keys and values
   #
-  # Returns a hash of all the loaded environment variables.
-  def with(*filenames)
-    filenames << ".env" if filenames.empty?
-
-    filenames.reduce({}) do |hash, filename|
-      hash.merge!(yield(File.expand_path(filename)) || {})
+  # @param env [Hash] Hash of keys and values to set in `ENV`
+  # @param overwrite [Boolean] Overwrite existing `ENV` values
+  def update(env = {}, overwrite: false)
+    instrument(:update) do |payload|
+      diff = payload[:diff] = Dotenv::Diff.new do
+        ENV.update(env.transform_keys(&:to_s)) do |key, old_value, new_value|
+          # This block is called when a key exists. Return the new value if overwrite is true.
+          overwrite ? new_value : old_value
+        end
+      end
+      diff.env
     end
   end
 
-  def instrument(name, payload = {}, &block)
-    if instrumenter
-      instrumenter.instrument(name, payload, &block)
-    else
-      yield
+  # Modify `ENV` for the block and restore it to its previous state afterwards.
+  #
+  # Note that the block is synchronized to prevent concurrent modifications to `ENV`,
+  # so multiple threads will be executed serially.
+  #
+  # @param env [Hash] Hash of keys and values to set in `ENV`
+  def modify(env = {}, &block)
+    SEMAPHORE.synchronize do
+      diff = Dotenv::Diff.new
+      update(env, overwrite: true)
+      block.call
+    ensure
+      restore(diff.a, safe: true)
     end
   end
 
@@ -79,8 +125,15 @@ module Dotenv
     raise MissingKeys, missing_keys
   end
 
-  def ignoring_nonexistent_files
-    yield
-  rescue Errno::ENOENT
+  private
+
+  def instrument(name, payload = {}, &block)
+    if instrumenter
+      instrumenter.instrument("#{name}.dotenv", payload, &block)
+    else
+      block&.call payload
+    end
   end
 end
+
+require "dotenv/rails" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dotenv
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Brandon Keepers
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-27 00:00:00.000000000 Z
+date: 2024-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -64,11 +64,17 @@ files:
 - README.md
 - bin/dotenv
 - lib/dotenv.rb
+- lib/dotenv/autorestore.rb
 - lib/dotenv/cli.rb
+- lib/dotenv/diff.rb
 - lib/dotenv/environment.rb
 - lib/dotenv/load.rb
+- lib/dotenv/log_subscriber.rb
 - lib/dotenv/missing_keys.rb
 - lib/dotenv/parser.rb
+- lib/dotenv/rails-now.rb
+- lib/dotenv/rails.rb
+- lib/dotenv/replay_logger.rb
 - lib/dotenv/substitutions/command.rb
 - lib/dotenv/substitutions/variable.rb
 - lib/dotenv/tasks.rb
@@ -78,7 +84,7 @@ homepage: https://github.com/bkeepers/dotenv
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -86,15 +92,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
-signing_key:
+rubygems_version: 3.5.3
+signing_key: 
 specification_version: 4
 summary: Loads environment variables from `.env`.
 test_files: []