## Motivation
Projects often rely on environmental variables stored in a `.env` file to run... and because these
variables sometimes contain sensitive data, we never add them to source control.
Instead, these variables are added e.g. to a `.env.example` file so it's easy to
get the project running for other developers. However, it's very easy to forget to update this file
when a variable is added/updated in `.env` (during development). This can make
it difficult for devs to get the project running (locally) because they rely on
`.env.example` file to setup their environment (with their own configs).
Enter `sync-dotenv` 🔥
## Description
`sync-dotenv` automates the process of keeping your
`.env` in sync with `.env.example`.
## Installation
```bash
$ npm install -g sync-dotenv
```
Install as a dev dependency (**recommended**)
```bash
$ npm install -D sync-dotenv
```
## Usage
By default, `sync-dotenv` looks for a `.env` in your working directory and
attempt to sync with `.env.example` when no argument is provided. Failure
to find these files will cause the sync to fail.
```
$ sync-dotenv
```
Alternatively, you can use the `--env` and `--sample` flag to specify the source and destination file.
```
$ sync-dotenv --env foo/.env --sample bar/.env.example
```
Also, in the situation where you want to keep multiple files in sync with one source `env` file you can make use of the `--samples` flag specifying a globbing pattern to match:
```sh
$ sync-dotenv --env foo/.env --samples "env-samples/*"
# note: glob pattern should be provided as a string as shown above
```
For CLI options, use the `--help` flag
```
$ sync-dotenv --help
```
## Examples
Sync (with `.env.example`) before every commit using [husky](https://github.com/typicode/husky)
```js
// package.json
{
"scripts": {
"env": "sync-dotenv"
},
"husky": {
"hooks": {
"pre-commit": "npm run env",
}
}
}
```
Or with file other than `.env.example`
```diff
{
"scripts": {
- "env": "sync-dotenv"
+ "env": "sync-dotenv --sample .env.development"
}
}
```
### Preserving variables in sample env
Sometimes you need to preserve certain variables in your example env file, you can optionally allow this by adding a `sync-dotenv` config in `package.json` like so
```js
// package.json
"scripts": {
...
},
"sync-dotenv": {
"preserve": ["CHANNEL"]
}
```
### Avoid comments or empty lines in sample env
You might not want to copy empty lines or comments to your sample env, in this case you can still use `sync-dotenv` config in `package.json` with the following:
```js
// package.json
"scripts": {
...
},
"sync-dotenv": {
"emptyLines": true,
"comments": false
}
```
Note that you can still combine those options with `preserve`.
## Related
- [parse-dotenv](https://github.com/codeshifu/parse-dotenv) - zero dependency `.env` to javascript object parser
## Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
