From 5d223b113ec9253e6edbed6df71ddf6d53f020f3 Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Mon, 13 Jun 2022 19:05:40 -0700
Subject: [PATCH] Add argument splitting section to readme (#1230)

---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/README.md b/README.md
index 9ff4b2d..3d55eec 100644
--- a/README.md
+++ b/README.md
@@ -1936,6 +1936,69 @@ echo bar
 bar
 ```
 
+### Avoiding Argument Splitting
+
+Given this `justfile`:
+
+```make
+foo argument:
+  touch {{argument}}
+```
+
+The following command will create two files, `some` and `argument.txt`:
+
+```sh
+$ just foo "some argument.txt"
+```
+
+The users shell will parse `"some argument.txt`" as a single argument, but when `just` replaces `touch {{argument}}` with `touch some argument.txt`, the quotes are not preserved, and `touch` will receive two arguments.
+
+There are a few ways to avoid this: quoting, positional arguments, and exported arguments.
+
+#### Quoting
+
+Quotes can be added around the `{{argument}}` interpolation:
+
+```make
+foo argument:
+  touch '{{argument}}'
+```
+
+This preserves `just`'s ability to catch variable name typos before running, for example if you were to write `{{argumant}}`, but will not do what you want if the value of `argument` contains single quotes.
+
+#### Positional Arguments
+
+The `positional-arguments` setting causes all arguments to be passed as positional arguments, allowing them to be accessed with `$1`, `$2`, …, and `$@`, which can be then double-quoted to avoid further splitting by the shell:
+
+```make
+set positional-arguments
+
+foo argument:
+  touch "$1"
+```
+
+This defeats `just`'s ability to catch typos, for example if you type `$2`, but works for all possible values of `argument`, including those with double quotes.
+
+#### Exported Arguments
+
+All arguments are exported when the `export` setting is set:
+
+```make
+set export
+
+foo argument:
+  touch "$argument"
+```
+
+Or individual arguments may be exported by prefixing them with `$`:
+
+```make
+foo $argument:
+  touch "$argument"
+```
+
+This defeats `just`'s ability to catch typos, for example if you type `$argumant`, but works for all possible values of `argument`, including those with double quotes.
+
 Changelog
 ---------