1 [![Build Status](https://travis-ci.org/Tarrasch/zsh-autoenv.svg?branch=master)](https://travis-ci.org/Tarrasch/zsh-autoenv)
5 zsh-autoenv automatically sources (known/whitelisted) `.autoenv.zsh` files,
6 typically used in project root directories.
8 It handles "enter" and leave" events, nesting, and stashing of
9 variables (overwriting and restoring).
13 - Zsh version 4.3.10 or later.
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`
20 - Interactively asks for confirmation / authentication before sourcing an
21 unknown `.autoenv.zsh` file, and remembers whitelisted files by their
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
32 % echo 'echo ENTERED; autostash FOO=changed' > project/.autoenv.zsh
35 Attempting to load unauthorized env file!
36 -rw-rw-r-- 1 user user 36 Mai 6 20:38 /tmp/project/.autoenv.zsh
38 **********************************************
40 echo ENTERED; autostash FOO=changed
42 **********************************************
44 Would you like to authorize it? (type 'yes') yes
52 There is also `stash`, `unstash` and `autounstash`, in case you want to
55 The varstash library has been taken from smartcd, and was optimized for Zsh.
57 ## Writing your .autoenv.zsh file
59 ### `autoenv_source_parent()`
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.
65 The function accepts an optional argument, which allows to stop looking before
66 the file system root is reached:
69 autoenv_source_parent ../..
74 Clone the repository and source it from your `~/.zshrc` file:
76 % git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
77 % echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
79 ### Using [antigen](https://github.com/zsh-users/antigen)
81 antigen-bundle Tarrasch/zsh-autoenv
83 ### Using [zgen](https://github.com/tarjoilija/zgen)
85 Add the following to your `.zshrc` where you are loading your plugins:
87 zgen load Tarrasch/zsh-autoenv
89 ### Using [zplug](https://github.com/zplug/zplug)
91 Add the following to your `.zshrc` where you are loading your plugins:
93 zplug "Tarrasch/zsh-autoenv"
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.
100 ### AUTOENV_FILE_ENTER
102 Name of the file to look for when entering directories.
104 Default: `.autoenv.zsh`
106 ### AUTOENV_FILE_LEAVE
108 Name of the file to look for when leaving directories.
109 Requires `AUTOENV_HANDLE_LEAVE=1`.
111 Default: `.autoenv_leave.zsh`
113 ### AUTOENV_LOOK_UPWARDS
115 Look for zsh-autoenv "enter" files in parent dirs?
119 ### AUTOENV_HANDLE_LEAVE
121 Handle leave events when changing away from a subtree, where an "enter"
128 (Temporarily) disable zsh-autoenv. This gets looked at in the chpwd handler.
134 Set debug level. If enabled (> 0) it will print information to stderr.
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
141 - sets xtrace option (`set -x`) while sourcing env files
147 zsh-autoenv works automatically once installed.
149 You can use ``autoenv-edit`` to edit the nearest/current autoenv files.
150 It will use ``$AUTOENV_EDITOR``, ``$EDITOR``, or ``vim`` for editing.
154 The following helper functions are available:
156 ### autoenv_append_path
158 Appends path(s) to `$path` (`$PATH`), if they are not in there already.
160 ### autoenv_prepend_path
162 Prepends path(s) to `$path` (`$PATH`), if they are not in there already.
164 ### autoenv_remove_path
166 Removes path(s) from `$path` (`$PATH`).
168 Returns 0 in case `$path` has changed, 1 otherwise.
172 ### Automatically activate Python virtualenvs
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`):
181 # Environment file for all projects.
182 # - (de)activates Python virtualenvs (.venv) from pipenv
184 if [[ $autoenv_event == 'enter' ]]; then
185 autoenv_source_parent
187 _my_autoenv_venv_chpwd() {
188 if [[ -z "$_ZSH_ACTIVATED_VIRTUALENV" && -n "$VIRTUAL_ENV" ]]; then
192 setopt localoptions extendedglob
194 venv=(./(../)#.venv(NY1:A))
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
201 # Simulate "deactivate", but handle $PATH better (remove VIRTUAL_ENV).
202 if ! autoenv_remove_path $VIRTUAL_ENV/bin; then
203 echo "warning: ${VIRTUAL_ENV}/bin not found in \$PATH" >&2
206 # NOTE: does not handle PYTHONHOME/_OLD_VIRTUAL_PYTHONHOME
207 unset _OLD_VIRTUAL_PYTHONHOME
208 # NOTE: does not handle PS1/_OLD_VIRTUAL_PS1
209 unset _OLD_VIRTUAL_PS1
214 if [[ -z "$VIRTUAL_ENV" ]]; then
215 if (( $#venv )); then
216 echo "Activating virtualenv: ${(D)venv}" >&2
217 export VIRTUAL_ENV=$venv[1]
218 autoenv_prepend_path $VIRTUAL_ENV/bin
219 _ZSH_ACTIVATED_VIRTUALENV="$venv[1]"
223 autoload -U add-zsh-hook
224 add-zsh-hook chpwd _my_autoenv_venv_chpwd
225 _my_autoenv_venv_chpwd
227 add-zsh-hook -d chpwd _my_autoenv_venv_chpwd
233 - <https://github.com/direnv/direnv>
234 - <https://github.com/cxreg/smartcd>
235 - <https://github.com/kennethreitz/autoenv>
239 This started as an optimized version of the bash plugin
240 [autoenv](https://github.com/kennethreitz/autoenv) but for Zsh, and grew a lot
241 of functionality on top of it (inspired by [smartcd]).
243 The code was initially based on
244 [@joshuaclayton](https://github.com/joshuaclayton)'s dotfiles.
245 In September 2013 [@Tarrasch](https://github.com/Tarrasch) packaged it into a
246 nice [antigen]-compatible unit with integration tests. Since November 2014,
247 [@blueyed](https://github.com/blueyed) took over and added many nice
248 features, mainly inspired by [smartcd].
250 [antigen]: https://github.com/Tarrasch/antigen-hs
251 [smartcd]: https://github.com/cxreg/smartcd