From 45c4ed5af1638d25ac84b84e4d06b3a05c2eb183 Mon Sep 17 00:00:00 2001
From: Nicolas Mattia <nicolas@nmattia.com>
Date: Thu, 13 Aug 2020 15:35:18 +0200
Subject: [PATCH] Document NIV_OVERRIDE and add FAQ TOC

---
 README.md     | 23 +++++++++++++++++++++--
 README.tpl.md | 23 +++++++++++++++++++++--
 2 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 819496b..525417e 100644
--- a/README.md
+++ b/README.md
@@ -383,7 +383,12 @@ Available options:
 
 ## Frequently Asked Questions
 
-### Can you use private GitHub repositories?
+* [Can I use private GitHub repositories?](#can-i-use-private-github-repositories)
+* [How do I import a subpath of a source?](#how-do-i-import-a-subpath-of-a-source)
+* [How do I import NixOS modules](#how-do-i-import-nixos-modules)
+* [Can I use local packages?](#can-i-use-local-packages)
+
+### Can I use private GitHub repositories?
 
 Yes. There are two ways:
 
@@ -431,7 +436,7 @@ in sources.my-package + "/dir"
 in this example, `sources.my-package` becomes `my-package`'s root directory, and `+ "/dir"` appends the
 subdirectory.
 
-### How can I import NixOS modules?
+### How do I import NixOS modules?
 
 After the package containing the modules has been `niv add`ed, importing the
 modules is straightforward:
@@ -443,3 +448,17 @@ in {
   imports = [ (sources.package + "/path/to/module") ];
 }
 ```
+
+### Can I use local packages?
+
+If you need to use a local path as a source -- especially convenient when
+modifying dependencies -- `niv` allows you to override the `sources.json` via
+environment variables. To override a source `foo` with a local path
+`./bar/baz`, set the environment variable `NIV_OVERRIDE_foo` to `./bar/baz`.
+
+Generally, if the environment variable `NIV_OVERRIDE_<name>` is set _and_ you
+have a source named `<name>` then `niv` will use the value of
+`NIV_OVERRIDE_<name>` as the `outPath` of that source. All non-alphanumeric
+characters in the source name are escaped to the character `_`; i.e. to
+override the package `my package-foo` you need to set the environment variable
+`NIV_OVERRIDE_my_package_foo`.
diff --git a/README.tpl.md b/README.tpl.md
index 4b02db4..8651764 100644
--- a/README.tpl.md
+++ b/README.tpl.md
@@ -260,7 +260,12 @@ replace_niv_show_help
 
 ## Frequently Asked Questions
 
-### Can you use private GitHub repositories?
+* [Can I use private GitHub repositories?](#can-i-use-private-github-repositories)
+* [How do I import a subpath of a source?](#how-do-i-import-a-subpath-of-a-source)
+* [How do I import NixOS modules](#how-do-i-import-nixos-modules)
+* [Can I use local packages?](#can-i-use-local-packages)
+
+### Can I use private GitHub repositories?
 
 Yes. There are two ways:
 
@@ -308,7 +313,7 @@ in sources.my-package + "/dir"
 in this example, `sources.my-package` becomes `my-package`'s root directory, and `+ "/dir"` appends the
 subdirectory.
 
-### How can I import NixOS modules?
+### How do I import NixOS modules?
 
 After the package containing the modules has been `niv add`ed, importing the
 modules is straightforward:
@@ -320,3 +325,17 @@ in {
   imports = [ (sources.package + "/path/to/module") ];
 }
 ```
+
+### Can I use local packages?
+
+If you need to use a local path as a source -- especially convenient when
+modifying dependencies -- `niv` allows you to override the `sources.json` via
+environment variables. To override a source `foo` with a local path
+`./bar/baz`, set the environment variable `NIV_OVERRIDE_foo` to `./bar/baz`.
+
+Generally, if the environment variable `NIV_OVERRIDE_<name>` is set _and_ you
+have a source named `<name>` then `niv` will use the value of
+`NIV_OVERRIDE_<name>` as the `outPath` of that source. All non-alphanumeric
+characters in the source name are escaped to the character `_`; i.e. to
+override the package `my package-foo` you need to set the environment variable
+`NIV_OVERRIDE_my_package_foo`.