diff --git a/README.adoc b/README.adoc
index ca97a5bf..ff290e4c 100644
--- a/README.adoc
+++ b/README.adoc
@@ -619,6 +619,25 @@ foo
 hello
 ```
 
+When using an `sh`-compatible shell, such as `bash` or `zsh`, `$@` expands to the positional arguments given to the recipe, starting from one. When used within double quotes as `"$@"`, arguments including whitespace will be passed on as if they were double-quoted. That is, "$@" is equivalent to "$1" "$2"... When there are no positional parameters, "$@" and $@ expand to nothing (i.e., they are removed).
+
+This example recipe will print arguments one by one on separate lines:
+
+```make
+set positional-arguments
+
+@test *args='':
+    bash -c 'while (( "$#" )); do echo - $1; shift; done' -- "$@"
+```
+
+Running it with _two_ arguments:
+
+```
+$ just test foo "bar baz"
+- foo
+- bar baz
+```
+             
 ==== Shell
 
 The `shell` setting controls the command used to invoke recipe lines and backticks. Shebang recipes are unaffected.