|
1 | | -# rust-dotenv |
| 1 | +# dotenvy |
2 | 2 |
|
3 | | - |
4 | | -[](https://codecov.io/gh/dotenv-rs/dotenv) |
5 | | -[](https://crates.io/crates/dotenv) |
| 3 | +[](https://crates.io/crates/dotenv) |
| 4 | + |
| 5 | +[](https://docs.rs/dotenvy) |
| 6 | +[](https://codecov.io/gh/allan2/dotenvy) |
6 | 7 |
|
7 | | -**Achtung!** This is a v0.\* version! Expect bugs and issues all around. |
8 | | -Submitting pull requests and issues is highly encouraged! |
| 8 | +A well-maintained fork of the [dotenv](https://github.com/dotenv-rs/dotenv) crate. |
9 | 9 |
|
10 | | -Quoting [bkeepers/dotenv][dotenv]: |
| 10 | +This library loads environment variables from a _.env_ file. This is convenient for dev environments. |
11 | 11 |
|
12 | | -> Storing [configuration in the environment](http://www.12factor.net/config) |
13 | | -> is one of the tenets of a [twelve-factor app](http://www.12factor.net/). |
14 | | -> Anything that is likely to change between deployment environments–such as |
15 | | -> resource handles for databases or credentials for external services–should |
16 | | -> be extracted from the code into environment variables. |
| 12 | +## Components |
17 | 13 |
|
18 | | -This library is meant to be used on development or testing environments in |
19 | | -which setting environment variables is not practical. It loads environment |
20 | | -variables from a `.env` file, if available, and mashes those with the actual |
21 | | -environment variables provided by the operative system. |
| 14 | +1. `dotenvy` crate - A well-maintained fork of the `dotenv` crate. |
| 15 | +2. `dotenvy_codegen` crate - A macro for compile time dotenv inspection. |
| 16 | +3. `dotenvy_codgen_impl` crate - Internal implementation for dotenvy_codegen. |
| 17 | +4. `dotenvy` CLI tool for running a command using the environment from a _.env_ file (currently Unix only) |
22 | 18 |
|
23 | | -Usage |
24 | | ----- |
| 19 | +## Usage |
25 | 20 |
|
26 | | -The easiest and most common usage consists on calling `dotenv::dotenv` when the |
27 | | -application starts, which will load environment variables from a file named |
28 | | -`.env` in the current directory or any of its parents; after that, you can just call |
29 | | -the environment-related method you need as provided by `std::os`. |
| 21 | +### Loading at runtime |
30 | 22 |
|
31 | | -If you need finer control about the name of the file or its location, you can |
32 | | -use the `from_filename` and `from_path` methods provided by the crate. |
33 | | - |
34 | | -`dotenv_codegen` provides the `dotenv!` macro, which |
35 | | -behaves identically to `env!`, but first tries to load a `.env` file at compile |
36 | | -time. |
37 | | - |
38 | | -Examples |
39 | | ----- |
40 | | - |
41 | | -A `.env` file looks like this: |
42 | | - |
43 | | -```sh |
44 | | -# a comment, will be ignored |
45 | | -REDIS_ADDRESS=localhost:6379 |
46 | | -MEANING_OF_LIFE=42 |
47 | | -``` |
48 | | - |
49 | | -You can optionally prefix each line with the word `export`, which will |
50 | | -conveniently allow you to source the whole file on your shell. |
51 | | - |
52 | | -A sample project using Dotenv would look like this: |
53 | | - |
54 | | -```rust |
55 | | -extern crate dotenv; |
56 | | - |
57 | | -use dotenv::dotenv; |
| 23 | +```rs |
| 24 | +use dotenvy::dotenv; |
58 | 25 | use std::env; |
59 | 26 |
|
60 | 27 | fn main() { |
61 | 28 | dotenv().ok(); |
62 | 29 |
|
63 | 30 | for (key, value) in env::vars() { |
64 | | - println!("{}: {}", key, value); |
| 31 | + println!("{key}: {value}"); |
65 | 32 | } |
66 | 33 | } |
67 | 34 | ``` |
68 | 35 |
|
69 | | -Variable substitution |
70 | | ----- |
| 36 | +### Loading at compile time |
71 | 37 |
|
72 | | -It's possible to reuse variables in the `.env` file using `$VARIABLE` syntax. |
73 | | -The syntax and rules are similar to bash ones, here's the example: |
| 38 | +The `dotenv!` macro provided by `dotenvy_codegen` crate can be used. |
74 | 39 |
|
| 40 | +Warning: there is an outstanding issue with rust-analyzer ([rust-analyzer #9606](https://github.com/rust-analyzer/rust-analyzer/issues/9606)) related to the `dotenv!` macro |
75 | 41 |
|
76 | | -```sh |
| 42 | +## Why does this fork exist? |
77 | 43 |
|
78 | | -VAR=one |
79 | | -VAR_2=two |
| 44 | +The original dotenv crate has not been updated since June 26, 2020. Attempts to reach the authors and present maintainer were not successful ([dotenv-rs/dotenv #74](https://github.com/dotenv-rs/dotenv/issues/74)). |
80 | 45 |
|
81 | | -# Non-existing values are replaced with an empty string |
82 | | -RESULT=$NOPE #value: '' (empty string) |
| 46 | +This fork is intended to serve as the development home for the dotenv implementation in Rust. |
83 | 47 |
|
84 | | -# All the letters after $ symbol are treated as the variable name to replace |
85 | | -RESULT=$VAR #value: 'one' |
| 48 | +## What are the differences from the original? |
86 | 49 |
|
87 | | -# Double quotes do not affect the substitution |
88 | | -RESULT="$VAR" #value: 'one' |
| 50 | +This repo fixes: |
89 | 51 |
|
90 | | -# Different syntax, same result |
91 | | -RESULT=${VAR} #value: 'one' |
| 52 | +- home directory works correctly (no longer using the deprecated `std::env::home_dir`) |
| 53 | +- more helpful errors for `dotenv!` ([dotenv-rs/dotenv #57](https://github.com/dotenv-rs/dotenv/pull/57/files#)) |
92 | 54 |
|
93 | | -# Curly braces are useful in cases when we need to use a variable with non-alphanumeric name |
94 | | -RESULT=$VAR_2 #value: 'one_2' since $ with no curly braces stops after first non-alphanumeric symbol |
95 | | -RESULT=${VAR_2} #value: 'two' |
| 55 | +For a full list of changes, read the [changelog](./CHANGELOG.md). |
96 | 56 |
|
97 | | -# The replacement can be escaped with either single quotes or a backslash: |
98 | | -RESULT='$VAR' #value: '$VAR' |
99 | | -RESULT=\$VAR #value: '$VAR' |
100 | | - |
101 | | -# Environment variables are used in the substutution and always override the local variables |
102 | | -RESULT=$PATH #value: the contents of the $PATH environment variable |
103 | | -PATH="My local variable value" |
104 | | -RESULT=$PATH #value: the contents of the $PATH environment variable, even though the local variable is defined |
105 | | -``` |
| 57 | +## Are you a usurper of the dotenv legacy? |
106 | 58 |
|
107 | | -Dotenv will parse the file, substituting the variables the way it's described in the comments. |
108 | | - |
109 | | - |
110 | | -Using the `dotenv!` macro |
111 | | ------------------------------------- |
112 | | - |
113 | | -Add `dotenv_codegen` to your dependencies, and add the following to the top of |
114 | | -your crate: |
115 | | - |
116 | | -```rust |
117 | | -#[macro_use] |
118 | | -extern crate dotenv_codegen; |
119 | | -``` |
120 | | - |
121 | | -Then, in your crate: |
122 | | - |
123 | | -```rust |
124 | | -fn main() { |
125 | | - println!("{}", dotenv!("MEANING_OF_LIFE")); |
126 | | -} |
127 | | -``` |
| 59 | +Legend has it that the Lost Maintainer will return, merging changes from `dotenvy` into `dotenv` with such thrust that all `Cargo.toml`s will lose one keystroke. Only then shall the Rust dotenv crateverse be united in true harmony. |
128 | 60 |
|
129 | | -[dotenv]: https://github.com/bkeepers/dotenv |
| 61 | +Until then, this repo dutifully carries on the dotenv torch. It is actively maintained. Contributions and PRs are very welcome! |
0 commit comments