Documentation/BreakingChanges.txt - jrn/git - Git at Google

 = 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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
 <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. <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. <xmqqttjazwwa.fsf@gitster.g>,
 <xmqqleeubork.fsf@gitster.g>,
 <112b6568912a6de6672bf5592c3a718e@manjaro.org>.
	= 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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
	<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
	<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. <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. <xmqqttjazwwa.fsf@gitster.g>,
	<xmqqleeubork.fsf@gitster.g>,
	<112b6568912a6de6672bf5592c3a718e@manjaro.org>.