From 7575929fe303ea46a51868350c0872b4bb404ea5 Mon Sep 17 00:00:00 2001
From: Calvin Rose <calsrose@gmail.com>
Date: Sun, 30 Aug 2026 10:54:24 -0500
Subject: [PATCH] Lead users to `os/execute` over `os/shell` for most cases.

---
 src/core/os.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/core/os.c b/src/core/os.c
index c8ef4277..c46f05e5 100644
--- a/src/core/os.c
+++ b/src/core/os.c
@@ -1636,7 +1636,8 @@ static JanetEVGenericMessage os_shell_subr(JanetEVGenericMessage args) {
 
 JANET_CORE_FN(os_shell,
               "(os/shell str)",
-              "Pass a command string str directly to the system shell.") {
+              "Pass a command string `str` directly to the system shell. Prefer `os/execute` "
+              "in most cases.") {
     janet_sandbox_assert(JANET_SANDBOX_SUBPROCESS);
     janet_arity(argc, 0, 1);
     const char *cmd = argc