dotenv 2.8.1 → 3.0.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ac1a9e8e04f95f111da23bf2541070f2617864fc3c55ac4e11e6b91c78d11a9b
4
- data.tar.gz: 24bf24be5be7020e72877e32d8cd2d9cf022a74b182569c77b2c81c0d482696b
3
+ metadata.gz: 3963c1ba53e439322c807f8312b8a8f9ebd0766e4d03757b41e5ce6b4bb43bc5
4
+ data.tar.gz: a7f026d236de3dbac4a1bd08a28cee474159abedb750ff5a6b3e545f1aa5cf15
5
5
  SHA512:
6
- metadata.gz: 1f8d6ae3bfd67c1b57bc4d72346d670c02570d07cee953930d6b7f9018cc053ac42624d1bc4d59dd112abe5ba711d551199ff92a2672d5434577356b0a24d0c0
7
- data.tar.gz: 38488d0f24d6f6014f87415775f94969cd56236bcb848c77b5dd4d066285ec47993006f87f1ab1afb50a033db101fe206741ec8e561de602a88717ad6fff3bdf
6
+ metadata.gz: 9bd6a081fb16b6115340a1d0751e5886a8333137061121c7adbe6c2757d8199cf3c23ae374bc9fa2dcac7faeb6c4533a30ce28f5e5eb34eac9fce1b9308cf10c
7
+ data.tar.gz: deeb7d87a65e8e7f1af595a822abd1b81ade441a46fbe1b7188e1d511ad621ceb3c45b1509580e5ceab7c957b7b49ea2d3686eef0c91fb43d914c4a58f9d975c
data/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # 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)
1
+ # dotenv [![Gem Version](https://badge.fury.io/rb/dotenv.svg)](https://badge.fury.io/rb/dotenv)
2
2
 
3
3
  Shim to load environment variables from `.env` into `ENV` in *development*.
4
4
 
@@ -8,52 +8,36 @@ But it is not always practical to set environment variables on development machi
8
8
 
9
9
  ## Installation
10
10
 
11
- ### Rails
12
-
13
- Add this line to the top of your application's Gemfile:
11
+ Add this line to the top of your application's Gemfile and run `bundle install`:
14
12
 
15
13
  ```ruby
16
- gem 'dotenv-rails', groups: [:development, :test]
14
+ gem 'dotenv', groups: [:development, :test]
17
15
  ```
18
16
 
19
- And then execute:
17
+ ## Usage
18
+
19
+ Add your application configuration to your `.env` file in the root of your project:
20
20
 
21
21
  ```shell
22
- $ bundle
22
+ S3_BUCKET=YOURS3BUCKET
23
+ SECRET_KEY=YOURSECRETKEYGOESHERE
23
24
  ```
24
25
 
25
- #### Note on load order
26
-
27
- 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`.
26
+ Whenever your application loads, these variables will be available in `ENV`:
28
27
 
29
28
  ```ruby
30
- # config/application.rb
31
- Bundler.require(*Rails.groups)
32
-
33
- # Load dotenv only in development or test environment
34
- if ['development', 'test'].include? ENV['RAILS_ENV']
35
- Dotenv::Railtie.load
36
- end
37
-
38
- HOSTNAME = ENV['HOSTNAME']
29
+ config.fog_directory = ENV['S3_BUCKET']
39
30
  ```
40
31
 
41
- 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`.
32
+ See the [API Docs](https://rubydoc.info/github/bkeepers/dotenv/main) for more.
42
33
 
43
- ```ruby
44
- gem 'dotenv-rails', require: 'dotenv/rails-now'
45
- gem 'gem-that-requires-env-variables'
46
- ```
47
-
48
- ### Sinatra or Plain ol' Ruby
34
+ ### Rails
49
35
 
50
- Install the gem:
36
+ Dotenv will automatically load when your Rails app boots. See [Customizing Rails](#customizing-rails) to change which files are loaded and when.
51
37
 
52
- ```shell
53
- $ gem install dotenv
54
- ```
38
+ ### Sinatra / Ruby
55
39
 
56
- As early as possible in your application bootstrap process, load `.env`:
40
+ Load Dotenv as early as possible in your application bootstrap process:
57
41
 
58
42
  ```ruby
59
43
  require 'dotenv/load'
@@ -70,17 +54,17 @@ require 'dotenv'
70
54
  Dotenv.load('file1.env', 'file2.env')
71
55
  ```
72
56
 
73
- Alternatively, you can use the `dotenv` executable to launch your application:
57
+ ## Autorestore in tests
74
58
 
75
- ```shell
76
- $ dotenv ./script.rb
77
- ```
59
+ 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`.
78
60
 
79
- 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.
61
+ To disable this behavior, set `config.dotenv.autorestore = false` in `config/application.rb` or `config/environments/test.rb`.
80
62
 
81
- ```
82
- $ dotenv -f ".env.local,.env" ./script.rb
83
- ```
63
+ To use this behavior outside of a Rails app, just `require "dotenv/autorestore"` in your test suite.
64
+
65
+ 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.
66
+
67
+ ### Rake
84
68
 
85
69
  To ensure `.env` is loaded in rake, load the tasks:
86
70
 
@@ -88,41 +72,119 @@ To ensure `.env` is loaded in rake, load the tasks:
88
72
  require 'dotenv/tasks'
89
73
 
90
74
  task mytask: :dotenv do
91
- # things that require .env
75
+ # things that require .env
92
76
  end
93
77
  ```
94
78
 
95
- ## Usage
79
+ ### CLI
96
80
 
97
- Add your application configuration to your `.env` file in the root of your project:
81
+ You can use the `dotenv` executable load `.env` before launching your application:
98
82
 
99
- ```shell
100
- S3_BUCKET=YOURS3BUCKET
101
- SECRET_KEY=YOURSECRETKEYGOESHERE
83
+ ```console
84
+ $ dotenv ./script.rb
102
85
  ```
103
86
 
104
- Whenever your application loads, these variables will be available in `ENV`:
87
+ 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.
105
88
 
106
- ```ruby
107
- config.fog_directory = ENV['S3_BUCKET']
89
+ ```console
90
+ $ dotenv -f ".env.local,.env" ./script.rb
108
91
  ```
109
92
 
110
- You may also add `export` in front of each line so you can `source` the file in bash:
93
+ 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.
111
94
 
112
- ```shell
113
- export S3_BUCKET=YOURS3BUCKET
114
- export SECRET_KEY=YOURSECRETKEYGOESHERE
95
+ ```console
96
+ $ dotenv -i -f ".env.local,.env" ./script.rb
115
97
  ```
116
98
 
117
- ### Multi-line values
99
+ ### Load Order
118
100
 
119
- If you need multiline variables, for example private keys, you can double quote strings and use the `\n` character for newlines:
101
+ 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`.
120
102
 
121
- ```shell
122
- PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
103
+ ```ruby
104
+ gem 'dotenv', require: 'dotenv/load'
105
+ gem 'gem-that-requires-env-variables'
106
+ ```
107
+
108
+ ### Customizing Rails
109
+
110
+ Dotenv will load the following files depending on `RAILS_ENV`, with the first file having the highest precedence, and `.env` having the lowest precedence:
111
+
112
+ <table>
113
+ <thead>
114
+ <tr>
115
+ <th>Priority</th>
116
+ <th colspan="3">Environment</th>
117
+ <th><code>.gitignore</code>it?</th>
118
+ <th>Notes</th>
119
+ </tr>
120
+ <tr>
121
+ <th></th>
122
+ <th>development</th>
123
+ <th>test</th>
124
+ <th>production</th>
125
+ <th></th>
126
+ <th></th>
127
+ </tr>
128
+ </thead>
129
+ <tr>
130
+ <td>highest</td>
131
+ <td><code>.env.development.local</code></td>
132
+ <td><code>.env.test.local</code></td>
133
+ <td><code>.env.production.local</code></td>
134
+ <td>Yes</td>
135
+ <td>Environment-specific local overrides</td>
136
+ </tr>
137
+ <tr>
138
+ <td>2nd</td>
139
+ <td><code>.env.local</code></td>
140
+ <td><strong>N/A</strong></td>
141
+ <td><code>.env.local</code></td>
142
+ <td>Yes</td>
143
+ <td>Local overrides</td>
144
+ </tr>
145
+ <tr>
146
+ <td>3rd</td>
147
+ <td><code>.env.development</code></td>
148
+ <td><code>.env.test</code></td>
149
+ <td><code>.env.production</code></td>
150
+ <td>No</td>
151
+ <td>Shared environment-specific variables</td>
152
+ </tr>
153
+ <tr>
154
+ <td>last</td>
155
+ <td><code>.env</code></td>
156
+ <td><code>.env</code></td>
157
+ <td><code>.env</code></td>
158
+ <td><a href="#should-i-commit-my-env-file">Maybe</a></td>
159
+ <td>Shared for all environments</td>
160
+ </tr>
161
+ </table>
162
+
163
+
164
+ 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`
165
+
166
+ ```ruby
167
+ # config/application.rb
168
+ Bundler.require(*Rails.groups)
169
+
170
+ # Load .env.local in test
171
+ Dotenv::Rails.files.unshift(".env.local") if ENV["RAILS_ENV"] == "test"
172
+
173
+ module YourApp
174
+ class Application < Rails::Application
175
+ # ...
176
+ end
177
+ end
123
178
  ```
124
179
 
125
- Alternatively, multi-line values with line breaks are now supported for quoted values.
180
+ Available options:
181
+
182
+ * `Dotenv::Rails.files` - list of files to be loaded, in order of precedence.
183
+ * `Dotenv::Rails.overwrite` - Overwrite exiting `ENV` variables with contents of `.env*` files
184
+
185
+ ### Multi-line values
186
+
187
+ Multi-line values with line breaks must be surrounded with double quotes.
126
188
 
127
189
  ```shell
128
190
  PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
@@ -132,7 +194,12 @@ HkVN9...
132
194
  -----END DSA PRIVATE KEY-----"
133
195
  ```
134
196
 
135
- 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.
197
+ 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`:
198
+
199
+ ```shell
200
+ DOTENV_LINEBREAK_MODE=legacy
201
+ PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
202
+ ```
136
203
 
137
204
  ### Command Substitution
138
205
 
@@ -166,6 +233,15 @@ SECRET_KEY=YOURSECRETKEYGOESHERE # comment
166
233
  SECRET_HASH="something-with-a-#-hash"
167
234
  ```
168
235
 
236
+ ### Exports
237
+
238
+ For compatability, you may also add `export` in front of each line so you can `source` the file in bash:
239
+
240
+ ```shell
241
+ export S3_BUCKET=YOURS3BUCKET
242
+ export SECRET_KEY=YOURSECRETKEYGOESHERE
243
+ ```
244
+
169
245
  ### Required Keys
170
246
 
171
247
  If a particular configuration value is required but not set, it's appropriate to raise an error.
@@ -191,39 +267,11 @@ Dotenv.parse(".env.local", ".env")
191
267
 
192
268
  This method returns a hash of the ENV var name/value pairs.
193
269
 
194
- ## Frequently Answered Questions
195
-
196
- ### Can I use dotenv in production?
197
-
198
- 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.
199
-
200
- 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`.
201
-
202
- 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>`.
203
-
204
- ### What other .env* files can I use?
205
-
206
- `dotenv-rails` will override in the following order (highest defined variable overrides lower):
207
-
208
- | Hierarchy Priority | Filename | Environment | Should I `.gitignore`it? | Notes |
209
- | ------------------ | ------------------------ | -------------------- | --------------------------------------------------- | ------------------------------------------------------------ |
210
- | 1st (highest) | `.env.development.local` | Development | Yes! | Local overrides of environment-specific settings. |
211
- | 1st | `.env.test.local` | Test | Yes! | Local overrides of environment-specific settings. |
212
- | 1st | `.env.production.local` | Production | Yes! | Local overrides of environment-specific settings. |
213
- | 2nd | `.env.local` | Wherever the file is | Definitely. | Local overrides. This file is loaded for all environments _except_ `test`. |
214
- | 3rd | `.env.development` | Development | No. | Shared environment-specific settings |
215
- | 3rd | `.env.test` | Test | No. | Shared environment-specific settings |
216
- | 3rd | `.env.production` | Production | No. | Shared environment-specific settings |
217
- | Last | `.env` | All Environments | Depends (See [below](#should-i-commit-my-env-file)) | The Original® |
218
-
219
-
220
- ### Should I commit my .env file?
221
-
222
- 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.
223
-
270
+ ### Templates
224
271
 
225
272
  You can use the `-t` or `--template` flag on the dotenv cli to create a template of your `.env` file.
226
- ```shell
273
+
274
+ ```console
227
275
  $ dotenv -t .env
228
276
  ```
229
277
  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 +292,29 @@ S3_BUCKET=S3_BUCKET
244
292
  SECRET_KEY=SECRET_KEY
245
293
  ```
246
294
 
295
+ ## Frequently Answered Questions
296
+
297
+ ### Can I use dotenv in production?
298
+
299
+ 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.
300
+
301
+ 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`.
302
+
303
+ 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>`.
304
+
305
+ ### Should I commit my .env file?
306
+
307
+ 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.
308
+
247
309
  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.
248
310
 
249
- ### Why is it not overriding existing `ENV` variables?
311
+ ### Why is it not overwriting existing `ENV` variables?
250
312
 
251
- 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`.
313
+ 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`.
252
314
 
253
- You can also use the `-o` or `--overload` flag on the dotenv cli to override existing `ENV` variables.
254
- ```shell
315
+ You can also use the `-o` or `--overwrite` flag on the dotenv cli to overwrite existing `ENV` variables.
316
+
317
+ ```console
255
318
  $ dotenv -o -f ".env.local,.env"
256
319
  ```
257
320
 
@@ -0,0 +1,29 @@
1
+ # Automatically restore `ENV` to its original state after
2
+
3
+ if defined?(RSpec.configure)
4
+ RSpec.configure do |config|
5
+ # Save ENV before the suite starts
6
+ config.before(:suite) { Dotenv.save }
7
+
8
+ # Restore ENV after each example
9
+ config.after { Dotenv.restore }
10
+ end
11
+ end
12
+
13
+ if defined?(ActiveSupport)
14
+ ActiveSupport.on_load(:active_support_test_case) do
15
+ ActiveSupport::TestCase.class_eval do
16
+ # Save ENV before each test
17
+ setup { Dotenv.save }
18
+
19
+ # Restore ENV after each test
20
+ teardown do
21
+ Dotenv.restore
22
+ rescue ThreadError => e
23
+ # Restore will fail if running tests in parallel.
24
+ warn e.message
25
+ warn "Set `config.dotenv.autorestore = false` in `config/initializers/test.rb`" if defined?(Dotenv::Rails)
26
+ end
27
+ end
28
+ end
29
+ end
data/lib/dotenv/cli.rb CHANGED
@@ -4,26 +4,32 @@ require "dotenv/template"
4
4
  require "optparse"
5
5
 
6
6
  module Dotenv
7
- # The command line interface
7
+ # The `dotenv` command line interface. Run `$ dotenv --help` to see usage.
8
8
  class CLI < OptionParser
9
- attr_reader :argv, :filenames, :overload
9
+ attr_reader :argv, :filenames, :overwrite
10
10
 
11
11
  def initialize(argv = [])
12
12
  @argv = argv.dup
13
13
  @filenames = []
14
- @overload = false
14
+ @ignore = false
15
+ @overwrite = false
15
16
 
16
- super "Usage: dotenv [options]"
17
+ super("Usage: dotenv [options]")
17
18
  separator ""
18
19
 
19
20
  on("-f FILES", Array, "List of env files to parse") do |list|
20
21
  @filenames = list
21
22
  end
22
23
 
23
- on("-o", "--overload", "override existing ENV variables") do
24
- @overload = true
24
+ on("-i", "--ignore", "ignore missing env files") do
25
+ @ignore = true
25
26
  end
26
27
 
28
+ on("-o", "--overwrite", "overwrite existing ENV variables") do
29
+ @overwrite = true
30
+ end
31
+ on("--overload") { @overwrite = true }
32
+
27
33
  on("-h", "--help", "Display help") do
28
34
  puts self
29
35
  exit
@@ -43,11 +49,7 @@ module Dotenv
43
49
  end
44
50
 
45
51
  def run
46
- if @overload
47
- Dotenv.overload!(*@filenames)
48
- else
49
- Dotenv.load!(*@filenames)
50
- end
52
+ Dotenv.load(*@filenames, overwrite: @overwrite, ignore: @ignore)
51
53
  rescue Errno::ENOENT => e
52
54
  abort e.message
53
55
  else
@@ -0,0 +1,56 @@
1
+ module Dotenv
2
+ # A diff between multiple states of ENV.
3
+ class Diff
4
+ # The initial state
5
+ attr_reader :a
6
+
7
+ # The final or current state
8
+ attr_reader :b
9
+
10
+ # Create a new diff. If given a block, the state of ENV after the block will be preserved as
11
+ # the final state for comparison. Otherwise, the current ENV will be the final state.
12
+ #
13
+ # @param a [Hash] the initial state, defaults to a snapshot of current ENV
14
+ # @param b [Hash] the final state, defaults to the current ENV
15
+ # @yield [diff] a block to execute before recording the final state
16
+ def initialize(a: snapshot, b: ENV, &block)
17
+ @a, @b = a, b
18
+ block&.call self
19
+ ensure
20
+ @b = snapshot if block
21
+ end
22
+
23
+ # Return a Hash of keys added with their new values
24
+ def added
25
+ b.slice(*(b.keys - a.keys))
26
+ end
27
+
28
+ # Returns a Hash of keys removed with their previous values
29
+ def removed
30
+ a.slice(*(a.keys - b.keys))
31
+ end
32
+
33
+ # Returns of Hash of keys changed with an array of their previous and new values
34
+ def changed
35
+ (b.slice(*a.keys).to_a - a.to_a).map do |(k, v)|
36
+ [k, [a[k], v]]
37
+ end.to_h
38
+ end
39
+
40
+ # Returns a Hash of all added, changed, and removed keys and their new values
41
+ def env
42
+ b.slice(*(added.keys + changed.keys)).merge(removed.transform_values { |v| nil })
43
+ end
44
+
45
+ # Returns true if any keys were added, removed, or changed
46
+ def any?
47
+ [added, removed, changed].any?(&:any?)
48
+ end
49
+
50
+ private
51
+
52
+ def snapshot
53
+ ENV.to_h.freeze
54
+ end
55
+ end
56
+ end
@@ -1,28 +1,25 @@
1
1
  module Dotenv
2
- # This class inherits from Hash and represents the environment into which
3
- # Dotenv will load key value pairs from a file.
2
+ # A `.env` file that will be read and parsed into a Hash
4
3
  class Environment < Hash
5
- attr_reader :filename
4
+ attr_reader :filename, :overwrite
6
5
 
7
- def initialize(filename, is_load = false)
6
+ # Create a new Environment
7
+ #
8
+ # @param filename [String] the path to the file to read
9
+ # @param overwrite [Boolean] whether the parser should assume existing values will be overwritten
10
+ def initialize(filename, overwrite: false)
11
+ super()
8
12
  @filename = filename
9
- load(is_load)
13
+ @overwrite = overwrite
14
+ load
10
15
  end
11
16
 
12
- def load(is_load = false)
13
- update Parser.call(read, is_load)
17
+ def load
18
+ update Parser.call(read, overwrite: overwrite)
14
19
  end
15
20
 
16
21
  def read
17
22
  File.open(@filename, "rb:bom|utf-8", &:read)
18
23
  end
19
-
20
- def apply
21
- each { |k, v| ENV[k] ||= v }
22
- end
23
-
24
- def apply!
25
- each { |k, v| ENV[k] = v }
26
- end
27
24
  end
28
25
  end
data/lib/dotenv/load.rb CHANGED
@@ -1,2 +1,3 @@
1
1
  require "dotenv"
2
- Dotenv.load
2
+
3
+ defined?(Dotenv::Rails) ? Dotenv::Rails.load : Dotenv.load
@@ -0,0 +1,61 @@
1
+ require "active_support/log_subscriber"
2
+
3
+ module Dotenv
4
+ # Logs instrumented events
5
+ #
6
+ # Usage:
7
+ # require "active_support/notifications"
8
+ # require "dotenv/log_subscriber"
9
+ # Dotenv.instrumenter = ActiveSupport::Notifications
10
+ #
11
+ class LogSubscriber < ActiveSupport::LogSubscriber
12
+ attach_to :dotenv
13
+
14
+ def logger
15
+ Dotenv::Rails.logger
16
+ end
17
+
18
+ def load(event)
19
+ env = event.payload[:env]
20
+
21
+ info "Loaded #{color_filename(env.filename)}"
22
+ end
23
+
24
+ def update(event)
25
+ diff = event.payload[:diff]
26
+ changed = diff.env.keys.map { |key| color_var(key) }
27
+ debug "Set #{changed.to_sentence}" if diff.any?
28
+ end
29
+
30
+ def save(event)
31
+ info "Saved a snapshot of #{color_env_constant}"
32
+ end
33
+
34
+ def restore(event)
35
+ diff = event.payload[:diff]
36
+
37
+ removed = diff.removed.keys.map { |key| color(key, :RED) }
38
+ restored = (diff.changed.keys + diff.added.keys).map { |key| color_var(key) }
39
+
40
+ if removed.any? || restored.any?
41
+ info "Restored snapshot of #{color_env_constant}"
42
+ debug "Unset #{removed.to_sentence}" if removed.any?
43
+ debug "Restored #{restored.to_sentence}" if restored.any?
44
+ end
45
+ end
46
+
47
+ private
48
+
49
+ def color_filename(filename)
50
+ color(Pathname.new(filename).relative_path_from(Dotenv::Rails.root.to_s).to_s, :YELLOW)
51
+ end
52
+
53
+ def color_var(name)
54
+ color(name, :CYAN)
55
+ end
56
+
57
+ def color_env_constant
58
+ color("ENV", :GREEN)
59
+ end
60
+ end
61
+ end
@@ -3,7 +3,7 @@ module Dotenv
3
3
 
4
4
  class MissingKeys < Error # :nodoc:
5
5
  def initialize(keys)
6
- key_word = "key#{keys.size > 1 ? "s" : ""}"
6
+ key_word = "key#{(keys.size > 1) ? "s" : ""}"
7
7
  super("Missing required configuration #{key_word}: #{keys.inspect}")
8
8
  end
9
9
  end
data/lib/dotenv/parser.rb CHANGED
@@ -2,11 +2,11 @@ require "dotenv/substitutions/variable"
2
2
  require "dotenv/substitutions/command" if RUBY_VERSION > "1.8.7"
3
3
 
4
4
  module Dotenv
5
+ # Error raised when encountering a syntax error while parsing a .env file.
5
6
  class FormatError < SyntaxError; end
6
7
 
7
- # This class enables parsing of a string for key value pairs to be returned
8
- # and stored in the Environment. It allows for variable substitutions and
9
- # exporting of variables.
8
+ # Parses the `.env` file format into key/value pairs.
9
+ # It allows for variable substitutions, command substitutions, and exporting of variables.
10
10
  class Parser
11
11
  @substitutions =
12
12
  [Dotenv::Substitutions::Variable, Dotenv::Substitutions::Command]
@@ -32,15 +32,15 @@ module Dotenv
32
32
  class << self
33
33
  attr_reader :substitutions
34
34
 
35
- def call(string, is_load = false)
36
- new(string, is_load).call
35
+ def call(...)
36
+ new(...).call
37
37
  end
38
38
  end
39
39
 
40
- def initialize(string, is_load = false)
40
+ def initialize(string, overwrite: false)
41
41
  @string = string
42
42
  @hash = {}
43
- @is_load = is_load
43
+ @overwrite = overwrite
44
44
  end
45
45
 
46
46
  def call
@@ -80,11 +80,15 @@ module Dotenv
80
80
  end
81
81
 
82
82
  def expand_newlines(value)
83
- value.gsub('\n', "\n").gsub('\r', "\r")
83
+ if (@hash["DOTENV_LINEBREAK_MODE"] || ENV["DOTENV_LINEBREAK_MODE"]) == "legacy"
84
+ value.gsub('\n', "\n").gsub('\r', "\r")
85
+ else
86
+ value.gsub('\n', "\\\\\\n").gsub('\r', "\\\\\\r")
87
+ end
84
88
  end
85
89
 
86
90
  def variable_not_set?(line)
87
- !line.split[1..-1].all? { |var| @hash.member?(var) }
91
+ !line.split[1..].all? { |var| @hash.member?(var) }
88
92
  end
89
93
 
90
94
  def unescape_value(value, maybe_quote)
@@ -100,7 +104,7 @@ module Dotenv
100
104
  def perform_substitutions(value, maybe_quote)
101
105
  if maybe_quote != "'"
102
106
  self.class.substitutions.each do |proc|
103
- value = proc.call(value, @hash, @is_load)
107
+ value = proc.call(value, @hash, overwrite: @overwrite)
104
108
  end
105
109
  end
106
110
  value
@@ -0,0 +1,10 @@
1
+ # If you use gems that require environment variables to be set before they are
2
+ # loaded, then list `dotenv` in the `Gemfile` before those other gems and
3
+ # require `dotenv/load`.
4
+ #
5
+ # gem "dotenv", require: "dotenv/load"
6
+ # gem "gem-that-requires-env-variables"
7
+ #
8
+
9
+ require "dotenv/load"
10
+ warn '[DEPRECATION] `require "dotenv/rails-now"` is deprecated. Use `require "dotenv/load"` instead.', caller(1..1).first
@@ -0,0 +1,104 @@
1
+ require "dotenv"
2
+ require "dotenv/replay_logger"
3
+ require "dotenv/log_subscriber"
4
+
5
+ Dotenv.instrumenter = ActiveSupport::Notifications
6
+
7
+ # Watch all loaded env files with Spring
8
+ begin
9
+ require "spring/commands"
10
+ ActiveSupport::Notifications.subscribe("load.dotenv") do |*args|
11
+ event = ActiveSupport::Notifications::Event.new(*args)
12
+ Spring.watch event.payload[:env].filename if Rails.application
13
+ end
14
+ rescue LoadError, ArgumentError
15
+ # Spring is not available
16
+ end
17
+
18
+ module Dotenv
19
+ # Rails integration for using Dotenv to load ENV variables from a file
20
+ class Rails < ::Rails::Railtie
21
+ delegate :files, :files=, :overwrite, :overwrite=, :autorestore, :autorestore=, :logger, :logger=, to: "config.dotenv"
22
+
23
+ def initialize
24
+ super()
25
+ config.dotenv = ActiveSupport::OrderedOptions.new.update(
26
+ # Rails.logger is not available yet, so we'll save log messages and replay them when it is
27
+ logger: Dotenv::ReplayLogger.new,
28
+ overwrite: false,
29
+ files: [
30
+ root.join(".env.#{env}.local"),
31
+ (root.join(".env.local") unless env.test?),
32
+ root.join(".env.#{env}"),
33
+ root.join(".env")
34
+ ].compact,
35
+ autorestore: env.test?
36
+ )
37
+ end
38
+
39
+ # Public: Load dotenv
40
+ #
41
+ # This will get called during the `before_configuration` callback, but you
42
+ # can manually call `Dotenv::Rails.load` if you needed it sooner.
43
+ def load
44
+ Dotenv.load(*files, overwrite: overwrite)
45
+ end
46
+
47
+ def overload
48
+ deprecator.warn("Dotenv::Rails.overload is deprecated. Set `Dotenv::Rails.overwrite = true` and call Dotenv::Rails.load instead.")
49
+ Dotenv.load(*files, overwrite: true)
50
+ end
51
+
52
+ # Internal: `Rails.root` is nil in Rails 4.1 before the application is
53
+ # initialized, so this falls back to the `RAILS_ROOT` environment variable,
54
+ # or the current working directory.
55
+ def root
56
+ ::Rails.root || Pathname.new(ENV["RAILS_ROOT"] || Dir.pwd)
57
+ end
58
+
59
+ # The current environment that the app is running in.
60
+ #
61
+ # When running `rake`, the Rails application is initialized in development, so we have to
62
+ # check which rake tasks are being run to determine the environment.
63
+ #
64
+ # See https://github.com/bkeepers/dotenv/issues/219
65
+ def env
66
+ @env ||= if defined?(Rake.application) && Rake.application.top_level_tasks.grep(TEST_RAKE_TASKS).any?
67
+ env = Rake.application.options.show_tasks ? "development" : "test"
68
+ ActiveSupport::EnvironmentInquirer.new(env)
69
+ else
70
+ ::Rails.env
71
+ end
72
+ end
73
+ TEST_RAKE_TASKS = /^(default$|test(:|$)|parallel:spec|spec(:|$))/
74
+
75
+ def deprecator # :nodoc:
76
+ @deprecator ||= ActiveSupport::Deprecation.new
77
+ end
78
+
79
+ # Rails uses `#method_missing` to delegate all class methods to the
80
+ # instance, which means `Kernel#load` gets called here. We don't want that.
81
+ def self.load
82
+ instance.load
83
+ end
84
+
85
+ initializer "dotenv", after: :initialize_logger do |app|
86
+ # Set up a new logger once Rails has initialized the logger and replay logs
87
+ new_logger = ActiveSupport::TaggedLogging.new(::Rails.logger).tagged("dotenv")
88
+ logger.replay new_logger if logger.respond_to?(:replay)
89
+ self.logger = new_logger
90
+ end
91
+
92
+ initializer "dotenv.deprecator" do |app|
93
+ app.deprecators[:dotenv] = deprecator if app.respond_to?(:deprecators)
94
+ end
95
+
96
+ initializer "dotenv.autorestore" do |app|
97
+ require "dotenv/autorestore" if autorestore
98
+ end
99
+
100
+ config.before_configuration { load }
101
+ end
102
+
103
+ Railtie = ActiveSupport::Deprecation::DeprecatedConstantProxy.new("Dotenv::Railtie", "Dotenv::Rails", Dotenv::Rails.deprecator)
104
+ end
@@ -0,0 +1,20 @@
1
+ module Dotenv
2
+ # A logger that can be used before the apps real logger is initialized.
3
+ class ReplayLogger
4
+ def initialize
5
+ @logs = []
6
+ end
7
+
8
+ def method_missing(name, *args, &block)
9
+ @logs.push([name, args, block])
10
+ end
11
+
12
+ def respond_to_missing?(name, include_private = false)
13
+ (include_private ? Logger.instance_methods : Logger.public_instance_methods).include?(name) || super
14
+ end
15
+
16
+ def replay(logger)
17
+ @logs.each { |name, args, block| logger.send(name, *args, &block) }
18
+ end
19
+ end
20
+ end
@@ -20,7 +20,7 @@ module Dotenv
20
20
  )
21
21
  /x
22
22
 
23
- def call(value, _env, _is_load)
23
+ def call(value, _env, overwrite: false)
24
24
  # Process interpolated shell commands
25
25
  value.gsub(INTERPOLATED_SHELL_COMMAND) do |*|
26
26
  # Eliminate opening and closing parentheses
@@ -28,7 +28,7 @@ module Dotenv
28
28
 
29
29
  if $LAST_MATCH_INFO[:backslash]
30
30
  # Command is escaped, don't replace it.
31
- $LAST_MATCH_INFO[0][1..-1]
31
+ $LAST_MATCH_INFO[0][1..]
32
32
  else
33
33
  # Execute the command and return the value
34
34
  `#{command}`.chomp
@@ -18,8 +18,8 @@ module Dotenv
18
18
  \}? # closing brace
19
19
  /xi
20
20
 
21
- def call(value, env, is_load)
22
- combined_env = is_load ? env.merge(ENV) : ENV.to_h.merge(env)
21
+ def call(value, env, overwrite: false)
22
+ combined_env = overwrite ? ENV.to_h.merge(env) : env.merge(ENV)
23
23
  value.gsub(VARIABLE) do |variable|
24
24
  match = $LAST_MATCH_INFO
25
25
  substitute(match, variable, combined_env)
@@ -30,7 +30,7 @@ module Dotenv
30
30
 
31
31
  def substitute(match, variable, env)
32
32
  if match[1] == "\\"
33
- variable[1..-1]
33
+ variable[1..]
34
34
  elsif match[3]
35
35
  env.fetch(match[3], "")
36
36
  else
@@ -20,7 +20,7 @@ module Dotenv
20
20
  var, value = line.split("=")
21
21
  template = var.gsub(EXPORT_COMMAND, "")
22
22
  is_a_comment = var.strip[0].eql?("#")
23
- value.nil? || is_a_comment ? line : "#{var}=#{template}"
23
+ (value.nil? || is_a_comment) ? line : "#{var}=#{template}"
24
24
  end
25
25
  end
26
26
  end
@@ -1,3 +1,3 @@
1
1
  module Dotenv
2
- VERSION = "2.8.1".freeze
2
+ VERSION = "3.0.0".freeze
3
3
  end
data/lib/dotenv.rb CHANGED
@@ -1,75 +1,121 @@
1
1
  require "dotenv/parser"
2
2
  require "dotenv/environment"
3
3
  require "dotenv/missing_keys"
4
+ require "dotenv/diff"
4
5
 
5
- # The top level Dotenv module. The entrypoint for the application logic.
6
+ # Shim to load environment variables from `.env files into `ENV`.
6
7
  module Dotenv
7
- class << self
8
- attr_accessor :instrumenter
9
- end
8
+ extend self
9
+
10
+ # An internal monitor to synchronize access to ENV in multi-threaded environments.
11
+ SEMAPHORE = Monitor.new
12
+ private_constant :SEMAPHORE
10
13
 
11
- module_function
14
+ attr_accessor :instrumenter
12
15
 
13
- def load(*filenames)
14
- with(*filenames) do |f|
15
- ignoring_nonexistent_files do
16
- env = Environment.new(f, true)
17
- instrument("dotenv.load", env: env) { env.apply }
16
+ # Loads environment variables from one or more `.env` files. See `#parse` for more details.
17
+ def load(*filenames, overwrite: false, ignore: true)
18
+ parse(*filenames, overwrite: overwrite, ignore: ignore) do |env|
19
+ instrument(:load, env: env) do |payload|
20
+ update(env, overwrite: overwrite)
18
21
  end
19
22
  end
20
23
  end
21
24
 
22
- # same as `load`, but raises Errno::ENOENT if any files don't exist
25
+ # Same as `#load`, but raises Errno::ENOENT if any files don't exist
23
26
  def load!(*filenames)
24
- with(*filenames) do |f|
25
- env = Environment.new(f, true)
26
- instrument("dotenv.load", env: env) { env.apply }
27
- end
27
+ load(*filenames, ignore: false)
28
+ end
29
+
30
+ # same as `#load`, but will overwrite existing values in `ENV`
31
+ def overwrite(*filenames)
32
+ load(*filenames, overwrite: true)
33
+ end
34
+ alias_method :overload, :overwrite
35
+
36
+ # same as `#overwrite`, but raises Errno::ENOENT if any files don't exist
37
+ def overwrite!(*filenames)
38
+ load(*filenames, overwrite: true, ignore: false)
28
39
  end
40
+ alias_method :overload!, :overwrite!
29
41
 
30
- # same as `load`, but will override existing values in `ENV`
31
- def overload(*filenames)
32
- with(*filenames) do |f|
33
- ignoring_nonexistent_files do
34
- env = Environment.new(f, false)
35
- instrument("dotenv.overload", env: env) { env.apply! }
42
+ # Parses the given files, yielding for each file if a block is given.
43
+ #
44
+ # @param filenames [String, Array<String>] Files to parse
45
+ # @param overwrite [Boolean] Overwrite existing `ENV` values
46
+ # @param ignore [Boolean] Ignore non-existent files
47
+ # @param block [Proc] Block to yield for each parsed `Dotenv::Environment`
48
+ # @return [Hash] parsed key/value pairs
49
+ def parse(*filenames, overwrite: false, ignore: true, &block)
50
+ filenames << ".env" if filenames.empty?
51
+ filenames = filenames.reverse if overwrite
52
+
53
+ filenames.reduce({}) do |hash, filename|
54
+ begin
55
+ env = Environment.new(File.expand_path(filename), overwrite: overwrite)
56
+ env = block.call(env) if block
57
+ rescue Errno::ENOENT
58
+ raise unless ignore
36
59
  end
60
+
61
+ hash.merge! env || {}
37
62
  end
38
63
  end
39
64
 
40
- # same as `overload`, but raises Errno::ENOENT if any files don't exist
41
- def overload!(*filenames)
42
- with(*filenames) do |f|
43
- env = Environment.new(f, false)
44
- instrument("dotenv.overload", env: env) { env.apply! }
65
+ # Save the current `ENV` to be restored later
66
+ def save
67
+ instrument(:save) do |payload|
68
+ @diff = payload[:diff] = Dotenv::Diff.new
45
69
  end
46
70
  end
47
71
 
48
- # returns a hash of parsed key/value pairs but does not modify ENV
49
- def parse(*filenames)
50
- with(*filenames) do |f|
51
- ignoring_nonexistent_files do
52
- Environment.new(f, false)
53
- end
72
+ # Restore `ENV` to a given state
73
+ #
74
+ # @param env [Hash] Hash of keys and values to restore, defaults to the last saved state
75
+ # @param safe [Boolean] Is it safe to modify `ENV`? Defaults to `true` in the main thread, otherwise raises an error.
76
+ def restore(env = @diff&.a, safe: Thread.current == Thread.main)
77
+ diff = Dotenv::Diff.new(b: env)
78
+ return unless diff.any?
79
+
80
+ unless safe
81
+ raise ThreadError, <<~EOE.tr("\n", " ")
82
+ Dotenv.restore is not thread safe. Use `Dotenv.modify { }` to update ENV for the duration
83
+ of the block in a thread safe manner, or call `Dotenv.restore(safe: true)` to ignore
84
+ this error.
85
+ EOE
54
86
  end
87
+ instrument(:restore, diff: diff) { ENV.replace(env) }
55
88
  end
56
89
 
57
- # Internal: Helper to expand list of filenames.
90
+ # Update `ENV` with the given hash of keys and values
58
91
  #
59
- # Returns a hash of all the loaded environment variables.
60
- def with(*filenames)
61
- filenames << ".env" if filenames.empty?
62
-
63
- filenames.reduce({}) do |hash, filename|
64
- hash.merge!(yield(File.expand_path(filename)) || {})
92
+ # @param env [Hash] Hash of keys and values to set in `ENV`
93
+ # @param overwrite [Boolean] Overwrite existing `ENV` values
94
+ def update(env = {}, overwrite: false)
95
+ instrument(:update) do |payload|
96
+ diff = payload[:diff] = Dotenv::Diff.new do
97
+ ENV.update(env.transform_keys(&:to_s)) do |key, old_value, new_value|
98
+ # This block is called when a key exists. Return the new value if overwrite is true.
99
+ overwrite ? new_value : old_value
100
+ end
101
+ end
102
+ diff.env
65
103
  end
66
104
  end
67
105
 
68
- def instrument(name, payload = {}, &block)
69
- if instrumenter
70
- instrumenter.instrument(name, payload, &block)
71
- else
72
- yield
106
+ # Modify `ENV` for the block and restore it to its previous state afterwards.
107
+ #
108
+ # Note that the block is synchronized to prevent concurrent modifications to `ENV`,
109
+ # so multiple threads will be executed serially.
110
+ #
111
+ # @param env [Hash] Hash of keys and values to set in `ENV`
112
+ def modify(env = {}, &block)
113
+ SEMAPHORE.synchronize do
114
+ diff = Dotenv::Diff.new
115
+ update(env, overwrite: true)
116
+ block.call
117
+ ensure
118
+ restore(diff.a, safe: true)
73
119
  end
74
120
  end
75
121
 
@@ -79,8 +125,15 @@ module Dotenv
79
125
  raise MissingKeys, missing_keys
80
126
  end
81
127
 
82
- def ignoring_nonexistent_files
83
- yield
84
- rescue Errno::ENOENT
128
+ private
129
+
130
+ def instrument(name, payload = {}, &block)
131
+ if instrumenter
132
+ instrumenter.instrument("#{name}.dotenv", payload, &block)
133
+ else
134
+ block&.call payload
135
+ end
85
136
  end
86
137
  end
138
+
139
+ require "dotenv/rails" if defined?(Rails::Railtie)
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: dotenv
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.8.1
4
+ version: 3.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Brandon Keepers
8
- autorequire:
8
+ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2022-07-27 00:00:00.000000000 Z
11
+ date: 2024-02-12 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rake
@@ -64,11 +64,17 @@ files:
64
64
  - README.md
65
65
  - bin/dotenv
66
66
  - lib/dotenv.rb
67
+ - lib/dotenv/autorestore.rb
67
68
  - lib/dotenv/cli.rb
69
+ - lib/dotenv/diff.rb
68
70
  - lib/dotenv/environment.rb
69
71
  - lib/dotenv/load.rb
72
+ - lib/dotenv/log_subscriber.rb
70
73
  - lib/dotenv/missing_keys.rb
71
74
  - lib/dotenv/parser.rb
75
+ - lib/dotenv/rails-now.rb
76
+ - lib/dotenv/rails.rb
77
+ - lib/dotenv/replay_logger.rb
72
78
  - lib/dotenv/substitutions/command.rb
73
79
  - lib/dotenv/substitutions/variable.rb
74
80
  - lib/dotenv/tasks.rb
@@ -78,7 +84,7 @@ homepage: https://github.com/bkeepers/dotenv
78
84
  licenses:
79
85
  - MIT
80
86
  metadata: {}
81
- post_install_message:
87
+ post_install_message:
82
88
  rdoc_options: []
83
89
  require_paths:
84
90
  - lib
@@ -86,15 +92,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
86
92
  requirements:
87
93
  - - ">="
88
94
  - !ruby/object:Gem::Version
89
- version: '0'
95
+ version: '3.0'
90
96
  required_rubygems_version: !ruby/object:Gem::Requirement
91
97
  requirements:
92
98
  - - ">="
93
99
  - !ruby/object:Gem::Version
94
100
  version: '0'
95
101
  requirements: []
96
- rubygems_version: 3.2.32
97
- signing_key:
102
+ rubygems_version: 3.5.3
103
+ signing_key:
98
104
  specification_version: 4
99
105
  summary: Loads environment variables from `.env`.
100
106
  test_files: []