dotenv-rails 2.8.0 → 3.0.0.beta

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: 5a8ba4039c1bdd46569ac907b8fb2f3a76b1c6d00a451a55aadf931c15f69d90
4
- data.tar.gz: 619354ce54dfb1689c7ccae402cfb3230df4fd0284783859906fae4c994488c8
3
+ metadata.gz: 84017f2c53d971b597af22f799cab58020ad0b76336fe82469dcd702e36173d9
4
+ data.tar.gz: c7511d8dce62e068cd518c857f913df66bccbd13dde70b9ff73279f4637eb1d3
5
5
  SHA512:
6
- metadata.gz: 4084c7af6d0e380f3209b302d9d116acb2f7eda31879c1d5c34b9705e7667239993fab2b5d69286a7bd268813c8f0d394cfd2fca92837b4fe38f5a2adbf59535
7
- data.tar.gz: 7cb29fd7b1572845347b8d26dd4b45141595c404d5b9b019228a712c6fd640e34b62a9fe49d664b9381ee34339d8c2ab1bbc7d6da989a7b4f526e9cc1fcad3d3
6
+ metadata.gz: ac03c442d9b507484044c2674e2705df3d9ce852a1cc22b1c8d34ce6042cdd8bd0221163847767bc5f3de9b97db59cfceb67e2b09c7c123d090ea921603aa707
7
+ data.tar.gz: cee6b5d3693c43e9a54ad6ab06e493174ffc68f6ef7bc892b067f0b46066a369bb563af675b028fb59cd4908e4d9c192c43ac9eafdd962c80525db344398c4b5
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` to its original state before 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,71 @@ 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'
123
106
  ```
124
107
 
125
- Alternatively, multi-line values with line breaks are now supported for quoted values.
108
+ ### Customizing Rails
109
+
110
+ Dotenv will load the following files depending on `RAILS_ENV`, with the last file listed having the highest precedence:
111
+
112
+ * **development**: `.env`, `.env.development`, `.env.local`, `.env.development.local`
113
+ * **test**: `.env`, `.env.test`, `.env.test.local` - Note that it will **not** load `.env.local`.
114
+ * **development**: `.env`, `.env.production`, `.env.local`, `.env.production.local`
115
+
116
+ 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`
117
+
118
+ ```ruby
119
+ # config/application.rb
120
+ Bundler.require(*Rails.groups)
121
+
122
+ # Load .env.local in test
123
+ Dotenv::Rails.files.unshift(".env.local") if ENV["RAILS_ENV"] == "test"
124
+
125
+ module YourApp
126
+ class Application < Rails::Application
127
+ # ...
128
+ end
129
+ end
130
+ ```
131
+
132
+ Available options:
133
+
134
+ * `Dotenv::Rails.files` - list of files to be loaded, in order of precedence.
135
+ * `Dotenv::Rails.overwrite` - Overwrite exiting `ENV` variables with contents of `.env*` files
136
+
137
+ ### Multi-line values
138
+
139
+ Multi-line values with line breaks must be surrounded with double quotes.
126
140
 
127
141
  ```shell
128
142
  PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
@@ -132,7 +146,12 @@ HkVN9...
132
146
  -----END DSA PRIVATE KEY-----"
133
147
  ```
134
148
 
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.
149
+ 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`:
150
+
151
+ ```shell
152
+ DOTENV_LINEBREAK_MODE=legacy
153
+ PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
154
+ ```
136
155
 
137
156
  ### Command Substitution
138
157
 
@@ -166,6 +185,15 @@ SECRET_KEY=YOURSECRETKEYGOESHERE # comment
166
185
  SECRET_HASH="something-with-a-#-hash"
167
186
  ```
168
187
 
188
+ ### Exports
189
+
190
+ For compatability, you may also add `export` in front of each line so you can `source` the file in bash:
191
+
192
+ ```shell
193
+ export S3_BUCKET=YOURS3BUCKET
194
+ export SECRET_KEY=YOURSECRETKEYGOESHERE
195
+ ```
196
+
169
197
  ### Required Keys
170
198
 
171
199
  If a particular configuration value is required but not set, it's appropriate to raise an error.
@@ -191,39 +219,11 @@ Dotenv.parse(".env.local", ".env")
191
219
 
192
220
  This method returns a hash of the ENV var name/value pairs.
193
221
 
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
-
222
+ ### Templates
224
223
 
225
224
  You can use the `-t` or `--template` flag on the dotenv cli to create a template of your `.env` file.
226
- ```shell
225
+
226
+ ```console
227
227
  $ dotenv -t .env
228
228
  ```
229
229
  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 +244,29 @@ S3_BUCKET=S3_BUCKET
244
244
  SECRET_KEY=SECRET_KEY
245
245
  ```
246
246
 
247
+ ## Frequently Answered Questions
248
+
249
+ ### Can I use dotenv in production?
250
+
251
+ 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.
252
+
253
+ 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`.
254
+
255
+ 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>`.
256
+
257
+ ### Should I commit my .env file?
258
+
259
+ 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.
260
+
247
261
  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
262
 
249
- ### Why is it not overriding existing `ENV` variables?
263
+ ### Why is it not overwriting existing `ENV` variables?
250
264
 
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`.
265
+ 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
266
 
253
- You can also use the `-o` or `--overload` flag on the dotenv cli to override existing `ENV` variables.
254
- ```shell
267
+ You can also use the `-o` or `--overwrite` flag on the dotenv cli to overwrite existing `ENV` variables.
268
+
269
+ ```console
255
270
  $ dotenv -o -f ".env.local,.env"
256
271
  ```
257
272
 
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: dotenv-rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.8.0
4
+ version: 3.0.0.beta
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-26 00:00:00.000000000 Z
11
+ date: 2024-01-25 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: dotenv
@@ -16,28 +16,28 @@ dependencies:
16
16
  requirements:
17
17
  - - '='
18
18
  - !ruby/object:Gem::Version
19
- version: 2.8.0
19
+ version: 3.0.0.beta
20
20
  type: :runtime
21
21
  prerelease: false
22
22
  version_requirements: !ruby/object:Gem::Requirement
23
23
  requirements:
24
24
  - - '='
25
25
  - !ruby/object:Gem::Version
26
- version: 2.8.0
26
+ version: 3.0.0.beta
27
27
  - !ruby/object:Gem::Dependency
28
28
  name: railties
29
29
  requirement: !ruby/object:Gem::Requirement
30
30
  requirements:
31
31
  - - ">="
32
32
  - !ruby/object:Gem::Version
33
- version: '3.2'
33
+ version: '6.1'
34
34
  type: :runtime
35
35
  prerelease: false
36
36
  version_requirements: !ruby/object:Gem::Requirement
37
37
  requirements:
38
38
  - - ">="
39
39
  - !ruby/object:Gem::Version
40
- version: '3.2'
40
+ version: '6.1'
41
41
  - !ruby/object:Gem::Dependency
42
42
  name: spring
43
43
  requirement: !ruby/object:Gem::Requirement
@@ -62,13 +62,11 @@ files:
62
62
  - LICENSE
63
63
  - README.md
64
64
  - lib/dotenv-rails.rb
65
- - lib/dotenv/rails-now.rb
66
- - lib/dotenv/rails.rb
67
65
  homepage: https://github.com/bkeepers/dotenv
68
66
  licenses:
69
67
  - MIT
70
68
  metadata: {}
71
- post_install_message:
69
+ post_install_message:
72
70
  rdoc_options: []
73
71
  require_paths:
74
72
  - lib
@@ -83,8 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
83
81
  - !ruby/object:Gem::Version
84
82
  version: '0'
85
83
  requirements: []
86
- rubygems_version: 3.2.32
87
- signing_key:
84
+ rubygems_version: 3.5.3
85
+ signing_key:
88
86
  specification_version: 4
89
87
  summary: Autoload dotenv in Rails.
90
88
  test_files: []
@@ -1,10 +0,0 @@
1
- # If you use gems that require environment variables to be set before they are
2
- # loaded, then list `dotenv-rails` in the `Gemfile` before those other gems and
3
- # require `dotenv/rails-now`.
4
- #
5
- # gem "dotenv-rails", require: "dotenv/rails-now"
6
- # gem "gem-that-requires-env-variables"
7
- #
8
-
9
- require "dotenv/rails"
10
- Dotenv::Railtie.load
data/lib/dotenv/rails.rb DELETED
@@ -1,77 +0,0 @@
1
- require "dotenv"
2
-
3
- # Fix for rake tasks loading in development
4
- #
5
- # Dotenv loads environment variables when the Rails application is initialized.
6
- # When running `rake`, the Rails application is initialized in development.
7
- # Rails includes some hacks to set `RAILS_ENV=test` when running `rake test`,
8
- # but rspec does not include the same hacks.
9
- #
10
- # See https://github.com/bkeepers/dotenv/issues/219
11
- if defined?(Rake.application)
12
- task_regular_expression = /^(default$|parallel:spec|spec(:|$))/
13
- if Rake.application.top_level_tasks.grep(task_regular_expression).any?
14
- environment = Rake.application.options.show_tasks ? "development" : "test"
15
- Rails.env = ENV["RAILS_ENV"] ||= environment
16
- end
17
- end
18
-
19
- Dotenv.instrumenter = ActiveSupport::Notifications
20
-
21
- # Watch all loaded env files with Spring
22
- begin
23
- require "spring/commands"
24
- ActiveSupport::Notifications.subscribe(/^dotenv/) do |*args|
25
- event = ActiveSupport::Notifications::Event.new(*args)
26
- Spring.watch event.payload[:env].filename if Rails.application
27
- end
28
- rescue LoadError, ArgumentError
29
- # Spring is not available
30
- end
31
-
32
- module Dotenv
33
- # Dotenv Railtie for using Dotenv to load environment from a file into
34
- # Rails applications
35
- class Railtie < Rails::Railtie
36
- # Public: Load dotenv
37
- #
38
- # This will get called during the `before_configuration` callback, but you
39
- # can manually call `Dotenv::Railtie.load` if you needed it sooner.
40
- def load
41
- Dotenv.load(*dotenv_files)
42
- end
43
-
44
- # Public: Reload dotenv
45
- #
46
- # Same as `load`, but will override existing values in `ENV`
47
- def overload
48
- Dotenv.overload(*dotenv_files)
49
- end
50
-
51
- # Internal: `Rails.root` is nil in Rails 4.1 before the application is
52
- # initialized, so this falls back to the `RAILS_ROOT` environment variable,
53
- # or the current working directory.
54
- def root
55
- Rails.root || Pathname.new(ENV["RAILS_ROOT"] || Dir.pwd)
56
- end
57
-
58
- # Rails uses `#method_missing` to delegate all class methods to the
59
- # instance, which means `Kernel#load` gets called here. We don't want that.
60
- def self.load
61
- instance.load
62
- end
63
-
64
- private
65
-
66
- def dotenv_files
67
- [
68
- root.join(".env.#{Rails.env}.local"),
69
- (root.join(".env.local") unless Rails.env.test?),
70
- root.join(".env.#{Rails.env}"),
71
- root.join(".env")
72
- ].compact
73
- end
74
-
75
- config.before_configuration { load }
76
- end
77
- end