forked from direnv/direnv
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
site: use jekyll to render the website
* improve the README * backtick .envrc * better docs TOC * remove broken screencasts * move LICENSE around * improve the man pages
- Loading branch information
Showing
17 changed files
with
441 additions
and
523 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,254 +1,161 @@ | ||
| direnv -- Unclutter your .profile | ||
| direnv -- unclutter your .profile | ||
| ================================= | ||
|
|
||
| [](https://builtwithnix.org) | ||
| [](https://dev.azure.com/direnv/direnv/_build/latest?definitionId=1&branchName=master) | ||
| `direnv` is an environment switcher for the shell. It knows how to hook into | ||
| bash, zsh, tcsh, fish shell and elvish to load or unload environment variables | ||
| depending on the current directory. This allows project-specific | ||
| environment variables without cluttering the `~/.profile` file. | ||
| [](https://repology.org/project/direnv/versions) | ||
| [](https://repology.org/project/direnv/versions) | ||
|
|
||
| Before each prompt, direnv checks for the existence of a ".envrc" file in the | ||
| current and parent directories. If the file exists (and is authorized), it is | ||
| loaded into a **bash** sub-shell and all exported variables are then captured by | ||
| direnv and then made available to the current shell. | ||
|
|
||
| Because direnv is compiled into a single static executable, it is fast enough | ||
| to be unnoticeable on each prompt. It is also language-agnostic and can be | ||
| used to build solutions similar to rbenv, pyenv and phpenv. | ||
|
|
||
|
|
||
| ## Example | ||
|
|
||
| ```sh | ||
| $ cd ~/my_project | ||
| $ echo ${FOO-nope} | ||
| nope | ||
| $ echo export FOO=foo > .envrc | ||
| .envrc is not allowed | ||
| $ direnv allow . | ||
| direnv: reloading | ||
| direnv: loading .envrc | ||
| direnv export: +FOO | ||
| $ echo ${FOO-nope} | ||
| foo | ||
| $ cd .. | ||
| direnv: unloading | ||
| direnv export: ~PATH | ||
| $ echo ${FOO-nope} | ||
| nope | ||
| ``` | ||
| `direnv` is an extension for your shell. It augments existing shells with a | ||
| new feature that can load and unload environment variables depending on the | ||
| current directory. | ||
|
|
||
| ## Install | ||
| ## Use cases | ||
|
|
||
| ### From system packages | ||
| * Load 12factor apps environment variables | ||
| * Create per-project isolated development environments | ||
| * Load secrets for deployment | ||
|
|
||
| direnv is packaged for a variety of systems: | ||
| ## How it works | ||
|
|
||
| * [Fedora](https://apps.fedoraproject.org/packages/direnv) | ||
| * [Arch AUR](https://aur.archlinux.org/packages/direnv/) | ||
| * [Debian](https://packages.debian.org/search?keywords=direnv&searchon=names&suite=all§ion=all) | ||
| * [Gentoo go-overlay](https://github.com/Dr-Terrible/go-overlay) | ||
| * [NetBSD pkgsrc-wip](http://www.pkgsrc.org/wip/) | ||
| * [NixOS](https://nixos.org/nixos/packages.html#direnv) | ||
| * [OSX Homebrew](http://brew.sh/) | ||
| * [openSUSE](https://build.opensuse.org/package/show/openSUSE%3AFactory/direnv) | ||
| * [MacPorts](https://www.macports.org/) | ||
| * [Ubuntu](https://packages.ubuntu.com/search?keywords=direnv&searchon=names&suite=all§ion=all) | ||
| * [GNU Guix](https://www.gnu.org/software/guix/) | ||
| * [Snap](https://snapcraft.io/direnv) | ||
|
|
||
| See also: | ||
|
|
||
| [](https://repology.org/metapackage/direnv) | ||
|
|
||
| ### From binary builds | ||
|
|
||
| Binary builds for a variety of architectures are also available for | ||
| [each release](https://github.com/direnv/direnv/releases). | ||
|
|
||
| Fetch the binary, `chmod +x direnv` and put it somewhere in your PATH. | ||
|
|
||
| ### Compile from source | ||
|
|
||
| Setup go environment https://golang.org/doc/install | ||
|
|
||
| > go >= 1.9 is required | ||
| Clone project: | ||
|
|
||
| $ git clone [email protected]:direnv/direnv.git | ||
|
|
||
| Build by just typing make: | ||
|
|
||
| $ cd direnv | ||
| $ make | ||
|
|
||
| To install to /usr/local: | ||
|
|
||
| $ make install | ||
|
|
||
| Or to a different location like `~/.local`: | ||
| Before each prompt, direnv checks for the existence of a `.envrc` file in the | ||
| current and parent directories. If the file exists (and is authorized), it is | ||
| loaded into a **bash** sub-shell and all exported variables are then captured | ||
| by direnv and then made available to the current shell. | ||
|
|
||
| $ make install DESTDIR=~/.local | ||
| It supports hooks for all the common shells like bash, zsh, tcsh and fish. | ||
| This allows project-specific environment variables without cluttering the | ||
| `~/.profile` file. | ||
|
|
||
| Because direnv is compiled into a single static executable, it is fast enough | ||
| to be unnoticeable on each prompt. It is also language-agnostic and can be | ||
| used to build solutions similar to rbenv, pyenv and phpenv. | ||
|
|
||
| ## Setup | ||
| ## Getting Started | ||
|
|
||
| For direnv to work properly it needs to be hooked into the shell. Each shell | ||
| has its own extension mechanism: | ||
| ### Prerequisites | ||
|
|
||
| ### BASH | ||
| * Unix-like operating system (macOS, Linux, ...) | ||
| * A supported shell (bash, zsh, tcsh, fish, elvish) | ||
|
|
||
| Add the following line at the end of the `~/.bashrc` file: | ||
| ### Basic Installation | ||
|
|
||
| ```sh | ||
| eval "$(direnv hook bash)" | ||
| ``` | ||
| 1. direnv is packaged in most distributions already. See [the installation documentation](docs/installation.md) for details. | ||
| 2. [hook direnv into your shell](docs/hook.md). | ||
|
|
||
| Make sure it appears even after rvm, git-prompt and other shell extensions | ||
| that manipulate the prompt. | ||
| Now restart your shell. | ||
|
|
||
| ### ZSH | ||
| ### Quick demo | ||
|
|
||
| Add the following line at the end of the `~/.zshrc` file: | ||
| To follow along in your shell once direnv is installed. | ||
|
|
||
| ```sh | ||
| eval "$(direnv hook zsh)" | ||
| ``` | ||
| # Create a new folder for demo purposes. | ||
| $ mkdir ~/my-project | ||
| $ cd ~/my-project | ||
| ### FISH | ||
|
|
||
| Add the following line at the end of the `~/.config/fish/config.fish` file: | ||
|
|
||
| ```fish | ||
| direnv hook fish | source | ||
| ``` | ||
|
|
||
| ### TCSH | ||
|
|
||
| Add the following line at the end of the `~/.cshrc` file: | ||
|
|
||
| ```sh | ||
| eval `direnv hook tcsh` | ||
| ``` | ||
| # Show that the FOO environment variable is not loaded. | ||
| $ echo ${FOO-nope} | ||
| nope | ||
| ### Elvish (0.12+) | ||
| # Create a new .envrc. This file is bash code that is going to be loaded by | ||
| # direnv. | ||
| $ echo export FOO=foo > .envrc | ||
| .envrc is not allowed | ||
| Run: | ||
| # The security mechanism didn't allow to load the .envrc. Since we trust it, | ||
| # let's allow it's execution. | ||
| $ direnv allow . | ||
| direnv: reloading | ||
| direnv: loading .envrc | ||
| direnv export: +FOO | ||
| ``` | ||
| $> direnv hook elvish > ~/.elvish/lib/direnv.elv | ||
| ``` | ||
| # Show that the FOO environment variable is loaded. | ||
| $ echo ${FOO-nope} | ||
| foo | ||
| and add the following line to your `~/.elvish/rc.elv` file: | ||
| # Exit the project | ||
| $ cd .. | ||
| direnv: unloading | ||
| ``` | ||
| use direnv | ||
| # And now FOO is unset again | ||
| $ echo ${FOO-nope} | ||
| nope | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| In some target folder, create a ".envrc" file and add some export(1) | ||
| directives in it. | ||
|
|
||
| Note that the contents of the `.envrc` file must be valid bash syntax, | ||
| regardless of the shell you are using. | ||
| This is because direnv always executes the `.envrc` with bash (a sort of | ||
| lowest common denominator of UNIX shells) so that direnv can work across shells. | ||
| If you try to use some syntax that doesn't work in bash (like zsh's | ||
| nested expansions), you will [run into | ||
| trouble](https://github.com/direnv/direnv/issues/199). | ||
|
|
||
| On the next prompt you will notice that direnv complains about the ".envrc" | ||
| being blocked. This is the security mechanism to avoid loading new files | ||
| automatically. Otherwise any git repo that you pull, or tar archive that you | ||
| unpack, would be able to wipe your hard drive once you `cd` into it. | ||
|
|
||
| So here we are pretty sure that it won't do anything bad. Type `direnv allow .` | ||
| and watch direnv loading your new environment. Note that `direnv edit .` is a | ||
| handy shortcut that opens the file in your $EDITOR and automatically allows it | ||
| if the file's modification time has changed. | ||
|
|
||
| Now that the environment is loaded, you will notice that once you `cd` out | ||
| of the directory it automatically gets unloaded. If you `cd` back into it, it's | ||
| loaded again. That's the basis of the mechanism that allows you to build cool | ||
| things. | ||
|
|
||
| ### The stdlib | ||
|
|
||
| Exporting variables by hand is a bit repetitive so direnv provides a set of | ||
| utility functions that are made available in the context of the ".envrc" file. | ||
| utility functions that are made available in the context of the `.envrc` file. | ||
|
|
||
| As an example, the `PATH_add` function is used to expand and prepend a path to | ||
| the $PATH environment variable. Instead of `export $PATH=$PWD/bin:$PATH` you | ||
| can write `PATH_add bin`. It's shorter and avoids a common mistake where | ||
| `$PATH=bin`. | ||
|
|
||
| To find the documentation for all available functions check the | ||
| direnv-stdlib(1) man page. | ||
| [direnv-stdlib(1) man page](man/direnv-stdlib.1.md). | ||
|
|
||
| It's also possible to create your own extensions by creating a bash file at | ||
| `~/.config/direnv/direnvrc` or `~/.direnvrc`. This file is loaded before your | ||
| ".envrc" and thus allows you to make your own extensions to direnv. | ||
| `.envrc` and thus allows you to make your own extensions to direnv. | ||
|
|
||
| #### Loading layered .envrc | ||
| ## Docs | ||
|
|
||
| NOTE: the authorization framework doesn't apply here and all the `.envrc` will | ||
| be loaded without verification | ||
| * [Install direnv](docs/installation.md) | ||
| * [Hook into your shell](docs/hook.md) | ||
| * [Develop for direnv](docs/development.md) | ||
| * [Manage your rubies with direnv and ruby-install](docs/ruby.md) | ||
| * [Community Wiki](https://github.com/direnv/direnv/wiki) | ||
|
|
||
| Let's say you have the following structure: | ||
| Make sure to take a look at the wiki! It contains all sorts of useful | ||
| information such as common recipes, editor integration, tips-and-tricks. | ||
|
|
||
| - "/a/.envrc" | ||
| - "/a/b/.envrc" | ||
| ### Man pages | ||
|
|
||
| If you add the following line in "/a/b/.envrc", you can load both of the | ||
| ".envrc" files when you are in `/a/b`: | ||
| * [direnv(1) man page](man/direnv.1.md) | ||
| * [direnv-stdlib(1) man page](man/direnv-stdlib.1.md) | ||
| * [direnv.toml(1) man page](man/direnv.toml.1.md) | ||
|
|
||
| ```sh | ||
| source_env .. | ||
| ``` | ||
| In the general case `source_up` will load any .envrc higher up in the folder structure. This allows you to truly enable arbitrary hierarchical stuctures of `.envrc` usage. | ||
| ### FAQ | ||
|
|
||
| ```sh | ||
| source_up | ||
| ``` | ||
| Based on GitHub issues interactions, here are the top things that have been | ||
| confusing for users: | ||
|
|
||
| 1. direnv has a standard library of functions, a collection of utilities that | ||
| I found useful to have and accumulated over the years. You can find it | ||
| here: https://github.com/direnv/direnv/blob/master/stdlib.sh | ||
|
|
||
| ## Common things people don't know | ||
| 2. It's possible to override the stdlib with your own set of function by | ||
| adding a bash file to `~/.config/direnv/direnvrc`. This file is loaded and | ||
| it's content made available to any `.envrc` file. | ||
|
|
||
| Based on GitHub issues interactions, here are the top things that have been confusing for users: | ||
| 3. direnv is not loading the `.envrc` into the current shell. It's creating a | ||
| new bash sub-process to load the stdlib, direnvrc and `.envrc`, and only | ||
| exports the environment diff back to the original shell. This allows direnv | ||
| to record the environment changes accurately and also work with all sorts | ||
| of shells. It also means that aliases and functions are not exportable | ||
| right now. | ||
|
|
||
| 1. direnv has a standard library of functions, a collection of utilities that I found useful to have and accumulated over the years. If you know how to read bash, you can find it here: https://github.com/direnv/direnv/blob/master/stdlib.sh | ||
| ## Contributing | ||
|
|
||
| 2. It's possible to override the stdlib with your own set of function by adding a bash file to either `~/.config/direnv/direnvrc` or `~/.direnvrc`. These will become available to all your `.envrc` files. | ||
| Bug reports, contributions and forks are welcome. All bugs or other forms of | ||
| discussion happen on http://github.com/direnv/direnv/issues . | ||
|
|
||
| 3. direnv is actually creating a new bash process to load the stdlib, direnvrc and `.envrc`, and only exports the environment diff back to the original shell. This allows direnv to record the environment changes accurately and also work with all sorts of shells. It also means that aliases and functions are not exportable right now. | ||
| Or drop by on [IRC (#direnv on freenode)](irc://irc.freenode.net/#direnv) to | ||
| have a chat. If you ask a question make sure to stay around as not everyone is | ||
| active all day. | ||
|
|
||
| ## Similar projects | ||
|
|
||
| Here is a list of other projects found in the same design space. Feel free to | ||
| submit new ones. | ||
|
|
||
| * [Environment Modules](http://modules.sourceforge.net/) - one of the oldest (in a good way) environment-loading systems | ||
| * [autoenv](https://github.com/kennethreitz/autoenv) - lightweight; doesn't support unloads | ||
| * [zsh-autoenv](https://github.com/Tarrasch/zsh-autoenv) - a feature-rich mixture of autoenv and [smartcd](https://github.com/cxreg/smartcd): enter/leave events, nesting, stashing (Zsh-only). | ||
| * [asdf](https://github.com/asdf-vm/asdf) - a pure bash solution that has a plugin system | ||
|
|
||
| ## Contribute | ||
|
|
||
| Bug reports, contributions and forks are welcome. | ||
|
|
||
| All bugs or other forms of discussion happen on | ||
| <http://github.com/direnv/direnv/issues>. | ||
|
|
||
| There is a wiki available where you can share your usage patterns or | ||
| other tips and tricks <https://github.com/direnv/direnv/wiki> | ||
|
|
||
| For longer form discussions you can also write to <mailto:[email protected]> | ||
|
|
||
| Or drop by on [IRC (#direnv on freenode)](irc://irc.freenode.net/#direnv) to | ||
| have a chat. If you ask a question make sure to stay around as not everyone is | ||
| active all day. | ||
|
|
||
| ## COPYRIGHT | ||
|
|
||
| Copyright (C) 2014 shared by all | ||
| [contributors](https://github.com/direnv/direnv/graphs/contributors) under | ||
| the MIT licence. | ||
| [MIT licence](LICENSE) - Copyright (C) 2019 @zimbatm and [contributors](https://github.com/direnv/direnv/graphs/contributors) |
Oops, something went wrong.