From 884c2d8b6b7dd8c8ff4b0ad1caf429ed1234540a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 28 Mar 2026 02:08:14 +0000
Subject: [PATCH] Add yqFlags to expressionScenario for doc command snippets;
 fix system op docs

Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/3f8a5375-25fd-4428-a8e6-b630194c36b2

Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>
---
 pkg/yqlib/doc/operators/system-operators.md |  4 ++--
 pkg/yqlib/operator_system_test.go           |  2 ++
 pkg/yqlib/operators_test.go                 | 15 ++++++++++++---
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/pkg/yqlib/doc/operators/system-operators.md b/pkg/yqlib/doc/operators/system-operators.md
index f9c0346c..0223acaa 100644
--- a/pkg/yqlib/doc/operators/system-operators.md
+++ b/pkg/yqlib/doc/operators/system-operators.md
@@ -47,7 +47,7 @@ country: Australia
 ```
 then
 ```bash
-yq '.country = system("/usr/bin/echo"; "test")' sample.yml
+yq --enable-system-operator '.country = system("/usr/bin/echo"; "test")' sample.yml
 ```
 will output
 ```yaml
@@ -63,7 +63,7 @@ a: hello
 ```
 then
 ```bash
-yq '.a = system("/usr/bin/echo")' sample.yml
+yq --enable-system-operator '.a = system("/usr/bin/echo")' sample.yml
 ```
 will output
 ```yaml
diff --git a/pkg/yqlib/operator_system_test.go b/pkg/yqlib/operator_system_test.go
index 388f4446..385e1561 100644
--- a/pkg/yqlib/operator_system_test.go
+++ b/pkg/yqlib/operator_system_test.go
@@ -55,6 +55,7 @@ func TestSystemOperatorEnabledScenarios(t *testing.T) {
 		{
 			description:    "Run a command with an argument",
 			subdescription: "Use `--enable-system-operator` to enable the system operator.",
+			yqFlags:        "--enable-system-operator",
 			document:       "country: Australia",
 			expression:     `.country = system("` + echoPath + `"; "test")`,
 			expected: []string{
@@ -64,6 +65,7 @@ func TestSystemOperatorEnabledScenarios(t *testing.T) {
 		{
 			description:    "Run a command without arguments",
 			subdescription: "Omit the semicolon and args to run the command with no extra arguments.",
+			yqFlags:        "--enable-system-operator",
 			document:       "a: hello",
 			expression:     `.a = system("` + echoPath + `")`,
 			expected: []string{
diff --git a/pkg/yqlib/operators_test.go b/pkg/yqlib/operators_test.go
index 1646fb9b..b4d4301e 100644
--- a/pkg/yqlib/operators_test.go
+++ b/pkg/yqlib/operators_test.go
@@ -31,6 +31,7 @@ type expressionScenario struct {
 	dontFormatInputForDoc bool // dont format input doc for documentation generation
 	requiresFormat        string
 	skipForGoccy          bool
+	yqFlags               string // extra yq flags to include in generated doc command snippets
 }
 
 var goccyTesting = false
@@ -356,14 +357,22 @@ func documentInput(w *bufio.Writer, s expressionScenario) (string, string) {
 
 		writeOrPanic(w, "then\n")
 
+		flagsPrefix := ""
+		if s.yqFlags != "" {
+			flagsPrefix = s.yqFlags + " "
+		}
 		if s.expression != "" {
-			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v'%v' %v\n```\n", envCommand, command, strings.ReplaceAll(s.expression, "'", `'\''`), files))
+			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v'%v' %v\n```\n", envCommand, flagsPrefix, command, strings.ReplaceAll(s.expression, "'", `'\''`), files))
 		} else {
-			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v\n```\n", envCommand, command, files))
+			writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v%v\n```\n", envCommand, flagsPrefix, command, files))
 		}
 	} else {
 		writeOrPanic(w, "Running\n")
-		writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v--null-input '%v'\n```\n", envCommand, command, s.expression))
+		flagsPrefix := ""
+		if s.yqFlags != "" {
+			flagsPrefix = s.yqFlags + " "
+		}
+		writeOrPanic(w, fmt.Sprintf("```bash\n%vyq %v%v--null-input '%v'\n```\n", envCommand, flagsPrefix, command, s.expression))
 	}
 	return formattedDoc, formattedDoc2
 }