Huge update of the README (finally)

diff --git a/README.md b/README.md
index bd2d295ccafdb471d2596e01b6e99e2675c4daeb..0682bdb2e6a8b330c1b4750f463ca34967d29b79 100644 (file)
--- a/README.md
+++ b/README.md
@@ -2,19 +2,70 @@
 
 [![Build Status](https://travis-ci.org/Tarrasch/zsh-autoenv.svg?branch=master)](https://travis-ci.org/Tarrasch/zsh-autoenv)
 
-# Autoenv for zsh
+# Autoenv for Zsh
 
-This is is a zsh optimized version of
-[autoenv](https://github.com/kennethreitz/autoenv)
+zsh-autoenv automatically sources `.env` files, typically used in project
+root directories.
 
-## Why a zsh version
+It handles "enter" and leave" events, nesting, and stashing of
+variables (overwriting and restoring).
+
+## Features
+
+ - Support for enter and leave events, which can use the same file.
+   By default `.env` is used for entering, and `.env_leave` for leaving.
+ - Asks for confirmation / authentication before sourcing a `.env` file, and
+   remembers whitelisted files by its hash.
+ - Test suite.
+ - Written in Zsh.
+
+### Variable stashing
+
+You can use `autostash` in your `.env` files to overwrite some variable, e.g.
+`$PATH`.  When leaving the directory, it will be automatically restored.
+
+    % echo 'echo ENTERED; autostash FOO=changed' > project/.env
+    % FOO=orig
+    % cd project
+    Attempting to load unauthorized env file!
+    -rw-rw-r-- 1 user user 36 Mai  6 20:38 /tmp/project/.env
+
+    **********************************************
+
+    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 .env file
+
+### `autoenv_source_parent()`
+
+zsh-autoenv will stop looking for `.env` files after the first one has been
+found.  But you can use the function `autoenv_source_parent` to source a
+parent `.env` file from there.
 
-  * Auto-completion will work rather than vomit
-  * No stupid error messages
-  * It's elegant to use the built in `chpwd_functions`
 
 ## 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
@@ -25,13 +76,55 @@ Add the following to your `.zshrc` where you are loading your plugins:
 
     zgen load Tarrasch/zsh-autoenv
 
-### Manually
 
-Clone the repository and source it from your `~/.zshrc` file:
+## 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: `.env`
+
+### AUTOENV\_FILE\_LEAVE
+Name of the file to look for when leaving directories.
+Requires `AUTOENV_HANDLE_LEAVE=1`.
+
+Default: `.env_leave`
+
+### AUTOENV\_LOOK\_UPWARDS
+Look for .env 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`
+Enable debugging. Multiple levels are supported (max 2).
+
+Default: `0`
+
+
+## Related projects
+- https://github.com/cxreg/smartcd
+- https://github.com/kennethreitz/autoenv
+
 
-    git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
-    echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
+## History
 
-## Credits
+This started as a optimized version of
+[autoenv](https://github.com/kennethreitz/autoenv) for Zsh, but grew a lot of
+functionality on top of it (inspired by
+[smartcd](https://github.com/cxreg/smartcd)).
 
-The code was mostly copied from [Joshua Clayton](https://github.com/joshuaclayton)
+The code was initially based on [Joshua Clayton](https://github.com/joshuaclayton)'s work.

diff --git a/autoenv.zsh b/autoenv.zsh
index d3f0f2efb9c19f74d573f558214a31473f4d76a6..1debfefe203e604c4b9ab49e6a3eefcc68b860bb 100644 (file)
--- a/autoenv.zsh
+++ b/autoenv.zsh
@@ -4,14 +4,14 @@
 # File to store confirmed authentication into.
 : ${AUTOENV_ENV_FILENAME:=~/.env_auth}
 
-# Name of file to look for when entering directories.
+# Name of the file to look for when entering directories.
 : ${AUTOENV_FILE_ENTER:=.env}
 
-# Name of file to look for when leaving directories.
+# Name of the file to look for when leaving directories.
 # Requires AUTOENV_HANDLE_LEAVE=1.
 : ${AUTOENV_FILE_LEAVE:=.env.leave}
 
-# Look for .env in parent dirs?
+# Look for .env files in parent dirs?
 : ${AUTOENV_LOOK_UPWARDS:=1}
 
 # Handle leave events when changing away from a subtree, where an "enter"