README.md

   1 [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/Tarrasch/zsh-autoenv/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
   2
   3 [![Build Status](https://travis-ci.org/Tarrasch/zsh-autoenv.svg?branch=master)](https://travis-ci.org/Tarrasch/zsh-autoenv)
   4
   5 # Autoenv for Zsh
   6
   7 zsh-autoenv automatically sources (known/whitelisted) `.env` files, typically
   8 used in project root directories.
   9
  10 It handles "enter" and leave" events, nesting, and stashing of
  11 variables (overwriting and restoring).
  12
  13 ## Features
  14
  15  - Support for enter and leave events, which can use the same file.
  16    By default `.env` is used for entering, and `.env_leave` for leaving.
  17  - Interactively asks for confirmation / authentication before sourcing an
  18    unknown `.env` file, and remembers whitelisted files by their hashed
  19    content.
  20  - Test suite.
  21  - Written in Zsh.
  22
  23 ### Variable stashing
  24
  25 You can use `autostash` in your `.env` files to overwrite some variable, e.g.
  26 `$PATH`.  When leaving the directory, it will be automatically restored.
  27
  28     % echo 'echo ENTERED; autostash FOO=changed' > project/.env
  29     % FOO=orig
  30     % cd project
  31     Attempting to load unauthorized env file!
  32     -rw-rw-r-- 1 user user 36 Mai  6 20:38 /tmp/project/.env
  33
  34     **********************************************
  35
  36     echo ENTERED; autostash FOO=changed
  37
  38     **********************************************
  39
  40     Would you like to authorize it? (type 'yes') yes
  41     ENTERED
  42     project % echo $FOO
  43     changed
  44     % cd ..
  45     % echo $FOO
  46     orig
  47
  48 There is also `stash`, `unstash` and `autounstash`, in case you want to
  49 have more control.
  50
  51 The varstash library has been taken from smartcd, and was optimized for Zsh.
  52
  53
  54 ## Writing your .env file
  55
  56 ### `autoenv_source_parent()`
  57
  58 zsh-autoenv will stop looking for `.env` files after the first one has been
  59 found.  But you can use the function `autoenv_source_parent` to source a
  60 parent `.env` file from there.
  61
  62
  63 ## Installation
  64
  65 Clone the repository and source it from your `~/.zshrc` file:
  66
  67     % git clone https://github.com/Tarrasch/zsh-autoenv ~/.dotfiles/lib/zsh-autoenv
  68     % echo 'source ~/.dotfiles/lib/zsh-autoenv/autoenv.zsh' >> ~/.zshrc
  69
  70 ### Using [antigen](https://github.com/zsh-users/antigen)
  71
  72     antigen-bundle Tarrasch/zsh-autoenv
  73
  74 ### Using [zgen](https://github.com/tarjoilija/zgen)
  75
  76 Add the following to your `.zshrc` where you are loading your plugins:
  77
  78     zgen load Tarrasch/zsh-autoenv
  79
  80
  81 ## Configuration
  82
  83 You can use the following variables to control zsh-autoenv's behavior.
  84 Add them to your `~/.zshrc` file, before sourcing/loading zsh-autoenv.
  85
  86 ### AUTOENV\_FILE\_ENTER
  87 Name of the file to look for when entering directories.
  88
  89 Default: `.env`
  90
  91 ### AUTOENV\_FILE\_LEAVE
  92 Name of the file to look for when leaving directories.
  93 Requires `AUTOENV_HANDLE_LEAVE=1`.
  94
  95 Default: `.env_leave`
  96
  97 ### AUTOENV\_LOOK\_UPWARDS
  98 Look for .env files in parent dirs?
  99
 100 Default: `1`
 101
 102 ### AUTOENV\_HANDLE\_LEAVE
 103 Handle leave events when changing away from a subtree, where an "enter"
 104 event was handled?
 105
 106 Default: `1`
 107
 108 ### AUTOENV\_DISABLED
 109 (Temporarily) disable zsh-autoenv. This gets looked at in the chpwd handler.
 110
 111 Default: 0
 112
 113 ### `AUTOENV_DEBUG`
 114 Enable debugging. Multiple levels are supported (max 2).
 115
 116 Default: `0`
 117
 118
 119 ## Related projects
 120 - https://github.com/cxreg/smartcd
 121 - https://github.com/kennethreitz/autoenv
 122
 123
 124 ## History
 125
 126 This started as an optimized version of the bash plugin
 127 [autoenv](https://github.com/kennethreitz/autoenv) but for Zsh, and grew a lot
 128 of functionality on top of it (inspired by [smartcd]).
 129
 130 The code was initially based on
 131 [@joshuaclayton](https://github.com/joshuaclayton)'s dotfiles.
 132 In September 2013 [@Tarrasch](https://github.com/Tarrasch) packaged it into a
 133 nice [antigen]-compatible unit with integration tests. Since November 2014,
 134 [@blueyed](https://github.com/blueyed) took over and added many many nice
 135 features, mainly inspired by [smartcd].
 136
 137 [antigen]: https://github.com/Tarrasch/antigen-hs
 138 [smartcd]: https://github.com/cxreg/smartcd