From 9f82ed901566bc8b88beccfcd38f83c088166c97 Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Tue, 12 Nov 2019 13:34:00 -0800
Subject: [PATCH] Document settings in readme (#527)

---
 README.adoc | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.adoc b/README.adoc
index e7e251086c..01ef2f0509 100644
--- a/README.adoc
+++ b/README.adoc
@@ -233,6 +233,45 @@ echo 'Building!'
 Building!
 ```
 
+=== Settings
+
+Settings control interpetation and execution. Each setting may be specified at most once, anywhere in the justfile.
+
+For example:
+
+```make
+
+set shell := ["zsh", "-cu"]
+
+foo:
+  # this line will be run as `zsh -cu 'ls **/*.txt'`
+  ls **/*.txt
+```
+
+==== Table of Settings
+
+[options="header"]
+|=================
+| Name | Value | Description
+|`shell` | `[COMMAND, ARGS...]` | Set the command used to invoke recipes and evaluate backticks.
+|=================
+
+==== Shell
+
+The `shell` setting controls the command used to invoke recipe lines and backticks. Shebang recipes are unaffected.
+
+```make
+# use python3 to execute recipe lines and backticks
+set shell := ["python3", "-c"]
+
+# use print to capture result of evaluation
+foos := `print("foo" * 4)`
+
+foo:
+  print("Snake snake snake snake.")
+  print("{{foos}}")
+```
+
 === Documentation Comments
 
 Comments immediately preceding a recipe will appear in `just --list`: