diff --git a/BreakingChanges.txt b/BreakingChanges.txt new file mode 100644 index 000000000..0532bfcf7 --- /dev/null +++ b/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 . release numbers these days, starting from Git 2.0. For +future releases, our plan is to increment in the release number when we +make the next breaking release. Before Git 2.0, the release numbers were +1.. with the intention to increment 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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, +. + +=== 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. <20140304174806.GA11561@sigill.intra.peff.net>. + +== 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. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. diff --git a/DecisionMaking.html b/DecisionMaking.html index 9e7eb6fd0..b08c8d9af 100644 --- a/DecisionMaking.html +++ b/DecisionMaking.html @@ -735,7 +735,7 @@
diff --git a/MyFirstContribution.html b/MyFirstContribution.html index ebdc4c602..2dd5248f1 100644 --- a/MyFirstContribution.html +++ b/MyFirstContribution.html @@ -735,7 +735,7 @@
diff --git a/MyFirstObjectWalk.html b/MyFirstObjectWalk.html index c92fefffa..e3b53144d 100644 --- a/MyFirstObjectWalk.html +++ b/MyFirstObjectWalk.html @@ -735,7 +735,7 @@
diff --git a/RelNotes/2.46.0.txt b/RelNotes/2.46.0.txt index 58fde28f5..182f4c7e6 100644 --- a/RelNotes/2.46.0.txt +++ b/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). diff --git a/ReviewingGuidelines.html b/ReviewingGuidelines.html index 53757e1a1..c8159bb02 100644 --- a/ReviewingGuidelines.html +++ b/ReviewingGuidelines.html @@ -735,7 +735,7 @@
diff --git a/SubmittingPatches.html b/SubmittingPatches.html index a45927880..2f724cff6 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html @@ -735,7 +735,7 @@
diff --git a/ToolsForGit.html b/ToolsForGit.html index 8fd8f206a..d60ed0d5e 100644 --- a/ToolsForGit.html +++ b/ToolsForGit.html @@ -735,7 +735,7 @@
diff --git a/diff-options.txt b/diff-options.txt index c7df20e57..cd0b81adb 100644 --- a/diff-options.txt +++ b/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..trustExitCode` or + environment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is + false. endif::git-log[] endif::git-format-patch[] diff --git a/everyday.html b/everyday.html index 7693c8186..907e0f10b 100644 --- a/everyday.html +++ b/everyday.html @@ -735,7 +735,7 @@
diff --git a/git-config.html b/git-config.html index 43585e7fe..a6660faa0 100644 --- a/git-config.html +++ b/git-config.html @@ -2378,6 +2378,14 @@

Variables

+rebaseTodoError +
+
+

+ Shown when there is an error after editing the rebase todo list. +

+
+
refSyntax
@@ -5032,6 +5040,20 @@

Variables

+diff.trustExitCode +
+
+

+ If this boolean value is set to true then the + diff.external 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 diff(1). + 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. +

+
+
diff.ignoreSubmodules
@@ -5214,6 +5236,20 @@

Variables

+diff.<driver>.trustExitCode +
+
+

+ If this boolean value is set to true then the + diff.<driver>.command 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 diff(1). + 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. +

+
+
diff.<driver>.xfuncname
@@ -8168,10 +8204,10 @@

Variables

- 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 --patch mode of - git-add(1), git-checkout(1), + 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 --patch + mode of git-add(1), git-checkout(1), git-restore(1), git-commit(1), git-reset(1), and git-stash(1).

diff --git a/git-diff-files.html b/git-diff-files.html index ebbb2b0f8..717afaf0e 100644 --- a/git-diff-files.html +++ b/git-diff-files.html @@ -1939,6 +1939,11 @@

OPTIONS

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.

diff --git a/git-diff-index.html b/git-diff-index.html index befc27317..ea32fe01e 100644 --- a/git-diff-index.html +++ b/git-diff-index.html @@ -1940,6 +1940,11 @@

OPTIONS

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.

diff --git a/git-diff-tree.html b/git-diff-tree.html index 43c570537..25fac3595 100644 --- a/git-diff-tree.html +++ b/git-diff-tree.html @@ -1941,6 +1941,11 @@

OPTIONS

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.

diff --git a/git-diff.html b/git-diff.html index 84d24cc9a..b276a10c4 100644 --- a/git-diff.html +++ b/git-diff.html @@ -2081,6 +2081,11 @@

OPTIONS

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.

@@ -3155,6 +3160,20 @@

CONFIGURATION

+diff.trustExitCode +
+
+

+ If this boolean value is set to true then the + diff.external 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 diff(1). + 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. +

+
+
diff.ignoreSubmodules
@@ -3337,6 +3356,20 @@

CONFIGURATION

+diff.<driver>.trustExitCode +
+
+

+ If this boolean value is set to true then the + diff.<driver>.command 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 diff(1). + 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. +

+
+
diff.<driver>.xfuncname
diff --git a/git-ls-remote.html b/git-ls-remote.html index 90781ddd3..20065e84d 100644 --- a/git-ls-remote.html +++ b/git-ls-remote.html @@ -749,7 +749,7 @@

NAME

SYNOPSIS

-
git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]
+
git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]
               [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
               [--symref] [<repository> [<patterns>…]]

 

@@ -768,10 +768,10 @@ 
OPTIONS

 

 

 

--h
+-b
 

 

---heads
+--branches
 

 

 -t
@@ -781,10 +781,12 @@ 
OPTIONS

 

 

 

-        Limit to only refs/heads and refs/tags, respectively.
+        Limit to only local branches and local tags, respectively.
         These options are not mutually exclusive; when given
         both, references stored in refs/heads and refs/tags are
-        displayed.  Note that git ls-remote -h used without
+        displayed.  Note that --heads and -h are deprecated
+        synonyms for --branches and -b and may be removed in
+        the future.  Also note that git ls-remote -h used without
         anything else on the command line gives help, consistent
         with other git subcommands.
 

@@ -987,7 +989,7 @@ 
GIT

 
 
diff --git a/git-ls-remote.txt b/git-ls-remote.txt
index 1c4f696ab..76c86c3ce 100644
--- a/git-ls-remote.txt
+++ b/git-ls-remote.txt
@@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository
 SYNOPSIS
 --------
 [verse]
-'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]
+'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=]
 	      [-q | --quiet] [--exit-code] [--get-url] [--sort=]
 	      [--symref] [ [...]]
 
@@ -21,14 +21,16 @@ commit IDs.
 
 OPTIONS
 -------
--h::
---heads::
+-b::
+--branches::
 -t::
 --tags::
-	Limit to only refs/heads and refs/tags, respectively.
+	Limit to only local branches and local tags, respectively.
 	These options are _not_ mutually exclusive; when given
 	both, references stored in refs/heads and refs/tags are
-	displayed.  Note that `git ls-remote -h` used without
+	displayed.  Note that `--heads` and `-h` are deprecated
+	synonyms for `--branches` and `-b` and may be removed in
+	the future.  Also note that `git ls-remote -h` used without
 	anything else on the command line gives help, consistent
 	with other git subcommands.
 
diff --git a/git-remote-helpers.html b/git-remote-helpers.html
index 0a80d0a50..45733d93f 100644
--- a/git-remote-helpers.html
+++ b/git-remote-helpers.html
@@ -735,7 +735,7 @@
 
 
 

 

diff --git a/git-show-ref.html b/git-show-ref.html
index 2fac233e2..f4c016991 100644
--- a/git-show-ref.html
+++ b/git-show-ref.html
@@ -750,8 +750,8 @@ 
SYNOPSIS

 

 

 
git show-ref [--head] [-d | --dereference]
-             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
-             [--heads] [--] [<pattern>…]
+             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]
+             [--] [<pattern>…]
 git show-ref --verify [-q | --quiet] [-d | --dereference]
              [-s | --hash[=<n>]] [--abbrev[=<n>]]
              [--] [<ref>…]
@@ -792,16 +792,18 @@ 
OPTIONS

 

 

 

---heads
+--branches
 

 

 --tags
 

 

 

-        Limit to "refs/heads" and "refs/tags", respectively.  These options
+        Limit to local branches and local tags, respectively.  These options
         are not mutually exclusive; when given both, references stored in
-        "refs/heads" and "refs/tags" are displayed.
+        "refs/heads" and "refs/tags" are displayed.  Note that --heads
+        is a deprecated synonym for --branches and may be removed
+        in the future.
 

 

 

@@ -928,7 +930,7 @@ 
OUTPUT

 
For example,

 

 

-
$ git show-ref --heads --hash
+
$ git show-ref --branches --hash
 2e3ba0114a1f52b47df29743d6915d056be13278
 185008ae97960c8d551adcd9e23565194651b5d1
 03adf42c988195b50e1a1935ba5fcbc39b2b029b
@@ -966,8 +968,8 @@ 
EXAMPLES

 
to check whether a particular branch exists or not (notice how we don’t
 actually want to show any results, and we want to use the full refname for it
 in order to not trigger the problem with ambiguous partial matches).

-
To show only tags, or only proper branch heads, use --tags and/or --heads
-respectively (using both means that it shows tags and heads, but not other
+
To show only tags, or only proper branch heads, use --tags and/or --branches
+respectively (using both means that it shows tags and branches, but not other
 random references under the refs/ subdirectory).

 
To do automatic tag object dereferencing, use the -d or --dereference
 flag, so you can do

@@ -1004,7 +1006,7 @@ 
GIT

 
 
diff --git a/git-show-ref.txt b/git-show-ref.txt
index ba7574700..616d91965 100644
--- a/git-show-ref.txt
+++ b/git-show-ref.txt
@@ -9,8 +9,8 @@ SYNOPSIS
 --------
 [verse]
 'git show-ref' [--head] [-d | --dereference]
-	     [-s | --hash[=]] [--abbrev[=]] [--tags]
-	     [--heads] [--] [...]
+	     [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]
+	     [--] [...]
 'git show-ref' --verify [-q | --quiet] [-d | --dereference]
 	     [-s | --hash[=]] [--abbrev[=]]
 	     [--] [...]
@@ -45,12 +45,14 @@ OPTIONS
 
 	Show the HEAD reference, even if it would normally be filtered out.
 
---heads::
+--branches::
 --tags::
 
-	Limit to "refs/heads" and "refs/tags", respectively.  These options
+	Limit to local branches and local tags, respectively.  These options
 	are not mutually exclusive; when given both, references stored in
-	"refs/heads" and "refs/tags" are displayed.
+	"refs/heads" and "refs/tags" are displayed.  Note that `--heads`
+	is a deprecated synonym for `--branches` and may be removed
+	in the future.
 
 -d::
 --dereference::
@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format:
 For example,
 
 -----------------------------------------------------------------------------
-$ git show-ref --heads --hash
+$ git show-ref --branches --hash
 2e3ba0114a1f52b47df29743d6915d056be13278
 185008ae97960c8d551adcd9e23565194651b5d1
 03adf42c988195b50e1a1935ba5fcbc39b2b029b
@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't
 actually want to show any results, and we want to use the full refname for it
 in order to not trigger the problem with ambiguous partial matches).
 
-To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
-respectively (using both means that it shows tags and heads, but not other
+To show only tags, or only proper branch heads, use `--tags` and/or `--branches`
+respectively (using both means that it shows tags and branches, but not other
 random references under the refs/ subdirectory).
 
 To do automatic tag object dereferencing, use the `-d` or `--dereference`
diff --git a/git-update-ref.html b/git-update-ref.html
index da088fce2..95686917b 100644
--- a/git-update-ref.html
+++ b/git-update-ref.html
@@ -806,6 +806,10 @@ 
DESCRIPTION

 create SP <ref> SP <new-oid> LF
 delete SP <ref> [SP <old-oid>] LF
 verify SP <ref> [SP <old-oid>] LF
+symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
+symref-create SP <ref> SP <new-target> LF
+symref-delete SP <ref> [SP <old-target>] LF
+symref-verify SP <ref> [SP <old-target>] LF
 option SP <opt> LF
 start LF
 prepare LF
@@ -826,6 +830,10 @@ 
DESCRIPTION

 create SP <ref> NUL <new-oid> NUL
 delete SP <ref> NUL [<old-oid>] NUL
 verify SP <ref> NUL [<old-oid>] NUL
+symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
+symref-create SP <ref> NUL <new-target> NUL
+symref-delete SP <ref> [NUL <old-target>] NUL
+symref-verify SP <ref> [NUL <old-target>] NUL
 option SP <opt> NUL
 start NUL
 prepare NUL
@@ -868,6 +876,16 @@ 
DESCRIPTION
+symref-update +
+
+

+ Set <ref> to <new-target> after verifying <old-target> or <old-oid>, + if given. Specify a zero <old-oid> to ensure that the ref does not + exist before the update. +

+
+
verify
@@ -876,6 +894,29 @@

DESCRIPTION

<old-oid> is zero or missing, the ref must not exist.

+
+

symref-create: + Create symbolic ref <ref> with <new-target> after verifying + it does not exist.

+
+
+symref-delete +
+
+

+ Delete <ref> after verifying it exists with <old-target>, if given. +

+
+
+symref-verify +
+
+

+ Verify symbolic <ref> against <old-target> but do not change it. + If <old-target> is missing, the ref must not exist. Can only be + used in no-deref mode. +

+
option
@@ -974,7 +1015,7 @@

GIT

diff --git a/git-update-ref.txt b/git-update-ref.txt index 374a2ebd2..afcf33cf6 100644 --- a/git-update-ref.txt +++ b/git-update-ref.txt @@ -65,6 +65,10 @@ performs all modifications together. Specify commands of the form: create SP SP LF delete SP [SP ] LF verify SP [SP ] LF + symref-update SP SP [SP (ref SP | oid SP )] LF + symref-create SP SP LF + symref-delete SP [SP ] LF + symref-verify SP [SP ] LF option SP LF start LF prepare LF @@ -86,6 +90,10 @@ quoting: create SP NUL NUL delete SP NUL [] NUL verify SP NUL [] NUL + symref-update SP NUL [NUL (ref NUL | oid NUL )] NUL + symref-create SP NUL NUL + symref-delete SP [NUL ] NUL + symref-verify SP [NUL ] NUL option SP NUL start NUL prepare NUL @@ -113,10 +121,27 @@ delete:: Delete after verifying it exists with , if given. If given, may not be zero. +symref-update:: + Set to after verifying or , + if given. Specify a zero to ensure that the ref does not + exist before the update. + verify:: Verify against but do not change it. If is zero or missing, the ref must not exist. +symref-create: + Create symbolic ref with after verifying + it does not exist. + +symref-delete:: + Delete after verifying it exists with , if given. + +symref-verify:: + Verify symbolic against but do not change it. + If is missing, the ref must not exist. Can only be + used in `no-deref` mode. + option:: Modify the behavior of the next command naming a . The only valid option is `no-deref` to avoid dereferencing diff --git a/git.html b/git.html index 89bb076c3..5de610ea2 100644 --- a/git.html +++ b/git.html @@ -3187,6 +3187,20 @@

Git Diffs

GIT_DIFF_PATH_COUNTER and GIT_DIFF_PATH_TOTAL are set.

+GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE +
+
+

+ If this Boolean environment variable is set to true then the + GIT_EXTERNAL_DIFF 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 diff(1). + 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. +

+
+
GIT_DIFF_PATH_COUNTER
@@ -3925,7 +3939,7 @@

GIT

diff --git a/git.txt b/git.txt index a31a70acc..4489e2297 100644 --- a/git.txt +++ b/git.txt @@ -644,6 +644,16 @@ parameter, . For each path `GIT_EXTERNAL_DIFF` is called, two environment variables, `GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set. +`GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE`:: + If this Boolean environment variable is set to true then the + `GIT_EXTERNAL_DIFF` 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 `diff(1)`. + 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. + + `GIT_DIFF_PATH_COUNTER`:: A 1-based counter incremented by one for every path. diff --git a/gitattributes.html b/gitattributes.html index 31f5aaf27..116f063d7 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -1548,6 +1548,10 @@

Defining an external diff driver

with the above configuration, i.e. j-c-diff, with 7 parameters, just like GIT_EXTERNAL_DIFF program is called. See git(1) for details.

+

If the program is able to ignore certain changes (similar to +git diff --ignore-space-change), then also set the option +trustExitCode to true. It is then expected to return exit code 1 if +it finds significant changes and 0 if it doesn’t.

Setting the internal diff algorithm

@@ -2263,7 +2267,7 @@

GIT

diff --git a/gitattributes.txt b/gitattributes.txt index 4338d023d..80cae17f3 100644 --- a/gitattributes.txt +++ b/gitattributes.txt @@ -776,6 +776,11 @@ with the above configuration, i.e. `j-c-diff`, with 7 parameters, just like `GIT_EXTERNAL_DIFF` program is called. See linkgit:git[1] for details. +If the program is able to ignore certain changes (similar to +`git diff --ignore-space-change`), then also set the option +`trustExitCode` to true. It is then expected to return exit code 1 if +it finds significant changes and 0 if it doesn't. + Setting the internal diff algorithm ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html index 785ae5322..30796658e 100644 --- a/howto/coordinate-embargoed-releases.html +++ b/howto/coordinate-embargoed-releases.html @@ -1038,7 +1038,7 @@

Last updated - 2024-06-17 16:43:22 PDT + 2024-06-20 16:27:50 PDT

diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 99da4ae49..cac88a3c9 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html @@ -735,7 +735,7 @@
@@ -939,7 +939,7 @@

Keep authoritative canonical history correct with git pull

diff --git a/howto/maintain-git.html b/howto/maintain-git.html index 011666d5f..03e3b6528 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html @@ -735,7 +735,7 @@
@@ -1479,7 +1479,7 @@

Preparing a "merge-fix"

diff --git a/howto/new-command.html b/howto/new-command.html index 9b8d3776f..ece042923 100644 --- a/howto/new-command.html +++ b/howto/new-command.html @@ -735,7 +735,7 @@
@@ -864,7 +864,7 @@

Integrating a command

diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index 8094b5c24..226b0e185 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html @@ -735,7 +735,7 @@
@@ -896,7 +896,7 @@

How to rebase from an internal branch

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index c06e7cf31..ecb8442a4 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html @@ -735,7 +735,7 @@
@@ -848,7 +848,7 @@

How to rebuild from update hook

diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index 67b1ad729..8521c2286 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html @@ -735,7 +735,7 @@
@@ -881,7 +881,7 @@

How to recover a corrupted blob object

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index 6baefb32c..e95246a34 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html @@ -735,7 +735,7 @@
@@ -1190,7 +1190,7 @@

The adventure continues…

diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index da98aac7e..6fb16aecd 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html @@ -735,7 +735,7 @@
@@ -1026,7 +1026,7 @@

How to revert a faulty merge

diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index fa9f33456..ba1ed1d84 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html @@ -735,7 +735,7 @@
@@ -908,7 +908,7 @@

How to revert an existing commit

diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index 308f6d1f9..4de2360bb 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html @@ -735,7 +735,7 @@
@@ -842,7 +842,7 @@

How to separate topic branches

diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index 60fec7d43..c870367a2 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html @@ -735,7 +735,7 @@
@@ -1072,7 +1072,7 @@

Troubleshooting:

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index 57f95aa52..f7ad45fd3 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html @@ -735,7 +735,7 @@
@@ -931,7 +931,7 @@

How to use the update hook

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 09849c858..d694a8da0 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html @@ -735,7 +735,7 @@
@@ -792,7 +792,7 @@

How to use git-daemon

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index 419a4c0c9..92776e830 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html @@ -735,7 +735,7 @@
@@ -849,7 +849,7 @@

Additional tips

diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index 3206d727a..ec2a1d2dc 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html @@ -735,7 +735,7 @@
@@ -953,7 +953,7 @@

Auditors

diff --git a/technical/api-error-handling.html b/technical/api-error-handling.html index 23221d6ad..9f08cb0e3 100644 --- a/technical/api-error-handling.html +++ b/technical/api-error-handling.html @@ -735,7 +735,7 @@
diff --git a/technical/api-index.html b/technical/api-index.html index a4d328795..03a3a6d7a 100644 --- a/technical/api-index.html +++ b/technical/api-index.html @@ -735,7 +735,7 @@
diff --git a/technical/api-merge.html b/technical/api-merge.html index 6b7adefb3..4d5e5ebe9 100644 --- a/technical/api-merge.html +++ b/technical/api-merge.html @@ -735,7 +735,7 @@
diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html index b6c985890..e38a3dfa0 100644 --- a/technical/api-parse-options.html +++ b/technical/api-parse-options.html @@ -735,7 +735,7 @@
diff --git a/technical/api-simple-ipc.html b/technical/api-simple-ipc.html index 22b76c673..691b9bd5d 100644 --- a/technical/api-simple-ipc.html +++ b/technical/api-simple-ipc.html @@ -735,7 +735,7 @@
diff --git a/technical/api-trace2.html b/technical/api-trace2.html index aca5168e7..597b35ee8 100644 --- a/technical/api-trace2.html +++ b/technical/api-trace2.html @@ -735,7 +735,7 @@
diff --git a/technical/bitmap-format.html b/technical/bitmap-format.html index 7a4a68e64..4754256ba 100644 --- a/technical/bitmap-format.html +++ b/technical/bitmap-format.html @@ -735,7 +735,7 @@
diff --git a/technical/bundle-uri.html b/technical/bundle-uri.html index a048528d5..c5d15732e 100644 --- a/technical/bundle-uri.html +++ b/technical/bundle-uri.html @@ -735,7 +735,7 @@
diff --git a/technical/hash-function-transition.html b/technical/hash-function-transition.html index 45ac0ea3d..3da46efbf 100644 --- a/technical/hash-function-transition.html +++ b/technical/hash-function-transition.html @@ -735,7 +735,7 @@
diff --git a/technical/long-running-process-protocol.html b/technical/long-running-process-protocol.html index c5fc5b0a1..177517733 100644 --- a/technical/long-running-process-protocol.html +++ b/technical/long-running-process-protocol.html @@ -735,7 +735,7 @@
diff --git a/technical/multi-pack-index.html b/technical/multi-pack-index.html index 94916374b..0dd4f5805 100644 --- a/technical/multi-pack-index.html +++ b/technical/multi-pack-index.html @@ -735,7 +735,7 @@
diff --git a/technical/pack-heuristics.html b/technical/pack-heuristics.html index 8f4971288..832b0915e 100644 --- a/technical/pack-heuristics.html +++ b/technical/pack-heuristics.html @@ -735,7 +735,7 @@
diff --git a/technical/parallel-checkout.html b/technical/parallel-checkout.html index 24bd9d73b..506156df9 100644 --- a/technical/parallel-checkout.html +++ b/technical/parallel-checkout.html @@ -735,7 +735,7 @@
diff --git a/technical/partial-clone.html b/technical/partial-clone.html index dfb5960b9..ca20431c5 100644 --- a/technical/partial-clone.html +++ b/technical/partial-clone.html @@ -735,7 +735,7 @@
diff --git a/technical/racy-git.html b/technical/racy-git.html index c4e039766..29e024527 100644 --- a/technical/racy-git.html +++ b/technical/racy-git.html @@ -735,7 +735,7 @@
diff --git a/technical/scalar.html b/technical/scalar.html index bff438d05..04374e6a2 100644 --- a/technical/scalar.html +++ b/technical/scalar.html @@ -735,7 +735,7 @@
diff --git a/technical/send-pack-pipeline.html b/technical/send-pack-pipeline.html index a8122e3b8..809506034 100644 --- a/technical/send-pack-pipeline.html +++ b/technical/send-pack-pipeline.html @@ -735,7 +735,7 @@
diff --git a/technical/shallow.html b/technical/shallow.html index 7ce648d39..80cd27b84 100644 --- a/technical/shallow.html +++ b/technical/shallow.html @@ -735,7 +735,7 @@
diff --git a/technical/trivial-merge.html b/technical/trivial-merge.html index b3abcd15a..f88032a77 100644 --- a/technical/trivial-merge.html +++ b/technical/trivial-merge.html @@ -735,7 +735,7 @@
diff --git a/technical/unit-tests.html b/technical/unit-tests.html index 4b054a282..db66a0e4f 100644 --- a/technical/unit-tests.html +++ b/technical/unit-tests.html @@ -735,7 +735,7 @@
diff --git a/user-manual.html b/user-manual.html index 5ecedbbfd..12905b0ab 100644 --- a/user-manual.html +++ b/user-manual.html @@ -1,5 +1,5 @@ -Git User Manual

Git User Manual

Revision History
2024-06-17

Table of Contents

Introduction
1. Repositories and Branches
How to get a Git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring Git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with Git
Telling Git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public Git repositories
Setting up a public repository
Exporting a Git repository via the Git protocol
Exporting a git repository via HTTP
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository
How to get a Git repository with minimal history
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git rebase
Rewriting a single commit
Reordering or selecting from a patch series
Using interactive rebases
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote-tracking branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How Git stores objects efficiently: pack files
Dangling objects
Recovering from repository corruption
The index
8. Submodules
Pitfalls with submodules
9. Low-level Git operations
Object access and manipulation
The Workflow
working directory → index
index → object database
object database → index
index → working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking Git
Object storage format
A birds-eye view of Git’s source code
11. Git Glossary
Git explained
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual
Todo list

Introduction

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX +Git User Manual

Git User Manual

Revision History
2024-06-20

Table of Contents

Introduction
1. Repositories and Branches
How to get a Git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring Git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with Git
Telling Git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public Git repositories
Setting up a public repository
Exporting a Git repository via the Git protocol
Exporting a git repository via HTTP
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository
How to get a Git repository with minimal history
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git rebase
Rewriting a single commit
Reordering or selecting from a patch series
Using interactive rebases
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote-tracking branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How Git stores objects efficiently: pack files
Dangling objects
Recovering from repository corruption
The index
8. Submodules
Pitfalls with submodules
9. Low-level Git operations
Object access and manipulation
The Workflow
working directory → index
index → object database
object database → index
index → working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking Git
Object storage format
A birds-eye view of Git’s source code
11. Git Glossary
Git explained
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual
Todo list

Introduction

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.

Chapter 1, Repositories and Branches and Chapter 2, Exploring Git history explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for