README.md

   1 [![Build Status](https://travis-ci.org/Tarrasch/zsh-autoenv.svg?branch=master)](https://travis-ci.org/Tarrasch/zsh-autoenv)
   2
   3 # Autoenv for Zsh
   4
   5 zsh-autoenv automatically sources (known/whitelisted) `.autoenv.zsh` files,
   6 typically used in project root directories.
   7
   8 It handles "enter" and leave" events, nesting, and stashing of
   9 variables (overwriting and restoring).
  10
  11 ## Requirements
  12
  13 - Zsh version 4.3.10 or later.
  14
  15 ## Features
  16
  17 - Support for enter and leave events, which can use the same file.
  18   By default it uses `.autoenv.zsh` for entering, and `.autoenv_leave.zsh`
  19   for leaving.
  20 - Interactively asks for confirmation / authentication before sourcing an
  21   unknown `.autoenv.zsh` file, and remembers whitelisted files by their
  22   hashed content.
  23 - Test suite.
  24 - Written in/for Zsh.
  25
  26 ### Variable stashing
  27
  28 You can use `autostash` in your `.autoenv.zsh` files to overwrite some
  29 variable, e.g.  `$PATH`.  When leaving the directory, it will be automatically
  30 restored.
  31
  32     % echo 'echo ENTERED; autostash FOO=changed' > project/.autoenv.zsh
  33     % FOO=orig
  34     % cd project
  35     Attempting to load unauthorized env file!
  36     -rw-rw-r-- 1 user user 36 Mai  6 20:38 /tmp/project/.autoenv.zsh
  37
  38     **********************************************
  39
  40     echo ENTERED; autostash FOO=changed
  41
  42     **********************************************
  43
  44     Would you like to authorize it? (type 'yes') yes
  45     ENTERED
  46     project % echo $FOO
  47     changed
  48     % cd ..
  49     % echo $FOO
  50     orig
  51
  52 There is also `stash`, `unstash` and `autounstash`, in case you want to
  53 have more control.
  54
  55 The varstash library has been taken from smartcd, and was optimized for Zsh.
  56
  57 ## Writing your .autoenv.zsh file
  58
  59 ### `autoenv_source_parent()`
  60
  61 zsh-autoenv will stop looking for `.autoenv.zsh` files upwards after the first
  62 one has been found, but you can use the function `autoenv_source_parent` to
  63 source the next `.autoenv.zsh` file upwards the directory tree from there.
  64
  65 The function accepts an optional argument, which allows to stop looking before
  66 the file system root is reached:
  67
  68 ```zsh
  69 autoenv_source_parent ../..
  70 ```
  71
  72 ## Installation
  73
  74 Clone the repository and source it from your `~/.zshrc` file:
  75
  76     % git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
  77     % echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
  78
  79 ### Using [antigen](https://github.com/zsh-users/antigen)
  80
  81     antigen-bundle Tarrasch/zsh-autoenv
  82
  83 ### Using [zgen](https://github.com/tarjoilija/zgen)
  84
  85 Add the following to your `.zshrc` where you are loading your plugins:
  86
  87     zgen load Tarrasch/zsh-autoenv
  88
  89 ### Using [zplug](https://github.com/zplug/zplug)
  90
  91 Add the following to your `.zshrc` where you are loading your plugins:
  92
  93     zplug "Tarrasch/zsh-autoenv"
  94
  95 ## Configuration
  96
  97 You can use the following variables to control zsh-autoenv's behavior.
  98 Add them to your `~/.zshrc` file, before sourcing/loading zsh-autoenv.
  99
 100 ### AUTOENV_FILE_ENTER
 101
 102 Name of the file to look for when entering directories.
 103
 104 Default: `.autoenv.zsh`
 105
 106 ### AUTOENV_FILE_LEAVE
 107
 108 Name of the file to look for when leaving directories.
 109 Requires `AUTOENV_HANDLE_LEAVE=1`.
 110
 111 Default: `.autoenv_leave.zsh`
 112
 113 ### AUTOENV_LOOK_UPWARDS
 114
 115 Look for zsh-autoenv "enter" files in parent dirs?
 116
 117 Default: `1`
 118
 119 ### AUTOENV_HANDLE_LEAVE
 120
 121 Handle leave events when changing away from a subtree, where an "enter"
 122 event was handled?
 123
 124 Default: `1`
 125
 126 ### AUTOENV_DISABLED
 127
 128 (Temporarily) disable zsh-autoenv. This gets looked at in the chpwd handler.
 129
 130 Default: 0
 131
 132 ### AUTOENV_DEBUG
 133
 134 Set debug level. If enabled (> 0) it will print information to stderr.
 135
 136 - 0: no debug messages
 137 - 1: generic debug logging
 138 - 2: more verbose messages
 139   - messages about adding/removing files on the internal stack
 140 - 3: everything
 141   - sets xtrace option (`set -x`) while sourcing env files
 142
 143 Default: `0`
 144
 145 ## Usage
 146
 147 zsh-autoenv works automatically once installed.
 148
 149 You can use ``autoenv-edit`` to edit the nearest/current autoenv files.
 150 It will use ``$AUTOENV_EDITOR``, ``$EDITOR``, or ``vim`` for editing.
 151
 152 ## Helper functions
 153
 154 The following helper functions are available:
 155
 156 ### autoenv_append_path
 157
 158 Appends path(s) to `$path` (`$PATH`), if they are not in there already.
 159
 160 ### autoenv_prepend_path
 161
 162 Prepends path(s) to `$path` (`$PATH`), if they are not in there already.
 163
 164 ### autoenv_remove_path
 165
 166 Removes path(s) from `$path` (`$PATH`).
 167
 168 Returns 0 in case `$path` has changed, 1 otherwise.
 169
 170 ## Recipes
 171
 172 ### Automatically activate Python virtualenvs
 173
 174 Given `AUTOENV_FILE_ENTER=.autoenv.zsh`, `AUTOENV_FILE_LEAVE=.autoenv.zsh` and
 175 `AUTOENV_HANDLE_LEAVE=1` the following script will activate Python virtualenvs
 176 automatically in all subdirectories (`.venv` directories get used by
 177 [pipenv](https://github.com/kennethreitz/pipenv) with
 178 `PIPENV_VENV_IN_PROJECT=1`):
 179
 180 ```zsh
 181 # Environment file for all projects.
 182 #  - (de)activates Python virtualenvs (.venv) from pipenv
 183
 184 if [[ $autoenv_event == 'enter' ]]; then
 185   autoenv_source_parent
 186
 187   _my_autoenv_venv_chpwd() {
 188     if [[ -z "$_ZSH_ACTIVATED_VIRTUALENV" && -n "$VIRTUAL_ENV" ]]; then
 189       return
 190     fi
 191
 192     setopt localoptions extendedglob
 193     local -a venv
 194     venv=(./(../)#.venv(NY1:a))
 195
 196     if [[ -n "$_ZSH_ACTIVATED_VIRTUALENV" && -n "$VIRTUAL_ENV" ]]; then
 197       if ! (( $#venv )) || [[ "$_ZSH_ACTIVATED_VIRTUALENV" != "$venv[1]" ]]; then
 198         unset _ZSH_ACTIVATED_VIRTUALENV
 199         echo "De-activating virtualenv: ${(D)VIRTUAL_ENV}" >&2
 200         deactivate
 201       fi
 202     fi
 203
 204     if [[ -z "$VIRTUAL_ENV" ]]; then
 205       if (( $#venv )); then
 206         echo "Activating virtualenv: ${(D)venv}" >&2
 207         source $venv[1]/bin/activate
 208         _ZSH_ACTIVATED_VIRTUALENV="$venv[1]"
 209       fi
 210     fi
 211   }
 212   autoload -U add-zsh-hook
 213   add-zsh-hook chpwd _my_autoenv_venv_chpwd
 214   _my_autoenv_venv_chpwd
 215 else
 216   add-zsh-hook -d chpwd _my_autoenv_venv_chpwd
 217 fi
 218 ```
 219
 220 ## Related projects
 221
 222 - <https://github.com/direnv/direnv>
 223 - <https://github.com/cxreg/smartcd>
 224 - <https://github.com/kennethreitz/autoenv>
 225
 226 ## History
 227
 228 This started as an optimized version of the bash plugin
 229 [autoenv](https://github.com/kennethreitz/autoenv) but for Zsh, and grew a lot
 230 of functionality on top of it (inspired by [smartcd]).
 231
 232 The code was initially based on
 233 [@joshuaclayton](https://github.com/joshuaclayton)'s dotfiles.
 234 In September 2013 [@Tarrasch](https://github.com/Tarrasch) packaged it into a
 235 nice [antigen]-compatible unit with integration tests. Since November 2014,
 236 [@blueyed](https://github.com/blueyed) took over and added many nice
 237 features, mainly inspired by [smartcd].
 238
 239 [antigen]: https://github.com/Tarrasch/antigen-hs
 240 [smartcd]: https://github.com/cxreg/smartcd