Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Tarrasch/zsh-autoenv

Autoenv for zsh
https://github.com/Tarrasch/zsh-autoenv

autoenv zsh zshrc

Last synced: 2 days ago
JSON representation

Autoenv for zsh

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/Tarrasch/zsh-autoenv.svg?branch=master)](https://travis-ci.org/Tarrasch/zsh-autoenv)



# 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).



## Requirements



- Zsh version 4.3.10 or later.



## Features



- Support for enter and leave events, which can use the same file.

  By default it uses `.autoenv.zsh` 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/for 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

    ENTERED

    project % echo $FOO

    changed

    % cd ..

    % echo $FOO

    orig



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



### `autoenv_source_parent()`



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:



```zsh

autoenv_source_parent ../..

```



## Installation



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



    % git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv

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



### Using [antigen](https://github.com/zsh-users/antigen)



    antigen-bundle Tarrasch/zsh-autoenv



### Using [zgen](https://github.com/tarjoilija/zgen)



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



    zgen load Tarrasch/zsh-autoenv



### Using [zplug](https://github.com/zplug/zplug)



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



    zplug "Tarrasch/zsh-autoenv"



## Configuration



You can use the following variables to control zsh-autoenv's behavior.

Add them to your `~/.zshrc` file, before sourcing/loading zsh-autoenv.



### AUTOENV_FILE_ENTER



Name of the file to look for when entering directories.



Default: `.autoenv.zsh`



### AUTOENV_FILE_LEAVE



Name of the file to look for when leaving directories.

Requires `AUTOENV_HANDLE_LEAVE=1`.



Default: `.autoenv_leave.zsh`



### AUTOENV_LOOK_UPWARDS



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



Default: `1`



### AUTOENV_HANDLE_LEAVE



Handle leave events when changing away from a subtree, where an "enter"

event was handled?



Default: `1`



### AUTOENV_DISABLED



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



Default: 0



### AUTOENV_DEBUG



Set debug level. If enabled (> 0) it will print information to stderr.



- 0: no debug messages

- 1: generic debug logging

- 2: more verbose messages

  - messages about adding/removing files on the internal stack

- 3: everything

  - sets xtrace option (`set -x`) while sourcing env files



Default: `0`



## Usage



zsh-autoenv works automatically once installed.



You can use ``autoenv-edit`` to edit the nearest/current autoenv files.

It will use ``$AUTOENV_EDITOR``, ``$EDITOR``, or ``vim`` for editing.



## Helper functions



The following helper functions are available:



### autoenv_append_path



Appends path(s) to `$path` (`$PATH`), if they are not in there already.



### autoenv_prepend_path



Prepends path(s) to `$path` (`$PATH`), if they are not in there already.



### autoenv_remove_path



Removes path(s) from `$path` (`$PATH`).



Returns 0 in case `$path` has changed, 1 otherwise.



## Recipes



### Automatically activate Python virtualenvs



Given `AUTOENV_FILE_ENTER=.autoenv.zsh`, `AUTOENV_FILE_LEAVE=.autoenv.zsh` and

`AUTOENV_HANDLE_LEAVE=1` the following script will activate Python virtualenvs

automatically in all subdirectories (`.venv` directories get used by

[pipenv](https://github.com/kennethreitz/pipenv) with

`PIPENV_VENV_IN_PROJECT=1`):



```zsh

# Environment file for all projects.

#  - (de)activates Python virtualenvs (.venv) from pipenv



if [[ $autoenv_event == 'enter' ]]; then

  autoenv_source_parent



  _my_autoenv_venv_chpwd() {

    if [[ -z "$_ZSH_ACTIVATED_VIRTUALENV" && -n "$VIRTUAL_ENV" ]]; then

      return

    fi



    setopt localoptions extendedglob

    local -a venv

    venv=(./(../)#.venv(NY1:A))



    if [[ -n "$_ZSH_ACTIVATED_VIRTUALENV" && -n "$VIRTUAL_ENV" ]]; then

      if ! (( $#venv )) || [[ "$_ZSH_ACTIVATED_VIRTUALENV" != "$venv[1]" ]]; then

        unset _ZSH_ACTIVATED_VIRTUALENV

        echo "De-activating virtualenv: ${(D)VIRTUAL_ENV}" >&2



        # Simulate "deactivate", but handle $PATH better (remove VIRTUAL_ENV).

        if ! autoenv_remove_path $VIRTUAL_ENV/bin; then

          echo "warning: ${VIRTUAL_ENV}/bin not found in \$PATH" >&2

        fi



        # NOTE: does not handle PYTHONHOME/_OLD_VIRTUAL_PYTHONHOME

        unset _OLD_VIRTUAL_PYTHONHOME

        # NOTE: does not handle PS1/_OLD_VIRTUAL_PS1

        unset _OLD_VIRTUAL_PS1

        unset VIRTUAL_ENV

      fi

    fi



    if [[ -z "$VIRTUAL_ENV" ]]; then

      if (( $#venv )); then

        echo "Activating virtualenv: ${(D)venv}" >&2

        export VIRTUAL_ENV=$venv[1]

        autoenv_prepend_path $VIRTUAL_ENV/bin

        _ZSH_ACTIVATED_VIRTUALENV="$venv[1]"

      fi

    fi

  }

  autoload -U add-zsh-hook

  add-zsh-hook chpwd _my_autoenv_venv_chpwd

  _my_autoenv_venv_chpwd

else

  add-zsh-hook -d chpwd _my_autoenv_venv_chpwd

fi

```



## Related projects



- 

- 

- 



## History



This started as an optimized version of the bash plugin

[autoenv](https://github.com/kennethreitz/autoenv) but for Zsh, and grew a lot

of functionality on top of it (inspired by [smartcd]).



The code was initially based on

[@joshuaclayton](https://github.com/joshuaclayton)'s dotfiles.

In September 2013 [@Tarrasch](https://github.com/Tarrasch) packaged it into a

nice [antigen]-compatible unit with integration tests. Since November 2014,

[@blueyed](https://github.com/blueyed) took over and added many nice

features, mainly inspired by [smartcd].



[antigen]: https://github.com/Tarrasch/antigen-hs

[smartcd]: https://github.com/cxreg/smartcd