1 files changed, 47 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..f50f0b2
--- /dev/null
+++ b/README
@@ -0,0 +1,47 @@
+Bootstrap secrets management in a project.
+
+Problem: Secrets (e.g., passowrds, API keys) get accidentaly commited and are
+leaked when a repository becomes public.
+
+Solution:
+
+secrets.sh.example  defines variable names
+secrets.sh          defines secret values
+run.sh              sources secrets
+.gitignore          exclude secrets.sh
+
+Rationale
+=========
+
+People are lazy.  The less steps the better.  So, `run.sh` should create
+`secrets.sh` out of `secrets.sh.example`, and nd tell the user to modify it.
+
+This flow is simple and portable.  No unreliable dependencies like:
+
+https://pypi.org/project/python-dotenv/  for the people that cannot use os.environ
+https://www.npmjs.com/package/dotenv
+
+People often use these tools because they don't know shell scripting.  Here's a
+quick reminder
+
+```sh
+foo=somevalue
+./run           # does not receive foo
+foo=anothervalue ./run    # passes foo only for ./run
+export foo      # mark variable for automatic export
+export -n foo   # remove export mark
+unset foo       # delete variable, alongside any marks
+
+set | grep foo    # check local variables
+env | grep foo    # check variables marked for automatic export to the environment of subsequently executed commands
+
+
+# shell built-ins
+help export
+help unset
+
+# external programs
+man env
+
+# Shell built-ins take precedence over any external program with the same name.
+```