From ac552c01378590e5727830a510ef3d40f6c445e7 Mon Sep 17 00:00:00 2001 From: Oliver Drobnik Date: Thu, 11 Jun 2026 22:54:57 +0200 Subject: [PATCH] Docs: Shell.arguments follows $@ semantics, not CommandLine.arguments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The doc claimed 'Mirrors CommandLine.arguments semantics', but CommandLine.arguments[0] is the binary path while positionalParameters[0] is $1 — Shell.processDefault already strips argv[0]. That mismatch produced a double-drop in SwiftPorts' gh standalone entry (Cocoanetics/SwiftPorts#69, argv-deaf binary). State the $@ contract explicitly and warn about the dropFirst habit. Co-Authored-By: Claude Fable 5 --- Sources/ShellKit/Shell+Static.swift | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Sources/ShellKit/Shell+Static.swift b/Sources/ShellKit/Shell+Static.swift index 1ff552b..fa98f49 100644 --- a/Sources/ShellKit/Shell+Static.swift +++ b/Sources/ShellKit/Shell+Static.swift @@ -28,10 +28,16 @@ public extension Shell { } /// Snapshot of the active shell's positional parameters. - /// Mirrors `CommandLine.arguments` semantics — the value - /// embedders set via `Shell.positionalParameters`, falling - /// through to the host process arguments when running - /// standalone via ``Shell/processDefault``. + /// + /// Bash `$@` semantics: the program name is **not** included — + /// `arguments[0]` is the first real argument (`$1`). This is + /// *unlike* `CommandLine.arguments`, whose element 0 is the + /// binary path; a standalone entry point that `dropFirst()`s + /// out of that habit eats its first real argument + /// (SwiftPorts#69). The value is whatever embedders set via + /// ``Shell/positionalParameters``, falling through to the host + /// process arguments minus `argv[0]` when running standalone + /// via ``Shell/processDefault``. static var arguments: [String] { current.positionalParameters }