From 611c575a97f0fbaaea9c334b2c70ffe3fa733f41 Mon Sep 17 00:00:00 2001
From: Hugohong258 <ugfifkgfufyu@gmail.com>
Date: Sun, 11 Oct 2026 23:24:32 +0800
Subject: [PATCH] docs: add simple and nested update-assignment examples
 (#3664)

---
 docs/content/manual/dev/manual.yml | 6 ++++++
 jq.1.prebuilt                      | 8 ++++++++
 tests/man.test                     | 8 ++++++++
 3 files changed, 22 insertions(+)

diff --git a/docs/content/manual/dev/manual.yml b/docs/content/manual/dev/manual.yml
index 64b2ef51..f4e91a6e 100644
--- a/docs/content/manual/dev/manual.yml
+++ b/docs/content/manual/dev/manual.yml
@@ -3572,6 +3572,12 @@ sections:
           releases, it used to be that only the last one was used).
 
         examples:
+          - program: '.foo |= . + 1'
+            input: '{"foo": 41, "bar": "unchanged"}'
+            output: ['{"foo": 42, "bar": "unchanged"}']
+          - program: '.user.age |= . + 1'
+            input: '{"user": {"name": "alice", "age": 30}, "active": true}'
+            output: ['{"user": {"name": "alice", "age": 31}, "active": true}']
           - program: '(..|select(type=="boolean")) |= if . then 1 else 0 end'
             input: '[true,false,[5,true,[true,[false]],false]]'
             output: ['[1,0,[5,1,[1,[0]],0]]']
diff --git a/jq.1.prebuilt b/jq.1.prebuilt
index 11150d17..f9f6e826 100644
--- a/jq.1.prebuilt
+++ b/jq.1.prebuilt
@@ -3942,6 +3942,14 @@ If the right\-hand side outputs multiple values, only the first one will be used
 .
 .nf
 
+jq \'\.foo |= \. + 1\'
+   {"foo": 41, "bar": "unchanged"}
+=> {"foo": 42, "bar": "unchanged"}
+
+jq \'\.user\.age |= \. + 1\'
+   {"user": {"name": "alice", "age": 30}, "active": true}
+=> {"user": {"name": "alice", "age": 31}, "active": true}
+
 jq \'(\.\.|select(type=="boolean")) |= if \. then 1 else 0 end\'
    [true,false,[5,true,[true,[false]],false]]
 => [1,0,[5,1,[1,[0]],0]]
diff --git a/tests/man.test b/tests/man.test
index f6b13d2b..2818c822 100644
--- a/tests/man.test
+++ b/tests/man.test
@@ -978,6 +978,14 @@ null
 [0,[1,{"a":1},{"b":2}]]
 true
 
+.foo |= . + 1
+{"foo": 41, "bar": "unchanged"}
+{"foo": 42, "bar": "unchanged"}
+
+.user.age |= . + 1
+{"user": {"name": "alice", "age": 30}, "active": true}
+{"user": {"name": "alice", "age": 31}, "active": true}
+
 (..|select(type=="boolean")) |= if . then 1 else 0 end
 [true,false,[5,true,[true,[false]],false]]
 [1,0,[5,1,[1,[0]],0]]