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: 3 months 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