From 9149cf89856ece5f6df90672f49abcb7b3bfe8d4 Mon Sep 17 00:00:00 2001 From: Steve Purcell Date: Tue, 30 Jun 2020 08:55:11 +1200 Subject: [PATCH] README updates - Make it clearer this is a re-implementation of `use_nix` - Grammar/spelling fixes - Clarifications --- README.md | 50 ++++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index e4e1356..d2cabf3 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,18 @@ ![Test](https://github.com/nix-community/nix-direnv/workflows/Test/badge.svg) -A fast, persistent use_nix implementation for direnv. +A faster, persistent implementation of `direnv`'s `use_nix`, to replace the built-in one. + Prominent features: -- significantly faster after the first run by caching the nix-shell environment +- significantly faster after the first run by caching the `nix-shell` environment - prevents garbage collection of build dependencies by symlinking the resulting - shell derivation in the user's `gcroots` (Life is too short to loose your - build cache of your project if you are in a plane without internet connection) + shell derivation in the user's `gcroots` (Life is too short to lose + your project's build cache if you are on a flight with no internet connection) -## Installation via nix +## Installation via Nix -Since 20.03 you can install nix-direnv via nix: +Since 20.03 you can install `nix-direnv` via nix: ### NixOS @@ -32,7 +33,7 @@ In `/etc/nixos/configuration.nix`: } ``` -Then source the direnvrc from this repository in your own `.direnvrc` +Then source the `direnvrc` from this repository in your own `.direnvrc` ```bash # put this in ~/.direnvrc @@ -58,7 +59,7 @@ In `$HOME/.config/nixpkgs/home.nix` add } ``` -Optional: To protect your nix-shell against garbage collection you also need to add these options to your nix configuration +Optional: To protect your nix-shell against garbage collection you also need to add these options to your Nix configuration. If you are on NixOS also add the following lines to your `/etc/nixos/configuration.nix`: @@ -71,7 +72,7 @@ If you are on NixOS also add the following lines to your `/etc/nixos/configurati } ``` -On other systems with nix add the following configuration to your `/etc/nix/nix.conf`: +On other systems with Nix add the following configuration to your `/etc/nix/nix.conf`: ``` keep-derivations = true @@ -105,13 +106,15 @@ source $HOME/nix-direnv/direnvrc ## Storing .direnv outside the project directory -`.direnv` might interact badly with backups (i.e. Dropbox) or IDEs. -Therefore it's possible to override in `$HOME/.config/direnv/direnvrc` or -in own project's `.envrc` a variable called `$direnv_layout_dir`. +A `.direnv` directory will be created in each `use_nix` project, which might +interact badly with backups (e.g. Dropbox) or IDEs. + +Therefore it's possible to override a variable called `$direnv_layout_dir` in +`$HOME/.config/direnv/direnvrc` or in each project's `.envrc`. + The following example will create a unique directory name per project in `$HOME/.cache/direnv/layouts/`: - ```bash # $HOME/.config/direnv/direnvrc : ${XDG_CACHE_HOME:=$HOME/.cache} @@ -121,18 +124,17 @@ direnv_layout_dir=$XDG_CACHE_HOME/direnv/layouts/$pwd_hash ## Known Bugs -At the moment nix-direnv depends on gnugrep and a modern bash version. +At the moment `nix-direnv` depends on GNU Grep and a modern Bash version. This might lead to [problems](https://github.com/nix-community/nix-direnv/issues/3) on macOS. -As a work-around we suggest to install direnv/grep via nix or homebrew. +As a work-around we suggest that macOS users install `direnv`/`grep` via Nix or Homebrew. -## Why not using lorri instead? +## Why not use `lorri` instead? -Lorri causes large CPU load when `$NIXPKGS` is pointed to a directory, i.e. a -git checkout. This is because it tries to watch any referenced nix file and -re-evaluates if those changes. Nix-direnv comprises between performance and -correctness and only reevaluate direnv if either the project-specific -`default.nix` / `shell.nix` changes or if there is a new commit added to +Lorri causes large CPU load when `$NIXPKGS` is pointed to a directory, e.g. a +git checkout. This is because it tries to watch all referenced Nix files and +re-evaluate them when they change. Nix-direnv compromises between performance and +correctness, and only re-evaluates direnv if either the project-specific +`default.nix` / `shell.nix` changes, or if there is a new commit added to `nixpkgs`. A re-evaluation can be also triggered by using `touch shell.nix` in -the same project. Also `nix-direnv` does not require additional software besides -`direnv` + `nix` i.e. a daemon and the function could be included into the -project itself. +the same project. Also `nix-direnv` does not require an additional daemon, so it can be +included into the project itself and enabled without further user effort.