From 3c1261afb42184787002271ac6b13ddd4f4d1832 Mon Sep 17 00:00:00 2001
From: Vidar Holen <vidar@vidarholen.net>
Date: Fri, 22 Jul 2022 17:20:53 -0700
Subject: [PATCH] Updated SC3021 (markdown)

---
 SC3021.md | 42 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 37 insertions(+), 5 deletions(-)

diff --git a/SC3021.md b/SC3021.md
index af100e9..1f4a948 100644
--- a/SC3021.md
+++ b/SC3021.md
@@ -1,9 +1,41 @@
-## In POSIX sh, `>&` is undefined.
+## In POSIX sh, >& filename (as opposed to >& fd) is undefined.
 
-This warning was retracted after 0.8.0.
+Note: ShellCheck 0.8.0 and below would trigger this warning on the perfectly POSIX compatible construct `>& fd`. If you are using `>&` to copy an integer file descriptor, please ignore this warning.
 
-There are two forms of this operator: `>& fd`, and `>& filename`. The former is POSIX, and copies stdout to the given file descriptor or fails if it's not an integer. The latter is a bash specific extension meaning `> filename 2>&1`. Bash will interpret `>& $var` as one or the other depending on whether the value is an integer.
+### Problematic code:
 
-ShellCheck 0.8.0 and below was unable to differentiate and unintentionally treated both as `>& filename`, causing an invalid warning when the value was an integer.
+```sh
+# Writing to a filename
+mycommand >& log.txt
+```
 
-If your script uses `>&` with an integer to copy a file descriptor, please ignore this warning. If it uses it to write both stdout and stderr to a filename, like `&>`, rewrite it explicitly to `> file 2>&1`. 
\ No newline at end of file
+### Correct code:
+
+```sh
+mycommand > log.txt 2>&1
+```
+
+The following construct is also fine, as it uses an integer file descriptor instead of a filename:
+
+```sh
+fd=3
+mycommand >& $fd
+```
+
+### Rationale:
+
+There are two forms of the `>&` file descriptor operator:
+
+* `>& integer` such as `>& 3` is a POSIX compatible synonym for `1>&3`
+* `>& filename` such as `>& log.txt` is a Bash specific synonym for `> log.txt 2>&1`
+
+If (and only if) you are using the latter form, write it out as shown in the correct example to ensure portability.
+
+### Exceptions:
+
+ShellCheck 0.8.0 and below incorrectly emits this warning for constructs like `>& $var`, even though this would be POSIX compatible when `$var` is an integer. In such cases, please ignore this warning.
+
+### Related resources:
+
+* [Shellcheck issue #2520](https://github.com/koalaman/shellcheck/issues/2520)
+* Help by adding links to BashFAQ, StackOverflow, man pages, POSIX, etc!
\ No newline at end of file