From 8c25f33df4d470c434ee715191dbda797618f74f Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sun, 9 Nov 2025 16:19:04 +1100
Subject: [PATCH] Merge in master

---
 go.sum                           |  1 -
 pkg/yqlib/doc/operators/first.md | 23 ++++++++++++++++++-----
 pkg/yqlib/shellvariables.go      |  1 -
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/go.sum b/go.sum
index 6afb12f5..85fb2918 100644
--- a/go.sum
+++ b/go.sum
@@ -59,7 +59,6 @@ golang.org/x/sys v0.37.0 h1:fdNQudmxPjkdUTPnLn5mdQv7Zwvbvpaxqs831goi9kQ=
 golang.org/x/sys v0.37.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k=
 golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/op/go-logging.v1 v1.0.0-20160211212156-b2cb9fa56473 h1:6D+BvnJ/j6e222UW8s2qTSe3wGBtvo0MbVQG/c5k8RE=
 gopkg.in/op/go-logging.v1 v1.0.0-20160211212156-b2cb9fa56473/go.mod h1:N1eN2tsCx0Ydtgjl4cqmbRCsY4/+z4cYDeqwZTk6zog=
diff --git a/pkg/yqlib/doc/operators/first.md b/pkg/yqlib/doc/operators/first.md
index 349fe1b0..ae0bd715 100644
--- a/pkg/yqlib/doc/operators/first.md
+++ b/pkg/yqlib/doc/operators/first.md
@@ -1,3 +1,8 @@
+# First
+
+Returns the first matching element in an array, or first matching value in a map.
+
+Can be given an expression to match with, otherwise will just return the first.
 
 ## First matching element from array
 Given a sample.yml file of:
@@ -20,8 +25,10 @@ Given a sample.yml file of:
 ```yaml
 - a: banana
 - a: cat
+  b: firstCat
 - a: apple
 - a: cat
+  b: secondCat
 ```
 then
 ```bash
@@ -30,6 +37,7 @@ yq 'first(.a == "cat")' sample.yml
 will output
 ```yaml
 a: cat
+b: firstCat
 ```
 
 ## First matching element from array with numeric condition
@@ -38,6 +46,7 @@ Given a sample.yml file of:
 - a: 10
 - a: 100
 - a: 1
+- a: 101
 ```
 then
 ```bash
@@ -53,7 +62,10 @@ Given a sample.yml file of:
 ```yaml
 - a: false
 - a: true
+  b: firstTrue
 - a: false
+- a: true
+  b: secondTrue
 ```
 then
 ```bash
@@ -62,6 +74,7 @@ yq 'first(.a == true)' sample.yml
 will output
 ```yaml
 a: true
+b: firstTrue
 ```
 
 ## First matching element from array with null values
@@ -84,19 +97,19 @@ a: cat
 Given a sample.yml file of:
 ```yaml
 - a: dog
-  b: 5
+  b: 7
 - a: cat
   b: 3
 - a: apple
-  b: 7
+  b: 5
 ```
 then
 ```bash
-yq 'first(.b > 4)' sample.yml
+yq 'first(.b > 4 and .b < 6)' sample.yml
 ```
 will output
 ```yaml
-a: dog
+a: apple
 b: 5
 ```
 
@@ -127,7 +140,7 @@ x:
 y:
   a: 100
 z:
-  a: 1
+  a: 101
 ```
 then
 ```bash
diff --git a/pkg/yqlib/shellvariables.go b/pkg/yqlib/shellvariables.go
index 634fc6fa..75801cda 100644
--- a/pkg/yqlib/shellvariables.go
+++ b/pkg/yqlib/shellvariables.go
@@ -11,4 +11,3 @@ func NewDefaultShellVariablesPreferences() ShellVariablesPreferences {
 }
 
 var ConfiguredShellVariablesPreferences = NewDefaultShellVariablesPreferences()
-