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’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>(&int_var, <code>description</code>)</dt> +<dt class="hdlist1"><code>OPT__FORCE</code>(&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>(&str_var)</dt> +<dd> +<p>Add hidden <code>--super-prefix=</code><em><prefix></em>, which stores the prefixed +path to the initial superproject in <code>str_var</code>.</p> +</dd> <dt class="hdlist1"><code>OPT__VERBOSE</code>(&int_var, <code>description</code>)</dt> <dd> <p>Add <code>-v,</code> <code>--verbose</code>.</p> </dd> +<dt class="hdlist1"><code>OPT__VERBOSITY</code>(&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> &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> &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> &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> &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> &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> &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> &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>(&commit_list_var, <code>description</code>)</dt> +<dd> +<p>Introduce a <code>--contains=</code><em><commit></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>(&commit_list_var, <code>description</code>)</dt> +<dd> +<p>Like <code>OPT_CONTAINS</code>(), but introduces <code>--no-contains=</code><em><commit></em>.</p> +</dd> +<dt class="hdlist1"><code>OPT_WITH</code>(&commit_list_var, <code>description</code>)</dt> +<dd> +<p>Like <code>OPT_CONTAINS</code>(), but introduces a hidden <code>--with=</code><em><commit></em>.</p> +</dd> +<dt class="hdlist1"><code>OPT_WITHOUT</code>(&commit_list_var, <code>description</code>)</dt> +<dd> +<p>Like <code>OPT_CONTAINS</code>(), but introduces a hidden +<code>--without=</code><em><commit></em>.</p> +</dd> +<dt class="hdlist1"><code>OPT_CLEANUP</code>(&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>(&str_var)</dt> +<dd> +<p>Introduce a <code>--pathspec-from-file=</code><em><file></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>(&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>(&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>(&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>(&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>(&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’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>