Autogenerated HTML docs for v2.45.2-606-g900514

BreakingChanges.txt

@@ -0,0 +1,135 @@
+= Upcoming breaking changes
+
+The Git project aims to ensure backwards compatibility to the best extent
+possible. Minor releases will not break backwards compatibility unless there is
+a very strong reason to do so, like for example a security vulnerability.
+
+Regardless of that, due to the age of the Git project, it is only natural to
+accumulate a backlog of backwards-incompatible changes that will eventually be
+required to keep the project aligned with a changing world. These changes fall
+into several categories:
+
+* Changes to long established defaults.
+* Concepts that have been replaced with a superior design.
+* Concepts, commands, configuration or options that have been lacking in major
+  ways and that cannot be fixed and which will thus be removed without any
+  replacement.
+
+Explicitly not included in this list are fixes to minor bugs that may cause a
+change in user-visible behavior.
+
+The Git project irregularly releases breaking versions that deliberately break
+backwards compatibility with older versions. This is done to ensure that Git
+remains relevant, safe and maintainable going forward. The release cadence of
+breaking versions is typically measured in multiple years. We had the following
+major breaking releases in the past:
+
+* Git 1.6.0, released in August 2008.
+* Git 2.0, released in May 2014.
+
+We use <major>.<minor> release numbers these days, starting from Git 2.0. For
+future releases, our plan is to increment <major> in the release number when we
+make the next breaking release. Before Git 2.0, the release numbers were
+1.<major>.<minor> with the intention to increment <major> for "usual" breaking
+releases, reserving the jump to Git 2.0 for really large backward-compatibility
+breaking changes.
+
+The intent of this document is to track upcoming deprecations for future
+breaking releases. Furthermore, this document also tracks what will _not_ be
+deprecated. This is done such that the outcome of discussions document both
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
+where the deprecation was discussed. These references use message-IDs, which
+can visited via
+
+  https://lore.kernel.org/git/$message_id/
+
+to see the message and its surrounding discussion. Such a reference is there to
+make it easier for you to find how the project reached consensus on the
+described item back then.
+
+This is a living document as the environment surrounding the project changes
+over time. If circumstances change, an earlier decision to deprecate or change
+something may need to be revisited from time to time. So do not take items on
+this list to mean "it is settled, do not waste our time bringing it up again".
+
+== Git 3.0
+
+The following subsections document upcoming breaking changes for Git 3.0. There
+is no planned release date for this breaking version yet.
+
+Proposed changes and removals only include items which are "ready" to be done.
+In other words, this is not supposed to be a wishlist of features that should
+be changed to or replaced in case the alternative was implemented already.
+
+=== Changes
+
+* The default hash function for new repositories will be changed from "sha1"
+  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
+  recommended against in FIPS 140-2 and similar certifications. Furthermore,
+  there are practical attacks on SHA-1 that weaken its cryptographic properties:
++
+  ** The SHAppening (2015). The first demonstration of a practical attack
+     against SHA-1 with 2^57 operations.
+  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
+  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
+     attacks with 2^68 operations.
+  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
+     operations.
++
+While we have protections in place against known attacks, it is expected
+that more attacks against SHA-1 will be found by future research. Paired
+with the ever-growing capability of hardware, it is only a matter of time
+before SHA-1 will be considered broken completely. We want to be prepared
+and will thus change the default hash algorithm to "sha256" for newly
+initialized repositories.
++
+An important requirement for this change is that the ecosystem is ready to
+support the "sha256" object format. This includes popular Git libraries,
+applications and forges.
++
+There is no plan to deprecate the "sha1" object format at this point in time.
++
+Cf. <[email protected]>,
+<[email protected]>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
+=== Removals
+
+* Support for grafting commits has long been superseded by git-replace(1).
+  Grafts are inferior to replacement refs:
++
+  ** Grafts are a local-only mechanism and cannot be shared across
+     repositories.
+  ** Grafts can lead to hard-to-diagnose problems when transferring objects
+     between repositories.
++
+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
+info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <[email protected]>.
+
+== Superseded features that will not be deprecated
+
+Some features have gained newer replacements that aim to improve the design in
+certain ways. The fact that there is a replacement does not automatically mean
+that the old way of doing things will eventually be removed. This section tracks
+those features with newer alternatives.
+
+* The features git-checkout(1) offers are covered by the pair of commands
+  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
+  widespread, and it is not expected that this will change anytime soon, all
+  three commands will stay.
++
+This decision may get revisited in case we ever figure out that there are
+almost no users of any of the commands anymore.
++
+Cf. <[email protected]>,
+<[email protected]>,
+<[email protected]>.

DecisionMaking.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>Decision-Making Process in the Git Project</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div class="sect1">

MyFirstContribution.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>My First Contribution to the Git Project</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div class="sect1">

MyFirstObjectWalk.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>My First Object Walk</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div class="sect1">

RelNotes/2.46.0.txt

@@ -70,6 +70,21 @@ UI, Workflows & Features
    files backend for its ref storage to use the reftable backend, with
    limitations.
 
+ * "git diff --exit-code --ext-diff" learned to take the exit status
+   of the external diff driver into account when deciding the exit
+   status of the overall "git diff" invocation when configured to do
+   so.
+
+ * "git update-ref --stdin" learned to handle transactional updates of
+   symbolic-refs.
+
+ * "git format-patch --interdiff" for multi-patch series learned to
+   turn on cover letters automatically (unless told never to enable
+   cover letter with "--no-cover-letter" and such).
+
+ * The "--heads" option of "ls-remote" and "show-ref" has been been
+   deprecated; "--branches" replaces "--heads".
+
 
 Performance, Internal Implementation, Development Support etc.
 
@@ -149,6 +164,15 @@ Performance, Internal Implementation, Development Support etc.
 
  * Building with "-Werror -Wwrite-strings" is now supported.
 
+ * To help developers, the build procedure now allows builders to use
+   CFLAGS_APPEND to specify additional CFLAGS.
+
+ * "oidtree" tests were rewritten to use the unit test framework.
+
+ * The structure of the document that records longer-term project
+   decisions to deprecate/remove/update various behaviour has been
+   outlined.
+
 
 Fixes since v2.45
 -----------------
@@ -273,6 +297,15 @@ Fixes since v2.45
  * A leak in "git imap-send" that somehow escapes LSan has been
    plugged.
 
+ * Setting core.abbrev too early before the repository set-up
+   (typically in "git clone") caused segfault, which as been
+   corrected.
+
+ * When the user adds to "git rebase -i" instruction to "pick" a merge
+   commit, the error experience is not pleasant.  Such an error is now
+   caught earlier in the process that parses the todo list.
+   (merge 4c063c82e9 pw/rebase-i-error-message later to maint).
+
  * Other code cleanup, docfix, build fix, etc.
    (merge a5a4cb7b27 rs/diff-parseopts-cleanup later to maint).
    (merge 55702c543e fa/p4-error later to maint).
@@ -283,3 +316,5 @@ Fixes since v2.45
    (merge 7150f140f9 mt/t0211-typofix later to maint).
    (merge d424488901 jc/rev-parse-fatal-doc later to maint).
    (merge 36d900d2b0 rs/difftool-env-simplify later to maint).
+   (merge e83055ecb0 ds/doc-add-interactive-singlekey later to maint).
+   (merge f1160393c1 ds/ahead-behind-fix later to maint).

ReviewingGuidelines.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>Reviewing Patches in the Git Project</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div class="sect1">

SubmittingPatches.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>Submitting Patches</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div class="sect1">

ToolsForGit.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>Tools for developing Git</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div class="sect1">

diff-options.txt

@@ -820,6 +820,11 @@ ifndef::git-log[]
 
 --quiet::
 	Disable all output of the program. Implies `--exit-code`.
+	Disables execution of external diff helpers whose exit code
+	is not trusted, i.e. their respective configuration option
+	`diff.trustExitCode` or `diff.<driver>.trustExitCode` or
+	environment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is
+	false.
 endif::git-log[]
 endif::git-format-patch[]
 

everyday.html

@@ -735,7 +735,7 @@
 <body class="article">
 <div id="header">
 <h1>Everyday Git With 20 Commands Or So</h1>
-<span id="revdate">2024-06-17</span>
+<span id="revdate">2024-06-20</span>
 </div>
 <div id="content">
 <div id="preamble">

git-config.html

@@ -2378,6 +2378,14 @@ <h3 id="_variables">Variables</h3>
 </p>
 </dd>
 <dt class="hdlist1">
+rebaseTodoError
+</dt>
+<dd>
+<p>
+                Shown when there is an error after editing the rebase todo list.
+</p>
+</dd>
+<dt class="hdlist1">
 refSyntax
 </dt>
 <dd>
@@ -5032,6 +5040,20 @@ <h3 id="_variables">Variables</h3>
 </p>
 </dd>
 <dt class="hdlist1">
+diff.trustExitCode
+</dt>
+<dd>
+<p>
+        If this boolean value is set to true then the
+        <code>diff.external</code> command is expected to return exit code
+        0 if it considers the input files to be equal or 1 if it
+        considers them to be different, like <code>diff(1)</code>.
+        If it is set to false, which is the default, then the command
+        is expected to return exit code 0 regardless of equality.
+        Any other exit code causes Git to report a fatal error.
+</p>
+</dd>
+<dt class="hdlist1">
 diff.ignoreSubmodules
 </dt>
 <dd>
@@ -5214,6 +5236,20 @@ <h3 id="_variables">Variables</h3>
 </p>
 </dd>
 <dt class="hdlist1">
+diff.&lt;driver&gt;.trustExitCode
+</dt>
+<dd>
+<p>
+        If this boolean value is set to true then the
+        <code>diff.&lt;driver&gt;.command</code> command is expected to return exit code
+        0 if it considers the input files to be equal or 1 if it
+        considers them to be different, like <code>diff(1)</code>.
+        If it is set to false, which is the default, then the command
+        is expected to return exit code 0 regardless of equality.
+        Any other exit code causes Git to report a fatal error.
+</p>
+</dd>
+<dt class="hdlist1">
 diff.&lt;driver&gt;.xfuncname
 </dt>
 <dd>
@@ -8168,10 +8204,10 @@ <h3 id="_variables">Variables</h3>
 </dt>
 <dd>
 <p>
-        In interactive commands, allow the user to provide one-letter
-        input with a single key (i.e., without hitting enter).
-        Currently this is used by the <code>--patch</code> mode of
-        <a href="git-add.html">git-add(1)</a>, <a href="git-checkout.html">git-checkout(1)</a>,
+        When set to true, allow the user to provide one-letter input
+        with a single key (i.e., without hitting the Enter key) in
+        interactive commands.  This is currently used by the <code>--patch</code>
+        mode of <a href="git-add.html">git-add(1)</a>, <a href="git-checkout.html">git-checkout(1)</a>,
         <a href="git-restore.html">git-restore(1)</a>, <a href="git-commit.html">git-commit(1)</a>,
         <a href="git-reset.html">git-reset(1)</a>, and <a href="git-stash.html">git-stash(1)</a>.
 </p>

git-diff-files.html

@@ -1939,6 +1939,11 @@ <h2 id="_options">OPTIONS</h2>
 <dd>
 <p>
         Disable all output of the program. Implies <code>--exit-code</code>.
+        Disables execution of external diff helpers whose exit code
+        is not trusted, i.e. their respective configuration option
+        <code>diff.trustExitCode</code> or <code>diff.&lt;driver&gt;.trustExitCode</code> or
+        environment variable <code>GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE</code> is
+        false.
 </p>
 </dd>
 <dt class="hdlist1">

git-diff-index.html

@@ -1940,6 +1940,11 @@ <h2 id="_options">OPTIONS</h2>
 <dd>
 <p>
         Disable all output of the program. Implies <code>--exit-code</code>.
+        Disables execution of external diff helpers whose exit code
+        is not trusted, i.e. their respective configuration option
+        <code>diff.trustExitCode</code> or <code>diff.&lt;driver&gt;.trustExitCode</code> or
+        environment variable <code>GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE</code> is
+        false.
 </p>
 </dd>
 <dt class="hdlist1">

git-diff-tree.html

@@ -1941,6 +1941,11 @@ <h2 id="_options">OPTIONS</h2>
 <dd>
 <p>
         Disable all output of the program. Implies <code>--exit-code</code>.
+        Disables execution of external diff helpers whose exit code
+        is not trusted, i.e. their respective configuration option
+        <code>diff.trustExitCode</code> or <code>diff.&lt;driver&gt;.trustExitCode</code> or
+        environment variable <code>GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE</code> is
+        false.
 </p>
 </dd>
 <dt class="hdlist1">