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 (known/whitelisted) `.autoenv.zsh` files,
   8 typically used in project 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 `.autoenv.zsh` is used for entering, and `.autoenv_leave.zsh`
  17    for leaving.
  18  - Interactively asks for confirmation / authentication before sourcing an
  19    unknown `.autoenv.zsh` file, and remembers whitelisted files by their
  20    hashed content.
  21  - Test suite.
  22  - Written in Zsh.
  23
  24 ### Variable stashing
  25
  26 You can use `autostash` in your `.autoenv.zsh` files to overwrite some
  27 variable, e.g.  `$PATH`.  When leaving the directory, it will be automatically
  28 restored.
  29
  30     % echo 'echo ENTERED; autostash FOO=changed' > project/.autoenv.zsh
  31     % FOO=orig
  32     % cd project
  33     Attempting to load unauthorized env file!
  34     -rw-rw-r-- 1 user user 36 Mai  6 20:38 /tmp/project/.autoenv.zsh
  35
  36     **********************************************
  37
  38     echo ENTERED; autostash FOO=changed
  39
  40     **********************************************
  41
  42     Would you like to authorize it? (type 'yes') yes
  43     ENTERED
  44     project % echo $FOO
  45     changed
  46     % cd ..
  47     % echo $FOO
  48     orig
  49
  50 There is also `stash`, `unstash` and `autounstash`, in case you want to
  51 have more control.
  52
  53 The varstash library has been taken from smartcd, and was optimized for Zsh.
  54
  55
  56 ## Writing your .autoenv.zsh file
  57
  58 ### `autoenv_source_parent()`
  59
  60 zsh-autoenv will stop looking for `.autoenv.zsh` files upwards after the first
  61 one has been found, but you can use the function `autoenv_source_parent` to
  62 source the next `.autoenv.zsh` file upwards the directory tree from there.
  63
  64 The function accepts an optional argument, which allows to stop looking before
  65 the file system root is reached:
  66
  67 ```zsh
  68 autoenv_source_parent ../..
  69 ```
  70
  71 ## Installation
  72
  73 Clone the repository and source it from your `~/.zshrc` file:
  74
  75     % git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
  76     % echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
  77
  78 ### Using [antigen](https://github.com/zsh-users/antigen)
  79
  80     antigen-bundle Tarrasch/zsh-autoenv
  81
  82 ### Using [zgen](https://github.com/tarjoilija/zgen)
  83
  84 Add the following to your `.zshrc` where you are loading your plugins:
  85
  86     zgen load Tarrasch/zsh-autoenv
  87
  88 ### Using [zplug](https://github.com/zplug/zplug)
  89
  90 Add the following to your `.zshrc` where you are loading your plugins:
  91
  92     zplug "Tarrasch/zsh-autoenv"
  93
  94 ## Configuration
  95
  96 You can use the following variables to control zsh-autoenv's behavior.
  97 Add them to your `~/.zshrc` file, before sourcing/loading zsh-autoenv.
  98
  99 ### AUTOENV\_FILE\_ENTER
 100 Name of the file to look for when entering directories.
 101
 102 Default: `.autoenv.zsh`
 103
 104 ### AUTOENV\_FILE\_LEAVE
 105 Name of the file to look for when leaving directories.
 106 Requires `AUTOENV_HANDLE_LEAVE=1`.
 107
 108 Default: `.autoenv_leave.zsh`
 109
 110 ### AUTOENV\_LOOK\_UPWARDS
 111 Look for zsh-autoenv "enter" files in parent dirs?
 112
 113 Default: `1`
 114
 115 ### AUTOENV\_HANDLE\_LEAVE
 116 Handle leave events when changing away from a subtree, where an "enter"
 117 event was handled?
 118
 119 Default: `1`
 120
 121 ### AUTOENV\_DISABLED
 122 (Temporarily) disable zsh-autoenv. This gets looked at in the chpwd handler.
 123
 124 Default: 0
 125
 126 ### AUTOENV\_DEBUG
 127 Enable debugging. Multiple levels are supported (max 2).
 128
 129 Default: `0`
 130
 131 ## Recipes
 132
 133 ### Automatically activate Python virtualenvs
 134
 135 Given `AUTOENV_FILE_ENTER=.autoenv.zsh`, `AUTOENV_FILE_LEAVE=.autoenv.zsh` and
 136 `AUTOENV_HANDLE_LEAVE=1` the following script will activate Python virtualenvs
 137 automatically in all subdirectories (`.venv` directories get used by
 138 [pipenv](https://github.com/kennethreitz/pipenv) with
 139 `PIPENV_VENV_IN_PROJECT=1`):
 140
 141 ```zsh
 142 # Environment file for all projects.
 143 #  - (de)activates Python virtualenvs (.venv) from pipenv
 144
 145 if [[ $autoenv_event == 'enter' ]]; then
 146   autoenv_source_parent
 147
 148   _my_autoenv_venv_chpwd() {
 149     if [[ -z "$_ZSH_ACTIVATED_VIRTUALENV" && -n "$VIRTUAL_ENV" ]]; then
 150       return
 151     fi
 152
 153     setopt localoptions extendedglob
 154     local -a venv
 155     venv=(./(../)#.venv(NY1:A))
 156
 157     if [[ -n "$_ZSH_ACTIVATED_VIRTUALENV" ]]; then
 158       if ! (( $#venv )) || [[ "$_ZSH_ACTIVATED_VIRTUALENV" != "$venv[1]" ]]; then
 159         echo "De-activating virtualenv: $VIRTUAL_ENV" >&2
 160         deactivate
 161         unset _ZSH_ACTIVATED_VIRTUALENV
 162       fi
 163     fi
 164
 165     if [[ -z "$VIRTUAL_ENV" ]]; then
 166       if (( $#venv )); then
 167         echo "Activating virtualenv: $venv" >&2
 168         source $venv[1]/bin/activate
 169         _ZSH_ACTIVATED_VIRTUALENV="$venv[1]"
 170       fi
 171     fi
 172   }
 173   autoload -U add-zsh-hook
 174   add-zsh-hook chpwd _my_autoenv_venv_chpwd
 175   _my_autoenv_venv_chpwd
 176 else
 177   add-zsh-hook -d chpwd _my_autoenv_venv_chpwd
 178 fi
 179 ```
 180
 181 ## Related projects
 182 - https://github.com/direnv/direnv
 183 - https://github.com/cxreg/smartcd
 184 - https://github.com/kennethreitz/autoenv
 185
 186
 187 ## History
 188
 189 This started as an optimized version of the bash plugin
 190 [autoenv](https://github.com/kennethreitz/autoenv) but for Zsh, and grew a lot
 191 of functionality on top of it (inspired by [smartcd]).
 192
 193 The code was initially based on
 194 [@joshuaclayton](https://github.com/joshuaclayton)'s dotfiles.
 195 In September 2013 [@Tarrasch](https://github.com/Tarrasch) packaged it into a
 196 nice [antigen]-compatible unit with integration tests. Since November 2014,
 197 [@blueyed](https://github.com/blueyed) took over and added many many nice
 198 features, mainly inspired by [smartcd].
 199
 200 [antigen]: https://github.com/Tarrasch/antigen-hs
 201 [smartcd]: https://github.com/cxreg/smartcd