From bcbb562397fdfd8a14f1791a6f412d12d43eb5b6 Mon Sep 17 00:00:00 2001
From: Gene Pasquet <dev@etenil.net>
Date: Thu, 5 Dec 2024 23:34:13 +0000
Subject: Improvements, documentation etc.

---
 README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 0723c86..6d25661 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,69 @@
 DEEPENV
 =======
 
-Deepenv is a tool to run programs with their environment variables populated from all detected parent .env files merged together.
+Deepenv is a tool to run programs with their environment variables
+populated from all detected parent .env files merged together.
+
+## Installing
+
+Deepenv is written in Chicken scheme. In order to install it, you will
+need to first install Chicken, and compile deepenv.
+
+On Linux, use your package manager to install Chicken like so:
+
+```
+sudo apt install chicken-bin
+```
+
+On MacOS, install Chicken with Homebrew:
+
+```
+brew install chicken
+```
+
+Then compile and install Chicken like so:
+
+```
+make
+make install
+```
+
+### Overrides
+
+The following can be overriden by environment or make variables:
+
+- `CSC` the chicken compiler command. Usually `csc`, sometimes `chicken-csc`.
+- `PREFIX` file-system prefix where the executables will be installed. Defaults to `/usr/local`.
+
+## Usage
+
+To use deepenv, simply `cd` to the place where you want to run a
+program, and run with:
+
+```
+deepenv <program> [arguments]
+```
+
+If a `.env` file exists in this folder or any parent folder, they will
+be loaded as environment variables when `program` runs.
+
+## Environment merging strategy
+
+All `.env` files encountered from the current working directory, all
+the way to the filesystem root are loaded and merged together, with
+environment variables defined deeper in the tree shadowing their
+parent definitions. The very top level is the existing environment
+variables.
+
+For example, given the following file structure:
+
+```
+/
+/.env
++- /foo
+   +- .env
+```
+
+Assuming `/.env` defines `FOO=123` and `/foo/.env` defines `FOO=456`,
+running `deepenv <program>` in `/foo` will result in `FOO` being set
+to `456`.
-- 
cgit v1.2.3