From e3d5bbdf1f213caafedf185251fba02558d30b98 Mon Sep 17 00:00:00 2001
From: Nikias Bassen
Date: Fri, 20 Feb 2026 03:38:36 +0100
Subject: plistutil: Add a --nodepath option to allow selecting a specific node

---
 docs/plistutil.1 | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

(limited to 'docs/plistutil.1')

diff --git a/docs/plistutil.1 b/docs/plistutil.1
index b1f7773..f322bab 100644
--- a/docs/plistutil.1
+++ b/docs/plistutil.1
@@ -28,6 +28,52 @@ convert to/from JSON or OpenStep the output format needs to specified.
 .TP
 .B \-p, \-\-print FILE
 Print PList in human-readable format.
+.TP
+.B \-n, \-\-nodepath PATH
+Restrict output to nodepath defined by
+.I PATH
+which selects a specific node within the plist document.
+A node path describes traversal through dictionaries and arrays using / to
+separate the components.
+Traversal begins at the root node and proceeds from left to right.
+Each component selects a child of the current node.
+If the current node is a dictionary, the component is interpreted as a
+dictionary key name.
+If the current node is an array, the component must be a non-negative decimal
+integer specifying the array index (0-based).
+
+Given the following structure:
+.PP
+.RS
+.nf
+<plist version="1.0">
+<dict>
+  <key>Users</key>
+  <array>
+    <dict>
+      <key>Name</key>
+      <string>Alice</string>
+    </dict>
+    <dict>
+      <key>Name</key>
+      <string>Bob</string>
+    </dict>
+  </array>
+</dict>
+</plist>
+.fi
+
+A nodepath of:
+.TP
+\f[B]Users\f[] resolves to the entire array.
+.TP
+\f[B]Users/0\f[] resolves to the first dictionary in the array.
+.TP
+\f[B]Users/0/Name\f[] resolves to the string value "Alice".
+.TP
+\f[B]Users/1/Name\f[] resolves to the string value "Bob".
+.RE
+
 .TP
 .B \-c, \-\-compact
 JSON and OpenStep only: Print output in compact form. By default, the output
-- 
cgit v1.1-32-gdbae