Autoenv for zsh
Shell Perl Perl6 Makefile
Latest commit dfb5648 Jan 10, 2017 @rspeed rspeed committed with blueyed Automatically upgrade v1 hashes (SHA-1) to v2 (`cksum`) (#55)
A new parameter is added to `_autoenv_hash_pair` to specify the version, defaulting to the latest (2). It outputs a `cksum`-based hash for version 2 and `shasum`-based for version 1.
Moves logic to check for an entry in `$AUTOENV_AUTH_FILE` into its own function (`_autoenv_authorized_pair`), as it may need to be called twice.
Modifies `_autoenv_authorized_env_file` to check for v1 entries when v2 fails.

Fixes #53. Alternative implementation to #54.

Bitdeli Badge

Build Status

Autoenv for Zsh

zsh-autoenv automatically sources (known/whitelisted) .autoenv.zsh files, typically used in project root directories.

It handles "enter" and leave" events, nesting, and stashing of variables (overwriting and restoring).


  • Support for enter and leave events, which can use the same file. By default .autoenv.zsh is used for entering, and .autoenv_leave.zsh for leaving.
  • Interactively asks for confirmation / authentication before sourcing an unknown .autoenv.zsh file, and remembers whitelisted files by their hashed content.
  • Test suite.
  • Written in Zsh.

Variable stashing

You can use autostash in your .autoenv.zsh files to overwrite some variable, e.g. $PATH. When leaving the directory, it will be automatically restored.

% echo 'echo ENTERED; autostash FOO=changed' > project/.autoenv.zsh
% FOO=orig
% cd project
Attempting to load unauthorized env file!
-rw-rw-r-- 1 user user 36 Mai  6 20:38 /tmp/project/.autoenv.zsh


echo ENTERED; autostash FOO=changed


Would you like to authorize it? (type 'yes') yes
project % echo $FOO
% cd ..
% echo $FOO

There is also stash, unstash and autounstash, in case you want to have more control.

The varstash library has been taken from smartcd, and was optimized for Zsh.

Writing your .autoenv.zsh file


zsh-autoenv will stop looking for .autoenv.zsh files upwards after the first one has been found, but you can use the function autoenv_source_parent to source the next .autoenv.zsh file upwards the directory tree from there.

The function accepts an optional argument, which allows to stop looking before the file system root is reached:

autoenv_source_parent ../..


Clone the repository and source it from your ~/.zshrc file:

% git clone ~/.dotfiles/lib/zsh-autoenv
% echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc

Using antigen

antigen-bundle Tarrasch/zsh-autoenv

Using zgen

Add the following to your .zshrc where you are loading your plugins:

zgen load Tarrasch/zsh-autoenv

Using zplug

Add the following to your .zshrc where you are loading your plugins:

zplug "Tarrasch/zsh-autoenv"


You can use the following variables to control zsh-autoenv's behavior. Add them to your ~/.zshrc file, before sourcing/loading zsh-autoenv.


Name of the file to look for when entering directories.

Default: .autoenv.zsh


Name of the file to look for when leaving directories. Requires AUTOENV_HANDLE_LEAVE=1.

Default: .autoenv_leave.zsh


Look for zsh-autoenv "enter" files in parent dirs?

Default: 1


Handle leave events when changing away from a subtree, where an "enter" event was handled?

Default: 1


(Temporarily) disable zsh-autoenv. This gets looked at in the chpwd handler.

Default: 0


Enable debugging. Multiple levels are supported (max 2).

Default: 0

Related projects


This started as an optimized version of the bash plugin autoenv but for Zsh, and grew a lot of functionality on top of it (inspired by smartcd).

The code was initially based on @joshuaclayton's dotfiles. In September 2013 @Tarrasch packaged it into a nice antigen-compatible unit with integration tests. Since November 2014, @blueyed took over and added many many nice features, mainly inspired by smartcd.