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