direnv-cache/README.md

# direnv-cache

## Setup

direnv-cache consists of two components: the direnv-cache script and an
extension to direnv's stdlib.

To set up direnv-cache, make direnv read the provided direnvrc, eg. via

    cp direnvrc ~/.config/direnv/direnvrc

and install direnv-cache somewhere in your PATH.

If you use home-manager, you can add the following to your configuration

    ...
    let
        direnv-cache = pkgs.callPackage ./path/to/this/repo {};
    in
    ...

    home.packages = [ ... direnv-cache ... ];
    programs.direnv = {
        enable = true;
        enableBashIntegration = true;
        stdlib = builtins.readFile direnv-cache.direnvrc;
    };
    ...

## Usage

The following assumes a working direnv setup.

Use the cache function in your `.envrc` files, eg.

    cache <<EOF
      # everything in here will be cached
      use nix -p hello
    EOF

    # you can also have stuff outside the cached region
    export PATH=/some/other/path:$PATH

If you now enter the directory, direnv will tell you that the environment
is not yet cached. We can fix that by running `direnv-cache reload`. This
will also tell direnv to reload. From now on, if you enter the directory,
direnv will load the cached environment.

Re-run `direnv-cache reload` whenever your `.envrc` or other dependencies change
to update the cache.

## How it works

Everything piped into the `cache` function is stored in a recipe file in
direnv-cache's cache directory when the `.envrc` is evaluated. Then, if the
environment cache exists, it is sourced.

When `direnv-cache reload` is called, it looks for a recipe file for the
current directory, and runs it. A diff of the environments before and after the
recipe is run is written to the directory-specific cache file.