stow/oh-my-zsh/.oh-my-zsh/plugins/dotenv/README.md

   1 # dotenv
   2
   3 Automatically load your project ENV variables from `.env` file when you `cd` into project root directory.
   4
   5 Storing configuration in the environment is one of the tenets of a [twelve-factor app](https://www.12factor.net). Anything that is likely to change between deployment environments, such as resource handles for databases or credentials for external services, should be extracted from the code into environment variables.
   6
   7 To use it, add `dotenv` to the plugins array in your zshrc file:
   8
   9 ```sh
  10 plugins=(... dotenv)
  11 ```
  12
  13 ## Usage
  14
  15 Create `.env` file inside your project root directory and put your ENV variables there.
  16
  17 For example:
  18
  19 ```sh
  20 export AWS_S3_TOKEN=d84a83539134f28f412c652b09f9f98eff96c9a
  21 export SECRET_KEY=7c6c72d959416d5aa368a409362ec6e2ac90d7f
  22 export MONGO_URI=mongodb://127.0.0.1:27017
  23 export PORT=3001
  24 ```
  25
  26 `export` is optional. This format works as well:
  27
  28 ```sh
  29 AWS_S3_TOKEN=d84a83539134f28f412c652b09f9f98eff96c9a
  30 SECRET_KEY=7c6c72d959416d5aa368a409362ec6e2ac90d7f
  31 MONGO_URI=mongodb://127.0.0.1:27017
  32 PORT=3001
  33 ```
  34
  35 You can even mix both formats, although it's probably a bad idea.
  36
  37 ## Settings
  38
  39 ### ZSH_DOTENV_FILE
  40
  41 You can also modify the name of the file to be loaded with the variable `ZSH_DOTENV_FILE`.
  42 If the variable isn't set, the plugin will default to use `.env`.
  43 For example, this will make the plugin look for files named `.dotenv` and load them:
  44
  45 ```zsh
  46 # in ~/.zshrc, before Oh My Zsh is sourced:
  47 ZSH_DOTENV_FILE=.dotenv
  48 ```
  49
  50 ### ZSH_DOTENV_PROMPT
  51
  52 Set `ZSH_DOTENV_PROMPT=false` in your zshrc file if you don't want the confirmation message.
  53 You can also choose the `Always` option when prompted to always allow sourcing the .env file
  54 in that directory. See the next section for more details.
  55
  56 ### ZSH_DOTENV_ALLOWED_LIST, ZSH_DOTENV_DISALLOWED_LIST
  57
  58 The default behavior of the plugin is to always ask whether to source a dotenv file. There's
  59 a **Y**es, **N**o, **A**lways and N**e**ver option. If you choose Always, the directory of the .env file
  60 will be added to an allowed list; if you choose Never, it will be added to a disallowed list.
  61 If a directory is found in either of those lists, the plugin won't ask for confirmation and will
  62 instead either source the .env file or proceed without action respectively.
  63
  64 The allowed and disallowed lists are saved by default in `$ZSH_CACHE_DIR/dotenv-allowed.list` and
  65 `$ZSH_CACHE_DIR/dotenv-disallowed.list` respectively. If you want to change that location,
  66 change the `$ZSH_DOTENV_ALLOWED_LIST` and `$ZSH_DOTENV_DISALLOWED_LIST` variables, like so:
  67
  68 ```zsh
  69 # in ~/.zshrc, before Oh My Zsh is sourced:
  70 ZSH_DOTENV_ALLOWED_LIST=/path/to/dotenv/allowed/list
  71 ZSH_DOTENV_DISALLOWED_LIST=/path/to/dotenv/disallowed/list
  72 ```
  73
  74 The file is just a list of directories, separated by a newline character. If you want
  75 to change your decision, just edit the file and remove the line for the directory you want to
  76 change.
  77
  78 NOTE: if a directory is found in both the allowed and disallowed lists, the disallowed list
  79 takes preference, _i.e._ the .env file will never be sourced.
  80
  81 ## Version Control
  82
  83 **It's strongly recommended to add `.env` file to `.gitignore`**, because usually it contains sensitive information such as your credentials, secret keys, passwords etc. You don't want to commit this file, it's supposed to be local only.
  84
  85 ## Disclaimer
  86
  87 This plugin only sources the `.env` file. Nothing less, nothing more. It doesn't do any checks. It's designed to be the fastest and simplest option. You're responsible for the `.env` file content. You can put some code (or weird symbols) there, but do it on your own risk. `dotenv` is the basic tool, yet it does the job.
  88
  89 If you need more advanced and feature-rich ENV management, check out these awesome projects:
  90
  91 * [direnv](https://github.com/direnv/direnv)
  92 * [zsh-autoenv](https://github.com/Tarrasch/zsh-autoenv)