From 6305114024566d371f6645aed0cf0c1ca9019c52 Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Tue, 2 Feb 2021 23:47:07 -0800
Subject: [PATCH] Document how to change the working directory in a recipe
 (#752)

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

diff --git a/README.adoc b/README.adoc
index 83d9a49..9d783c3 100644
--- a/README.adoc
+++ b/README.adoc
@@ -916,6 +916,38 @@ foo:
   echo $x
 ```
 
+=== Changing the Working Directory in a Recipe
+
+Each recipe line is executed by a new shell, so if you change the working
+directory on one line, it won't have an effect on later lines:
+
+```make
+foo:
+  pwd    # This `pwd` will print the same directory…
+  cd bar
+  pwd    # …as this `pwd`!
+```
+
+There are a couple ways around this. One is to call `cd` on the same line as
+the command you want to run:
+
+```make
+foo:
+  cd bar && pwd
+```
+
+The other is to use a shebang recipe. Shebang recipe bodies are extracted and
+run as scripts, so a single shell instance will run the whole thing, and thus a
+`pwd` on one line will affect later lines, just like a shell script:
+
+```make
+foo:
+  #!/usr/bin/env bash
+  set -euxo pipefail
+  cd bar
+  pwd
+```
+
 === Multi-line Constructs
 
 Recipes without an initial shebang are evaluated and run line-by-line, which means that multi-line constructs probably won't do what you want.