Autogenerated HTML docs for v2.56.1-625-gf7de8
diff --git a/RelNotes/2.98.0.adoc b/RelNotes/2.98.0.adoc
index a8e1dc1..6711f8f 100644
--- a/RelNotes/2.98.0.adoc
+++ b/RelNotes/2.98.0.adoc
@@ -194,6 +194,14 @@
    use 'git switch -c' instead of 'git checkout -b' in its examples,
    aligning with the earlier promotion of 'git switch'.
 
+ * The command line completion script (in contrib/) has been taught to
+   complete the '--[no-]graph-indent' and '--graph-lane-limit' options of
+   'git log'.
+
+ * The documentation on partial clone has been updated to describe the
+   order in which promisor remotes are tried when fetching missing
+   objects.
+
 
 Performance, Internal Implementation, Development Support etc.
 --------------------------------------------------------------
@@ -531,6 +539,31 @@
    modernized to use the 'test_path_is_dir' helper instead of the raw
    'test -d' shell command.
 
+ * The 'merge.c' code has been updated to eliminate its reliance on the
+   global 'the_repository' and 'the_hash_algo' variables by passing down
+   the repository context already available to its entry points.
+
+ * The merge-blobs subsystem has been updated to remove its reliance on
+   the global the_repository variable by threading the repository
+   context available from the index_state down to its helper functions.
+
+ * A test script has been modernized to use 'test_path_is_file' and
+   'test_path_is_missing' helpers.
+
+ * The technical documentation for the parse-options API has been
+   updated to include descriptions for various missing flags and
+   macros.
+
+ * The client-side refspec matching during 'git push' has been
+   optimized by replacing linear traversals with string map lookups,
+   speeding up pushes with lots of delete refspecs against a server
+   with many advertised refs.
+
+ * The index writer has been taught to check the untracked cache
+   against the filesystem when an FSMonitor trivial response is
+   received, preventing commands like 'git add' from saving a new token
+   while leaving stale untracked cache entries intact.
+
 
 Fixes since v2.56
 -----------------
@@ -802,6 +835,19 @@
    superproject's, avoiding potential ambiguity.
    (merge 96909c142c sp/submodule-abbrev-fix later to maint).
 
+ * The configuration parser for 'sideband.allowControlCharacters' has
+   been updated to correctly advance past unrecognized values,
+   preventing an infinite loop when an unknown control character
+   keyword is encountered.
+
+ * A regression where 'git grep --recurse-submodules' failed to read
+   nested trees in a submodule has been fixed by passing the correct
+   repository context pointer instead of relying on the global
+   'the_repository' variable. Additional latent bugs where grep_cache()
+   and grep_objects() incorrectly referenced the global state have also
+   been corrected.
+   (merge 8fa399d6f2 ps/grep-recurse-submodules-fix later to maint).
+
  * Other code cleanup, docfix, build fix, etc.
    (merge e638de60bc kz/doc-add-rm-typofix later to maint).
    (merge 778c73948a kz/doc-user-manual-typo later to maint).
diff --git a/technical/api-parse-options.adoc b/technical/api-parse-options.adoc
index 0072fab..c0ebe50 100644
--- a/technical/api-parse-options.adoc
+++ b/technical/api-parse-options.adoc
@@ -138,6 +138,16 @@
 	turns it off and allows one to add custom handlers for these
 	options, or to just leave them unknown.
 
+`PARSE_OPT_ONE_SHOT`::
+	Process only the first option (and its value, if any) and return
+	the number of arguments processed, leaving `argv[]` untouched.
+	`argv[0]` is taken to be the first option, not the program name.
+	An unknown option stops processing without an error.
+
+`PARSE_OPT_SHELL_EVAL`::
+	Wrap the usage output in a heredoc followed by an `exit 0`,
+	so that a shell can `eval` it.
+
 `PARSE_OPT_SUBCOMMAND_OPTIONAL`::
 	Don't error out when no subcommand is specified.
 
@@ -235,15 +245,25 @@
 `OPT__DRY_RUN(&int_var, description)`::
 	Add `-n, --dry-run`.
 
-`OPT__FORCE(&int_var, description)`::
+`OPT__FORCE(&int_var, description, flags)`::
 	Add `-f, --force`.
 
 `OPT__QUIET(&int_var, description)`::
 	Add `-q, --quiet`.
 
+`OPT__SUPER_PREFIX(&str_var)`::
+	Add hidden `--super-prefix=<prefix>`, which stores the prefixed
+	path to the initial superproject in `str_var`.
+
 `OPT__VERBOSE(&int_var, description)`::
 	Add `-v, --verbose`.
 
+`OPT__VERBOSITY(&int_var)`::
+	Add `-v, --verbose` and `-q, --quiet`, sharing `int_var`.
+	Each `-v` increments `int_var` (a `-v` after `-q` sets it to 1)
+	and each `-q` decrements it (a `-q` after `-v` sets it to -1).
+	`--no-verbose` and `--no-quiet` reset it to zero.
+
 `OPT_GROUP(description)`::
 	Start an option group. `description` is a short string that
 	describes the group or an empty string.
@@ -278,6 +298,11 @@
 	Introduce a boolean option.
 	If used, `int_var` is bitwise-ored with `mask`.
 
+`OPT_BITOP(short, long, &int_var, description, set, clear)`::
+	Introduce a boolean option.
+	If used, `int_var` is bitwise-anded with the inverted `clear` and
+	then bitwise-ored with `set`. Cannot be used in the negated form.
+
 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
 	Introduce a boolean option.
 	If used, `int_var` is bitwise-anded with the inverted `mask`.
@@ -296,6 +321,16 @@
 	The string argument is stored as an element in `string_list`.
 	Use of `--no-option` will clear the list of preceding values.
 
+`OPT_STRVEC(short, long, &struct strvec, arg_str, description)`::
+	Introduce an option with string argument.
+	The string argument is appended to the provided `strvec`.
+	Use of `--no-option` will clear the list of preceding values.
+
+`OPT_UYN(short, long, &int_var, description)`::
+	Introduce a ternary option.
+	`--option` sets `int_var` to `1` and `--no-option` sets it to `2`.
+	If neither is given, `int_var` is left unchanged.
+
 `OPT_INTEGER(short, long, &int_var, description)`::
 	Introduce an option with integer argument. The argument must be a
 	integer and may include a suffix of 'k', 'm' or 'g' to
@@ -345,6 +380,17 @@
 	Use it to hide deprecated options that are still to be recognized
 	and ignored silently.
 
+`OPT_NOOP_ARG(short, long)`::
+	Introduce an option that takes one argument but has no effect.
+	Use it to hide deprecated options that are still to be recognized
+	and ignored silently.
+
+`OPT_COLUMN(short, long, &unsigned_int_var, description)`::
+	Introduce an option that takes an optional argument and sets
+	`unsigned_int_var` as per the column layout modes specified in
+	linkgit:git-config[1]. `--option` and `--no-option` without
+	arguments are equivalent to `always` and `never` respectively.
+
 `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
 	Introduce an option that will be reconstructed into a char* string,
 	which must be initialized to NULL. This is useful when you need to
@@ -371,6 +417,64 @@
 	this subcommand is used. The subcommand is not listed in the
 	usage output.
 
+`OPT_CONTAINS(&commit_list_var, description)`::
+	Introduce a `--contains=<commit>` option. The argument is parsed
+	as a commit and inserted into `commit_list_var`. If the option is
+	the last token on the command line and has no argument, `HEAD`
+	is used. Cannot be negated.
+
+`OPT_NO_CONTAINS(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces `--no-contains=<commit>`.
+
+`OPT_WITH(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden `--with=<commit>`.
+
+`OPT_WITHOUT(&commit_list_var, description)`::
+	Like `OPT_CONTAINS()`, but introduces a hidden
+	`--without=<commit>`.
+
+`OPT_CLEANUP(&str_var)`::
+	Introduce a string option with `--cleanup` long name. Commonly
+	used to parse cleanup mode as specified in linkgit:git-commit[1].
+	The option does not do any parsing itself and simply stores the
+	argument in `str_var`.
+
+`OPT_PATHSPEC_FROM_FILE(&str_var)`::
+	Introduce a `--pathspec-from-file=<file>` option. Commonly used
+	to read the pathspec from a file instead of the command-line
+	arguments. See linkgit:git-commit[1] for more details.
+
+`OPT_PATHSPEC_FILE_NUL(&int_var)`::
+	Introduce a boolean `--pathspec-file-nul` option. Commonly
+	accompanies `OPT_PATHSPEC_FROM_FILE()` to denote that the
+	pathspec elements are separated with `NUL` characters.
+	See linkgit:git-commit[1] for more details.
+
+`OPT_AUTOSTASH(&int_var)`::
+	Introduce a boolean `--autostash` option. Commonly used to
+	automatically create a stash entry before the operation and
+	restore it after. See linkgit:git-merge[1] for more details.
+
+`OPT_DIFF_UNIFIED(&int_var)`::
+	Introduce an integer option with `-U` short name and `--unified`
+	long name. Commonly used to denote lines of context for generating
+	diffs. Cannot be negated. See linkgit:git-add[1] for more details.
+
+`OPT_DIFF_INTERHUNK_CONTEXT(&int_var)`::
+	Introduce an integer option with `--inter-hunk-context` long name.
+	Commonly used to show the context between diff hunks up to the
+	specified number. Cannot be negated. See linkgit:git-add[1] for
+	more details.
+
+`OPT_IPVERSION(&family_var)`::
+	Introduce `-4, --ipv4` and `-6, --ipv6` for selecting the IP
+	protocol to use. Neither takes an argument or can be negated.
+	`family_var` (an `enum transport_family`) is set to
+	`TRANSPORT_FAMILY_IPV4` or `TRANSPORT_FAMILY_IPV6` respectively.
+
+`OPT_ALIAS(short, long, source_long_name)`::
+	Introduce an alias to another existing `source_long_name` option.
+
 The last element of the array must be `OPT_END()`.
 
 If not stated otherwise, interpret the arguments as follows:
diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html
index 850a5bb..3887c91 100644
--- a/technical/api-parse-options.html
+++ b/technical/api-parse-options.html
@@ -635,6 +635,18 @@
 turns it off and allows one to add custom handlers for these
 options, or to just leave them unknown.</p>
 </dd>
+<dt class="hdlist1"><code>PARSE_OPT_ONE_SHOT</code></dt>
+<dd>
+<p>Process only the first option (and its value, if any) and return
+the number of arguments processed, leaving <code>argv</code>[] untouched.
+<code>argv</code>[<code>0</code>] is taken to be the first option, not the program name.
+An unknown option stops processing without an error.</p>
+</dd>
+<dt class="hdlist1"><code>PARSE_OPT_SHELL_EVAL</code></dt>
+<dd>
+<p>Wrap the usage output in a heredoc followed by an <code>exit</code> <code>0</code>,
+so that a shell can <code>eval</code> it.</p>
+</dd>
 <dt class="hdlist1"><code>PARSE_OPT_SUBCOMMAND_OPTIONAL</code></dt>
 <dd>
 <p>Don&#8217;t error out when no subcommand is specified.</p>
@@ -765,7 +777,7 @@
 <dd>
 <p>Add <code>-n,</code> <code>--dry-run</code>.</p>
 </dd>
-<dt class="hdlist1"><code>OPT__FORCE</code>(&amp;int_var, <code>description</code>)</dt>
+<dt class="hdlist1"><code>OPT__FORCE</code>(&amp;int_var, <code>description,</code> <code>flags</code>)</dt>
 <dd>
 <p>Add <code>-f,</code> <code>--force</code>.</p>
 </dd>
@@ -773,10 +785,22 @@
 <dd>
 <p>Add <code>-q,</code> <code>--quiet</code>.</p>
 </dd>
+<dt class="hdlist1"><code>OPT__SUPER_PREFIX</code>(&amp;str_var)</dt>
+<dd>
+<p>Add hidden <code>--super-prefix=</code><em>&lt;prefix&gt;</em>, which stores the prefixed
+path to the initial superproject in <code>str_var</code>.</p>
+</dd>
 <dt class="hdlist1"><code>OPT__VERBOSE</code>(&amp;int_var, <code>description</code>)</dt>
 <dd>
 <p>Add <code>-v,</code> <code>--verbose</code>.</p>
 </dd>
+<dt class="hdlist1"><code>OPT__VERBOSITY</code>(&amp;int_var)</dt>
+<dd>
+<p>Add <code>-v,</code> <code>--verbose</code> and <code>-q,</code> <code>--quiet</code>, sharing <code>int_var</code>.
+Each <code>-v</code> increments <code>int_var</code> (a <code>-v</code> after <code>-q</code> sets it to 1)
+and each <code>-q</code> decrements it (a <code>-q</code> after <code>-v</code> sets it to -1).
+<code>--no-verbose</code> and <code>--no-quiet</code> reset it to zero.</p>
+</dd>
 <dt class="hdlist1"><code>OPT_GROUP</code>(<code>description</code>)</dt>
 <dd>
 <p>Start an option group. <code>description</code> is a short string that
@@ -817,6 +841,12 @@
 <p>Introduce a boolean option.
 If used, <code>int_var</code> is bitwise-ored with <code>mask</code>.</p>
 </dd>
+<dt class="hdlist1"><code>OPT_BITOP</code>(<code>short,</code> <code>long,</code> &amp;int_var, <code>description,</code> <code>set,</code> <code>clear</code>)</dt>
+<dd>
+<p>Introduce a boolean option.
+If used, <code>int_var</code> is bitwise-anded with the inverted <code>clear</code> and
+then bitwise-ored with <code>set</code>. Cannot be used in the negated form.</p>
+</dd>
 <dt class="hdlist1"><code>OPT_NEGBIT</code>(<code>short,</code> <code>long,</code> &amp;int_var, <code>description,</code> <code>mask</code>)</dt>
 <dd>
 <p>Introduce a boolean option.
@@ -839,6 +869,18 @@
 The string argument is stored as an element in <code>string_list</code>.
 Use of <code>--no-option</code> will clear the list of preceding values.</p>
 </dd>
+<dt class="hdlist1"><code>OPT_STRVEC</code>(<code>short,</code> <code>long,</code> &amp;struct <code>strvec,</code> <code>arg_str,</code> <code>description</code>)</dt>
+<dd>
+<p>Introduce an option with string argument.
+The string argument is appended to the provided <code>strvec</code>.
+Use of <code>--no-option</code> will clear the list of preceding values.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_UYN</code>(<code>short,</code> <code>long,</code> &amp;int_var, <code>description</code>)</dt>
+<dd>
+<p>Introduce a ternary option.
+<code>--option</code> sets <code>int_var</code> to <code>1</code> and <code>--no-option</code> sets it to <code>2</code>.
+If neither is given, <code>int_var</code> is left unchanged.</p>
+</dd>
 <dt class="hdlist1"><code>OPT_INTEGER</code>(<code>short,</code> <code>long,</code> &amp;int_var, <code>description</code>)</dt>
 <dd>
 <p>Introduce an option with integer argument. The argument must be a
@@ -896,6 +938,19 @@
 Use it to hide deprecated options that are still to be recognized
 and ignored silently.</p>
 </dd>
+<dt class="hdlist1"><code>OPT_NOOP_ARG</code>(<code>short,</code> <code>long</code>)</dt>
+<dd>
+<p>Introduce an option that takes one argument but has no effect.
+Use it to hide deprecated options that are still to be recognized
+and ignored silently.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_COLUMN</code>(<code>short,</code> <code>long,</code> &amp;unsigned_int_var, <code>description</code>)</dt>
+<dd>
+<p>Introduce an option that takes an optional argument and sets
+<code>unsigned_int_var</code> as per the column layout modes specified in
+<a href="../git-config.html">git-config(1)</a>. <code>--option</code> and <code>--no-option</code> without
+arguments are equivalent to <code>always</code> and <code>never</code> respectively.</p>
+</dd>
 <dt class="hdlist1"><code>OPT_PASSTHRU</code>(<code>short,</code> <code>long,</code> &amp;char_var, <code>arg_str,</code> <code>description,</code> <code>flags</code>)</dt>
 <dd>
 <p>Introduce an option that will be reconstructed into a char* string,
@@ -926,6 +981,76 @@
 this subcommand is used. The subcommand is not listed in the
 usage output.</p>
 </dd>
+<dt class="hdlist1"><code>OPT_CONTAINS</code>(&amp;commit_list_var, <code>description</code>)</dt>
+<dd>
+<p>Introduce a <code>--contains=</code><em>&lt;commit&gt;</em> option. The argument is parsed
+as a commit and inserted into <code>commit_list_var</code>. If the option is
+the last token on the command line and has no argument, <code>HEAD</code>
+is used. Cannot be negated.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_NO_CONTAINS</code>(&amp;commit_list_var, <code>description</code>)</dt>
+<dd>
+<p>Like <code>OPT_CONTAINS</code>(), but introduces <code>--no-contains=</code><em>&lt;commit&gt;</em>.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_WITH</code>(&amp;commit_list_var, <code>description</code>)</dt>
+<dd>
+<p>Like <code>OPT_CONTAINS</code>(), but introduces a hidden <code>--with=</code><em>&lt;commit&gt;</em>.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_WITHOUT</code>(&amp;commit_list_var, <code>description</code>)</dt>
+<dd>
+<p>Like <code>OPT_CONTAINS</code>(), but introduces a hidden
+<code>--without=</code><em>&lt;commit&gt;</em>.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_CLEANUP</code>(&amp;str_var)</dt>
+<dd>
+<p>Introduce a string option with <code>--cleanup</code> long name. Commonly
+used to parse cleanup mode as specified in <a href="../git-commit.html">git-commit(1)</a>.
+The option does not do any parsing itself and simply stores the
+argument in <code>str_var</code>.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_PATHSPEC_FROM_FILE</code>(&amp;str_var)</dt>
+<dd>
+<p>Introduce a <code>--pathspec-from-file=</code><em>&lt;file&gt;</em> option. Commonly used
+to read the pathspec from a file instead of the command-line
+arguments. See <a href="../git-commit.html">git-commit(1)</a> for more details.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_PATHSPEC_FILE_NUL</code>(&amp;int_var)</dt>
+<dd>
+<p>Introduce a boolean <code>--pathspec-file-nul</code> option. Commonly
+accompanies <code>OPT_PATHSPEC_FROM_FILE</code>() to denote that the
+pathspec elements are separated with <code>NUL</code> characters.
+See <a href="../git-commit.html">git-commit(1)</a> for more details.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_AUTOSTASH</code>(&amp;int_var)</dt>
+<dd>
+<p>Introduce a boolean <code>--autostash</code> option. Commonly used to
+automatically create a stash entry before the operation and
+restore it after. See <a href="../git-merge.html">git-merge(1)</a> for more details.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_DIFF_UNIFIED</code>(&amp;int_var)</dt>
+<dd>
+<p>Introduce an integer option with <code>-U</code> short name and <code>--unified</code>
+long name. Commonly used to denote lines of context for generating
+diffs. Cannot be negated. See <a href="../git-add.html">git-add(1)</a> for more details.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_DIFF_INTERHUNK_CONTEXT</code>(&amp;int_var)</dt>
+<dd>
+<p>Introduce an integer option with <code>--inter-hunk-context</code> long name.
+Commonly used to show the context between diff hunks up to the
+specified number. Cannot be negated. See <a href="../git-add.html">git-add(1)</a> for
+more details.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_IPVERSION</code>(&amp;family_var)</dt>
+<dd>
+<p>Introduce <code>-4,</code> <code>--ipv4</code> and <code>-6,</code> <code>--ipv6</code> for selecting the IP
+protocol to use. Neither takes an argument or can be negated.
+<code>family_var</code> (an <code>enum</code> <code>transport_family</code>) is set to
+<code>TRANSPORT_FAMILY_IPV4</code> or <code>TRANSPORT_FAMILY_IPV6</code> respectively.</p>
+</dd>
+<dt class="hdlist1"><code>OPT_ALIAS</code>(<code>short,</code> <code>long,</code> <code>source_long_name</code>)</dt>
+<dd>
+<p>Introduce an alias to another existing <code>source_long_name</code> option.</p>
+</dd>
 </dl>
 </div>
 <div class="paragraph">
@@ -1033,7 +1158,7 @@
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-11-15 15:02:18 -0800
+Last updated 2026-11-19 16:27:10 -0800
 </div>
 </div>
 </body>
diff --git a/technical/partial-clone.adoc b/technical/partial-clone.adoc
index 18718a3..52fce44 100644
--- a/technical/partial-clone.adoc
+++ b/technical/partial-clone.adoc
@@ -195,7 +195,9 @@
 filtered `git-fetch` commands from the central server.
 
 When fetching objects, promisor remotes are tried one after the other
-until all the objects have been fetched.
+until all the objects have been fetched. Promisor remotes that the
+client accepted from a server's advertisement are tried before the
+other promisor remotes.
 
 Remotes that are considered "promisor" remotes are those specified by
 the following configuration variables:
diff --git a/technical/partial-clone.html b/technical/partial-clone.html
index d0d490b..af462d4 100644
--- a/technical/partial-clone.html
+++ b/technical/partial-clone.html
@@ -707,7 +707,9 @@
 </div>
 <div class="paragraph">
 <p>When fetching objects, promisor remotes are tried one after the other
-until all the objects have been fetched.</p>
+until all the objects have been fetched. Promisor remotes that the
+client accepted from a server&#8217;s advertisement are tried before the
+other promisor remotes.</p>
 </div>
 <div class="paragraph">
 <p>Remotes that are considered "promisor" remotes are those specified by
@@ -947,7 +949,7 @@
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-09-02 14:16:12 -0700
+Last updated 2026-11-19 16:27:10 -0800
 </div>
 </div>
 </body>