From 910775cdf921315310f99ea354de7aaf47917cf3 Mon Sep 17 00:00:00 2001
From: Polly Labs <pollychen.lab@gmail.com>
Date: Sun, 12 Jul 2026 16:00:33 -0500
Subject: [PATCH] docs: add command-v example pair

---
 examples/standards/11-command-v-not-which.bad.sh  | 10 ++++++++++
 examples/standards/11-command-v-not-which.good.sh | 15 +++++++++++++++
 examples/standards/README.md                      |  1 +
 3 files changed, 26 insertions(+)
 create mode 100755 examples/standards/11-command-v-not-which.bad.sh
 create mode 100755 examples/standards/11-command-v-not-which.good.sh

diff --git a/examples/standards/11-command-v-not-which.bad.sh b/examples/standards/11-command-v-not-which.bad.sh
new file mode 100755
index 0000000..de9a019
--- /dev/null
+++ b/examples/standards/11-command-v-not-which.bad.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+#
+# BAD: which is an external program with non-portable output and unreliable
+# exit status. Prefer the shell builtin `command -v`.
+# expect-shellcheck: SC2230
+if which jq > /dev/null 2>&1; then
+  printf 'jq is available\n'
+else
+  printf 'jq is not available\n'
+fi
diff --git a/examples/standards/11-command-v-not-which.good.sh b/examples/standards/11-command-v-not-which.good.sh
new file mode 100755
index 0000000..acf0ae4
--- /dev/null
+++ b/examples/standards/11-command-v-not-which.good.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+#
+# GOOD: command -v is a shell builtin with predictable output and exit status
+# for checking whether a command is available.
+set -euo pipefail
+
+main() {
+  if command -v jq > /dev/null; then
+    printf 'jq is available\n'
+  else
+    printf 'jq is not available\n'
+  fi
+}
+
+main "$@"
diff --git a/examples/standards/README.md b/examples/standards/README.md
index e911f46..ca7bbbe 100644
--- a/examples/standards/README.md
+++ b/examples/standards/README.md
@@ -30,6 +30,7 @@ paired files side by side.
 | `08-brace-expansions` | `${base}_2026` | `$base_2026` (a different var) | `SC2250` |
 | `09-no-parse-ls` | glob `"$dir"/*.txt` | `$(ls *.txt)` | `SC2045` |
 | `10-parameter-expansion-not-sed` | `${path##*/}` strips in-process | `echo ... \| sed ...` forks twice | `SC2001` |
+| `11-command-v-not-which` | `command -v jq` checks a command | `which jq` is non-standard | `SC2230` |
 
 ## `.env.example`