Merge pull request #27 from blueyed/add-doc
Huge update of the README (finally)
This commit is contained in:
Arash Rouhani
commit
928a945e99
119
README.md
119
README.md
|
|
@ -2,19 +2,70 @@
|
|||
|
||||
[](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
|
||||
|
||||
git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
|
||||
echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
|
||||
You can use the following variables to control zsh-autoenv's behavior.
|
||||
Add them to your `~/.zshrc` file, before sourcing/loading zsh-autoenv.
|
||||
|
||||
## Credits
|
||||
### AUTOENV\_FILE\_ENTER
|
||||
Name of the file to look for when entering directories.
|
||||
|
||||
The code was mostly copied from [Joshua Clayton](https://github.com/joshuaclayton)
|
||||
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
|
||||
|
||||
|
||||
## History
|
||||
|
||||
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 initially based on [Joshua Clayton](https://github.com/joshuaclayton)'s work.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue