BreakingChanges.txt

   1 = Upcoming breaking changes
   2
   3 The Git project aims to ensure backwards compatibility to the best extent
   4 possible. Minor releases will not break backwards compatibility unless there is
   5 a very strong reason to do so, like for example a security vulnerability.
   6
   7 Regardless of that, due to the age of the Git project, it is only natural to
   8 accumulate a backlog of backwards-incompatible changes that will eventually be
   9 required to keep the project aligned with a changing world. These changes fall
  10 into several categories:
  11
  12 * Changes to long established defaults.
  13 * Concepts that have been replaced with a superior design.
  14 * Concepts, commands, configuration or options that have been lacking in major
  15   ways and that cannot be fixed and which will thus be removed without any
  16   replacement.
  17
  18 Explicitly not included in this list are fixes to minor bugs that may cause a
  19 change in user-visible behavior.
  20
  21 The Git project irregularly releases breaking versions that deliberately break
  22 backwards compatibility with older versions. This is done to ensure that Git
  23 remains relevant, safe and maintainable going forward. The release cadence of
  24 breaking versions is typically measured in multiple years. We had the following
  25 major breaking releases in the past:
  26
  27 * Git 1.6.0, released in August 2008.
  28 * Git 2.0, released in May 2014.
  29
  30 We use <major>.<minor> release numbers these days, starting from Git 2.0. For
  31 future releases, our plan is to increment <major> in the release number when we
  32 make the next breaking release. Before Git 2.0, the release numbers were
  33 1.<major>.<minor> with the intention to increment <major> for "usual" breaking
  34 releases, reserving the jump to Git 2.0 for really large backward-compatibility
  35 breaking changes.
  36
  37 The intent of this document is to track upcoming deprecations for future
  38 breaking releases. Furthermore, this document also tracks what will _not_ be
  39 deprecated. This is done such that the outcome of discussions document both
  40 when the discussion favors deprecation, but also when it rejects a deprecation.
  41
  42 Items should have a clear summary of the reasons why we do or do not want to
  43 make the described change that can be easily understood without having to read
  44 the mailing list discussions. If there are alternatives to the changed feature,
  45 those alternatives should be pointed out to our users.
  46
  47 All items should be accompanied by references to relevant mailing list threads
  48 where the deprecation was discussed. These references use message-IDs, which
  49 can visited via
  50
  51   https://lore.kernel.org/git/$message_id/
  52
  53 to see the message and its surrounding discussion. Such a reference is there to
  54 make it easier for you to find how the project reached consensus on the
  55 described item back then.
  56
  57 This is a living document as the environment surrounding the project changes
  58 over time. If circumstances change, an earlier decision to deprecate or change
  59 something may need to be revisited from time to time. So do not take items on
  60 this list to mean "it is settled, do not waste our time bringing it up again".
  61
  62 == Procedure
  63
  64 Discussing the desire to make breaking changes, declaring that breaking
  65 changes are made at a certain version boundary, and recording these
  66 decisions in this document, are necessary but not sufficient.
  67 Because such changes are expected to be numerous, and the design and
  68 implementation of them are expected to span over time, they have to
  69 be deployable trivially at such a version boundary.
  70
  71 The breaking changes MUST be guarded with the a compile-time switch,
  72 WITH_BREAKING_CHANGES, to help this process.  When built with it,
  73 the resulting Git binary together with its documentation would
  74 behave as if these breaking changes slated for the next big version
  75 boundary are already in effect.  We may also want to have a CI job
  76 or two to exercise the work-in-progress version of Git with these
  77 breaking changes.
  78
  79
  80 == Git 3.0
  81
  82 The following subsections document upcoming breaking changes for Git 3.0. There
  83 is no planned release date for this breaking version yet.  The early
  84 adopter configuration used for changes for this release is `feature.git3`.
  85
  86 Proposed changes and removals only include items which are "ready" to be done.
  87 In other words, this is not supposed to be a wishlist of features that should
  88 be changed to or replaced in case the alternative was implemented already.
  89
  90 === Changes
  91
  92 * The default hash function for new repositories will be changed from "sha1"
  93   to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
  94   recommended against in FIPS 140-2 and similar certifications. Furthermore,
  95   there are practical attacks on SHA-1 that weaken its cryptographic properties:
  96 +
  97   ** The SHAppening (2015). The first demonstration of a practical attack
  98      against SHA-1 with 2^57 operations.
  99   ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
 100   ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
 101      attacks with 2^68 operations.
 102   ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
 103      operations.
 104 +
 105 While we have protections in place against known attacks, it is expected
 106 that more attacks against SHA-1 will be found by future research. Paired
 107 with the ever-growing capability of hardware, it is only a matter of time
 108 before SHA-1 will be considered broken completely. We want to be prepared
 109 and will thus change the default hash algorithm to "sha256" for newly
 110 initialized repositories.
 111 +
 112 An important requirement for this change is that the ecosystem is ready to
 113 support the "sha256" object format. This includes popular Git libraries,
 114 applications and forges.
 115 +
 116 There is no plan to deprecate the "sha1" object format at this point in time.
 117 +
 118 Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 119 <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
 120 <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
 121
 122 === Removals
 123
 124 * Support for grafting commits has long been superseded by git-replace(1).
 125   Grafts are inferior to replacement refs:
 126 +
 127   ** Grafts are a local-only mechanism and cannot be shared across
 128      repositories.
 129   ** Grafts can lead to hard-to-diagnose problems when transferring objects
 130      between repositories.
 131 +
 132 The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
 133 info/grafts as outdated, 2014-03-05) and will be removed.
 134 +
 135 Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
 136
 137 * The git-pack-redundant(1) command can be used to remove redundant pack files.
 138   The subcommand is unusably slow and the reason why nobody reports it as a
 139   performance bug is suspected to be the absence of users. We have nominated
 140   the command for removal and have started to emit a user-visible warning in
 141   c3b58472be (pack-redundant: gauge the usage before proposing its removal,
 142   2020-08-25) whenever the command is executed.
 143 +
 144 So far there was a single complaint about somebody still using the command, but
 145 that complaint did not cause us to reverse course. On the contrary, we have
 146 doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
 147 escalate deprecation warning to an error, 2023-03-23), the command dies unless
 148 the user passes the `--i-still-use-this` option.
 149 +
 150 There have not been any subsequent complaints, so this command will finally be
 151 removed.
 152 +
 153 Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
 154     <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
 155     <20230323204047.GA9290@coredump.intra.peff.net>,
 156
 157 == Superseded features that will not be deprecated
 158
 159 Some features have gained newer replacements that aim to improve the design in
 160 certain ways. The fact that there is a replacement does not automatically mean
 161 that the old way of doing things will eventually be removed. This section tracks
 162 those features with newer alternatives.
 163
 164 * The features git-checkout(1) offers are covered by the pair of commands
 165   git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
 166   widespread, and it is not expected that this will change anytime soon, all
 167   three commands will stay.
 168 +
 169 This decision may get revisited in case we ever figure out that there are
 170 almost no users of any of the commands anymore.
 171 +
 172 Cf. <xmqqttjazwwa.fsf@gitster.g>,
 173 <xmqqleeubork.fsf@gitster.g>,
 174 <112b6568912a6de6672bf5592c3a718e@manjaro.org>.