README.md

   1 [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/Tarrasch/zsh-autoenv/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
   2
   3 [![Build Status](https://travis-ci.org/Tarrasch/zsh-autoenv.svg?branch=master)](https://travis-ci.org/Tarrasch/zsh-autoenv)
   4
   5 # Autoenv for Zsh
   6
   7 zsh-autoenv automatically sources `.env` files, typically used in project
   8 root directories.
   9
  10 It handles "enter" and leave" events, nesting, and stashing of
  11 variables (overwriting and restoring).
  12
  13 ## Features
  14
  15  - Support for enter and leave events, which can use the same file.
  16    By default `.env` is used for entering, and `.env_leave` for leaving.
  17  - Asks for confirmation / authentication before sourcing a `.env` file, and
  18    remembers whitelisted files by its hash.
  19  - Test suite.
  20  - Written in Zsh.
  21
  22 ### Variable stashing
  23
  24 You can use `autostash` in your `.env` files to overwrite some variable, e.g.
  25 `$PATH`.  When leaving the directory, it will be automatically restored.
  26
  27     % echo 'echo ENTERED; autostash FOO=changed' > project/.env
  28     % FOO=orig
  29     % cd project
  30     Attempting to load unauthorized env file!
  31     -rw-rw-r-- 1 user user 36 Mai  6 20:38 /tmp/project/.env
  32
  33     **********************************************
  34
  35     echo ENTERED; autostash FOO=changed
  36
  37     **********************************************
  38
  39     Would you like to authorize it? (type 'yes') yes
  40     ENTERED
  41     project % echo $FOO
  42     changed
  43     % cd ..
  44     % echo $FOO
  45     orig
  46
  47 There is also `stash`, `unstash` and `autounstash`, in case you want to
  48 have more control.
  49
  50 The varstash library has been taken from smartcd, and was optimized for Zsh.
  51
  52
  53 ## Writing your .env file
  54
  55 ### `autoenv_source_parent()`
  56
  57 zsh-autoenv will stop looking for `.env` files after the first one has been
  58 found.  But you can use the function `autoenv_source_parent` to source a
  59 parent `.env` file from there.
  60
  61
  62 ## Installation
  63
  64 Clone the repository and source it from your `~/.zshrc` file:
  65
  66     % git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
  67     % echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
  68
  69 ### Using [antigen](https://github.com/zsh-users/antigen)
  70
  71     antigen-bundle Tarrasch/zsh-autoenv
  72
  73 ### Using [zgen](https://github.com/tarjoilija/zgen)
  74
  75 Add the following to your `.zshrc` where you are loading your plugins:
  76
  77     zgen load Tarrasch/zsh-autoenv
  78
  79
  80 ## Configuration
  81
  82 You can use the following variables to control zsh-autoenv's behavior.
  83 Add them to your `~/.zshrc` file, before sourcing/loading zsh-autoenv.
  84
  85 ### AUTOENV\_FILE\_ENTER
  86 Name of the file to look for when entering directories.
  87
  88 Default: `.env`
  89
  90 ### AUTOENV\_FILE\_LEAVE
  91 Name of the file to look for when leaving directories.
  92 Requires `AUTOENV_HANDLE_LEAVE=1`.
  93
  94 Default: `.env_leave`
  95
  96 ### AUTOENV\_LOOK\_UPWARDS
  97 Look for .env files in parent dirs?
  98
  99 Default: `1`
 100
 101 ### AUTOENV\_HANDLE\_LEAVE
 102 Handle leave events when changing away from a subtree, where an "enter"
 103 event was handled?
 104
 105 Default: `1`
 106
 107 ### AUTOENV\_DISABLED
 108 (Temporarily) disable zsh-autoenv. This gets looked at in the chpwd handler.
 109
 110 Default: 0
 111
 112 ### `AUTOENV_DEBUG`
 113 Enable debugging. Multiple levels are supported (max 2).
 114
 115 Default: `0`
 116
 117
 118 ## Related projects
 119 - https://github.com/cxreg/smartcd
 120 - https://github.com/kennethreitz/autoenv
 121
 122
 123 ## History
 124
 125 This started as a optimized version of
 126 [autoenv](https://github.com/kennethreitz/autoenv) for Zsh, but grew a lot of
 127 functionality on top of it (inspired by
 128 [smartcd](https://github.com/cxreg/smartcd)).
 129
 130 The code was initially based on [Joshua Clayton](https://github.com/joshuaclayton)'s work.