Autogenerated HTML docs for v2.50.1-271-gd30e1

Author: gitster

BreakingChanges.adoc

@@ -118,6 +118,53 @@ Cf. <[email protected]>,
 <[email protected]>,
 <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
 
+* The default storage format for references in newly created repositories will
+  be changed from "files" to "reftable". The "reftable" format provides
+  multiple advantages over the "files" format:
++
+  ** It is impossible to store two references that only differ in casing on
+     case-insensitive filesystems with the "files" format. This issue is common
+     on Windows and macOS platforms. As the "reftable" backend does not use
+     filesystem paths to encode reference names this problem goes away.
+  ** Similarly, macOS normalizes path names that contain unicode characters,
+     which has the consequence that you cannot store two names with unicode
+     characters that are encoded differently with the "files" backend. Again,
+     this is not an issue with the "reftable" backend.
+  ** Deleting references with the "files" backend requires Git to rewrite the
+     complete "packed-refs" file. In large repositories with many references
+     this file can easily be dozens of megabytes in size, in extreme cases it
+     may be gigabytes. The "reftable" backend uses tombstone markers for
+     deleted references and thus does not have to rewrite all of its data.
+  ** Repository housekeeping with the "files" backend typically performs
+     all-into-one repacks of references. This can be quite expensive, and
+     consequently housekeeping is a tradeoff between the number of loose
+     references that accumulate and slow down operations that read references,
+     and compressing those loose references into the "packed-refs" file. The
+     "reftable" backend uses geometric compaction after every write, which
+     amortizes costs and ensures that the backend is always in a
+     well-maintained state.
+  ** Operations that write multiple references at once are not atomic with the
+     "files" backend. Consequently, Git may see in-between states when it reads
+     references while a reference transaction is in the process of being
+     committed to disk.
+  ** Writing many references at once is slow with the "files" backend because
+     every reference is created as a separate file. The "reftable" backend
+     significantly outperforms the "files" backend by multiple orders of
+     magnitude.
+  ** The reftable backend uses a binary format with prefix compression for
+     reference names. As a result, the format uses less space compared to the
+     "packed-refs" file.
++
+Users that get immediate benefit from the "reftable" backend could continue to
+opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
+config. But defaults matter, and we think that overall users will have a better
+experience with less platform-specific quirks when they use the new backend by
+default.
++
+A prerequisite for this change is that the ecosystem is ready to support the
+"reftable" format. Most importantly, alternative implementations of Git like
+JGit, libgit2 and Gitoxide need to support it.
+
 === Removals
 
 * Support for grafting commits has long been superseded by git-replace(1).

BreakingChanges.html

@@ -620,6 +620,73 @@ <h3 id="_changes">Changes</h3>
 </ul>
 </div>
 </li>
+<li>
+<p>The default storage format for references in newly created repositories will
+be changed from "files" to "reftable". The "reftable" format provides
+multiple advantages over the "files" format:</p>
+<div class="ulist">
+<ul>
+<li>
+<p>It is impossible to store two references that only differ in casing on
+case-insensitive filesystems with the "files" format. This issue is common
+on Windows and macOS platforms. As the "reftable" backend does not use
+filesystem paths to encode reference names this problem goes away.</p>
+</li>
+<li>
+<p>Similarly, macOS normalizes path names that contain unicode characters,
+which has the consequence that you cannot store two names with unicode
+characters that are encoded differently with the "files" backend. Again,
+this is not an issue with the "reftable" backend.</p>
+</li>
+<li>
+<p>Deleting references with the "files" backend requires Git to rewrite the
+complete "packed-refs" file. In large repositories with many references
+this file can easily be dozens of megabytes in size, in extreme cases it
+may be gigabytes. The "reftable" backend uses tombstone markers for
+deleted references and thus does not have to rewrite all of its data.</p>
+</li>
+<li>
+<p>Repository housekeeping with the "files" backend typically performs
+all-into-one repacks of references. This can be quite expensive, and
+consequently housekeeping is a tradeoff between the number of loose
+references that accumulate and slow down operations that read references,
+and compressing those loose references into the "packed-refs" file. The
+"reftable" backend uses geometric compaction after every write, which
+amortizes costs and ensures that the backend is always in a
+well-maintained state.</p>
+</li>
+<li>
+<p>Operations that write multiple references at once are not atomic with the
+"files" backend. Consequently, Git may see in-between states when it reads
+references while a reference transaction is in the process of being
+committed to disk.</p>
+</li>
+<li>
+<p>Writing many references at once is slow with the "files" backend because
+every reference is created as a separate file. The "reftable" backend
+significantly outperforms the "files" backend by multiple orders of
+magnitude.</p>
+</li>
+<li>
+<p>The reftable backend uses a binary format with prefix compression for
+reference names. As a result, the format uses less space compared to the
+"packed-refs" file.</p>
+<div class="paragraph">
+<p>Users that get immediate benefit from the "reftable" backend could continue to
+opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
+config. But defaults matter, and we think that overall users will have a better
+experience with less platform-specific quirks when they use the new backend by
+default.</p>
+</div>
+<div class="paragraph">
+<p>A prerequisite for this change is that the ecosystem is ready to support the
+"reftable" format. Most importantly, alternative implementations of Git like
+JGit, libgit2 and Gitoxide need to support it.</p>
+</div>
+</li>
+</ul>
+</div>
+</li>
 </ul>
 </div>
 </div>
@@ -758,7 +825,7 @@ <h2 id="_superseded_features_that_will_not_be_deprecated">Superseded features th
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-06-30 16:59:08 -0700
+Last updated 2025-07-14 12:11:05 -0700
 </div>
 </div>
 </body>

RelNotes/2.51.0.adoc

@@ -40,6 +40,13 @@ UI, Workflows & Features
    client, instead of retrying, it skipped it by mistake, which has
    been corrected.
 
+ * The reftable ref backend has matured enough; Git 3.0 will make it
+   the default format in a newly created repositories by default.
+
+ * "netrc" credential helper has been improved to understand textual
+   service names (like smtp) in addition to the numeric port numbers
+   (like 25).
+
 
 Performance, Internal Implementation, Development Support etc.
 --------------------------------------------------------------
@@ -62,10 +69,26 @@ Performance, Internal Implementation, Development Support etc.
 
  * A lot of stale stuff has been removed from the contrib/ hierarchy.
 
+ * "git push" and "git fetch" are taught to update refs in batches to
+   gain performance.
+
+ * Some code paths in the "git prune" used to ignore passed in
+   repository object and used the_repository singleton instance
+   instead, which has been corrected.
+
+ * Update ".clang-format" and ".editorconfig" to match our style guide
+   a bit better.
+
+ * "make coccicheck" succeeds even when spatch made suggestions, which
+   has been updated to fail in such a case.
+
 
 Fixes since v2.50
 -----------------
 
+Unless otherwise noted, all the changes in 2.50.X maintenance track,
+including security updates, are included in this release.
+
  * A memory-leak in an error code path has been plugged.
    (merge 7082da85cb ly/commit-graph-graph-write-leakfix later to maint).
 
@@ -111,8 +134,32 @@ Fixes since v2.50
  * Remove unnecessary check from "git daemon" code.
    (merge 0c856224d2 cb/daemon-fd-check-fix later to maint).
 
- * Leakfix.
-   (merge b0e9d25865 jk/fix-leak-send-pack later to maint).
+ * Use of sysctl() system call to learn the total RAM size used on
+   BSDs has been corrected.
+   (merge 781c1cf571 cb/total-ram-bsd-fix later to maint).
+
+ * Drop FreeBSD 4 support and declare that we support only FreeBSD 12
+   or later, which has memmem() supported.
+   (merge 0392f976a7 bs/config-mak-freebsd later to maint).
+
+ * A diff-filter with negative-only specification like "git log
+   --diff-filter=d" did not trigger correctly, which has been fixed.
+   (merge 375ac087c5 jk/all-negative-diff-filter-fix later to maint).
+
+ * A failure to open the index file for writing due to conflicting
+   access did not state what went wrong, which has been corrected.
+   (merge 9455397a5c hy/read-cache-lock-error-fix later to maint).
+
+ * Tempfile removal fix in the codepath to sign commits with SSH keys.
+   (merge 4498127b04 re/ssh-sign-buffer-fix later to maint).
+
+ * Code and test clean-up around string-list API.
+   (merge 6e5b26c3ff sj/string-list later to maint).
+
+ * "git apply -N" should start from the current index and register
+   only new files, but it instead started from an empty index, which
+   has been corrected.
+   (merge 2b49d97fcb rp/apply-intent-to-add-fix later to maint).
 
  * Other code cleanup, docfix, build fix, etc.
    (merge b257adb571 lo/my-first-ow-doc-update later to maint).
@@ -130,3 +177,9 @@ Fixes since v2.50
    (merge ff73f375bb jg/mailinfo-leakfix later to maint).
    (merge 996f14c02b jj/doc-branch-markup-fix later to maint).
    (merge 1e77de1864 cb/ci-freebsd-update-to-14.3 later to maint).
+   (merge b0e9d25865 jk/fix-leak-send-pack later to maint).
+   (merge f3a9558c8c bs/remote-helpers-doc-markup-fix later to maint).
+   (merge c4e9775c60 kh/doc-config-subcommands later to maint).
+   (merge de404249ab ps/perlless-test-fixes later to maint).
+   (merge 953049eed8 ts/merge-orig-head-doc-fix later to maint).
+   (merge 0c83bbc704 rj/freebsd-sysinfo-build-fix later to maint).

git-apply.adoc

@@ -75,13 +75,14 @@ OPTIONS
 	tree. If `--check` is in effect, merely check that it would
 	apply cleanly to the index entry.
 
+-N::
 --intent-to-add::
 	When applying the patch only to the working tree, mark new
 	files to be added to the index later (see `--intent-to-add`
-	option in linkgit:git-add[1]). This option is ignored unless
-	running in a Git repository and `--index` is not specified.
-	Note that `--index` could be implied by other options such
-	as `--cached` or `--3way`.
+	option in linkgit:git-add[1]). This option is ignored if
+	`--index` or `--cached` are used, and has no effect outside a Git
+	repository. Note that `--index` could be implied by other options
+	such as `--3way`.
 
 -3::
 --3way::

git-apply.html

@@ -535,14 +535,15 @@ <h2 id="_options">OPTIONS</h2>
 tree. If <code>--check</code> is in effect, merely check that it would
 apply cleanly to the index entry.</p>
 </dd>
+<dt class="hdlist1">-N</dt>
 <dt class="hdlist1">--intent-to-add</dt>
 <dd>
 <p>When applying the patch only to the working tree, mark new
 files to be added to the index later (see <code>--intent-to-add</code>
-option in <a href="git-add.html">git-add(1)</a>). This option is ignored unless
-running in a Git repository and <code>--index</code> is not specified.
-Note that <code>--index</code> could be implied by other options such
-as <code>--cached</code> or <code>--3way</code>.</p>
+option in <a href="git-add.html">git-add(1)</a>). This option is ignored if
+<code>--index</code> or <code>--cached</code> are used, and has no effect outside a Git
+repository. Note that <code>--index</code> could be implied by other options
+such as <code>--3way</code>.</p>
 </dd>
 <dt class="hdlist1">-3</dt>
 <dt class="hdlist1">--3way</dt>
@@ -844,7 +845,7 @@ <h2 id="_git">GIT</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-02-14 21:38:14 -0800
+Last updated 2025-07-14 12:11:05 -0700
 </div>
 </div>
 </body>

git-config.adoc

@@ -10,9 +10,9 @@ SYNOPSIS
 --------
 [verse]
 'git config list' [<file-option>] [<display-option>] [--includes]
-'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>
-'git config set' [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>
-'git config unset' [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>
+'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>
+'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
+'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
 'git config rename-section' [<file-option>] <old-name> <new-name>
 'git config remove-section' [<file-option>] <name>
 'git config edit' [<file-option>]
@@ -26,7 +26,7 @@ escaped.
 
 Multiple lines can be added to an option by using the `--append` option.
 If you want to update or unset an option which can occur on multiple
-lines, a `value-pattern` (which is an extended regular expression,
+lines, `--value=<pattern>` (which is an extended regular expression,
 unless the `--fixed-value` option is given) needs to be given.  Only the
 existing values that match the pattern are updated or unset.  If
 you want to handle the lines that do *not* match the pattern, just
@@ -109,7 +109,7 @@ OPTIONS
 
 --replace-all::
 	Default behavior is to replace at most one line. This replaces
-	all lines matching the key (and optionally the `value-pattern`).
+	all lines matching the key (and optionally `--value=<pattern>`).
 
 --append::
 	Adds a new line to the option without altering any existing
@@ -200,11 +200,19 @@ See also <<FILES>>.
 	section in linkgit:gitrevisions[7] for a more complete list of
 	ways to spell blob names.
 
+`--value=<pattern>`::
+`--no-value`::
+	With `get`, `set`, and `unset`, match only against
+	_<pattern>_. The pattern is an extended regular expression unless
+	`--fixed-value` is given.
++
+Use `--no-value` to unset _<pattern>_.
+
 --fixed-value::
-	When used with the `value-pattern` argument, treat `value-pattern` as
+	When used with `--value=<pattern>`, treat _<pattern>_ as
 	an exact string instead of a regular expression. This will restrict
 	the name/value pairs that are matched to only those where the value
-	is exactly equal to the `value-pattern`.
+	is exactly equal to _<pattern>_.
 
 --type <type>::
   'git config' will ensure that any input or output is valid under the given
@@ -259,6 +267,12 @@ Valid `<type>`'s include:
 	Output only the names of config variables for `list` or
 	`get`.
 
+`--show-names`::
+`--no-show-names`::
+	With `get`, show config keys in addition to their values. The
+	default is `--no-show-names` unless `--url` is given and there
+	are no subsections in _<name>_.
+
 --show-origin::
 	Augment the output of all queried config options with the
 	origin type (file, standard input, blob, command line) and