From a7ce94f63e36a7085a3c7d7ce4a0a9930ec1a14d Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Thu, 5 Mar 2020 19:24:53 -0800
Subject: [PATCH]  Document behavior of `@` on shebang recipes (#602)

Shebang recipes have the somewhat confusing property of being quiet by
default, with `@` before a shebang recipe name causing just to print out
the recipe before executing it.

This is somewhat questionable behavior, since it's the opposite of
linewise recipes, but it should be documented, even if it might change
in the future.
---
 README.adoc | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.adoc b/README.adoc
index 394870d..0b0452b 100644
--- a/README.adoc
+++ b/README.adoc
@@ -812,6 +812,35 @@ goodbye
 # all done!
 ```
 
+Shebang recipes are quiet by default:
+
+```make
+foo:
+  #!/usr/bin/env bash
+  echo 'Foo!'
+```
+
+```sh
+$ just foo
+Foo!
+```
+
+Adding `@` to a shebang recipe name makes `just` print the recipe before executing it:
+
+
+```make
+@bar:
+  #!/usr/bin/env bash
+  echo 'Bar!'
+```
+
+```sh
+$ just bar                                                                                    ~/src/just
+#!/usr/bin/env bash
+echo 'Bar!'
+Bar!
+```
+
 === Invoking Justfiles in Other Directories
 
 If the first argument passed to `just` contains a `/`, then the following occurs: