You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<divclass="paragraph"><p>Discussing the desire to make breaking changes, declaring that breaking changes are made at a certain version boundary, and recording these decisions in this document, are necessary but not sufficient. Because such changes are expected to be numerous, and the design and implementation of them are expected to span over time, they have to be deployable trivially at such a version boundary, prepared over long time.</p></div>
792
+
<divclass="paragraph"><p>The breaking changes MUST be guarded with the a compile-time switch, WITH_BREAKING_CHANGES, to help this process. When built with it, the resulting Git binary together with its documentation would behave as if these breaking changes slated for the next big version boundary are already in effect. We also have a CI job to exercise the work-in-progress version of Git with these breaking changes.</p></div>
<divclass="paragraph"><p>The following subsections document upcoming breaking changes for Git 3.0. There is no planned release date for this breaking version yet.</p></div>
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:
837
+
</p>
838
+
<divclass="ulist"><ul>
839
+
<li>
840
+
<p>
841
+
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.
842
+
</p>
843
+
</li>
844
+
<li>
845
+
<p>
846
+
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.
847
+
</p>
848
+
</li>
849
+
<li>
850
+
<p>
851
+
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.
852
+
</p>
853
+
</li>
854
+
<li>
855
+
<p>
856
+
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.
857
+
</p>
858
+
</li>
859
+
<li>
860
+
<p>
861
+
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.
862
+
</p>
863
+
</li>
864
+
<li>
865
+
<p>
866
+
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.
867
+
</p>
868
+
</li>
869
+
<li>
870
+
<p>
871
+
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.
872
+
</p>
873
+
<divclass="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>
874
+
<divclass="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>
875
+
</li>
876
+
</ul></div>
877
+
</li>
878
+
<li>
879
+
<p>
880
+
In new repositories, the default branch name will be <code>main</code>. We have been warning that the default name will change since 675704c74dd (init: provide useful advice about init.defaultBranch, 2020-12-11). The new name matches the default branch name used in new repositories by many of the big Git forges.
881
+
</p>
882
+
</li>
883
+
<li>
884
+
<p>
885
+
Git will require Rust as a mandatory part of the build process. While Git already started to adopt Rust in Git 2.49, all parts written in Rust are optional for the time being. This includes:
886
+
</p>
887
+
<divclass="ulist"><ul>
888
+
<li>
889
+
<p>
890
+
The Rust wrapper around libgit.a that is part of "contrib/" and which has been introduced in Git 2.49.
891
+
</p>
892
+
</li>
893
+
<li>
894
+
<p>
895
+
Subsystems that have an alternative implementation in Rust to test interoperability between our C and Rust codebase.
896
+
</p>
897
+
</li>
898
+
<li>
899
+
<p>
900
+
Newly written features that are not mission critical for a fully functional Git client.
901
+
</p>
902
+
<divclass="paragraph"><p>These changes are meant as test balloons to allow distributors of Git to prepare for Rust becoming a mandatory part of the build process. There will be multiple milestones for the introduction of Rust:</p></div>
903
+
<divclass="openblock">
904
+
<divclass="content">
905
+
<divclass="olist arabic"><olclass="arabic">
906
+
<li>
907
+
<p>
908
+
Initially, with Git 2.52, support for Rust will be auto-detected by Meson and disabled in our Makefile so that the project can sort out the initial infrastructure.
909
+
</p>
910
+
</li>
911
+
<li>
912
+
<p>
913
+
In Git 2.53, both build systems will default-enable support for Rust. Consequently, builds will break by default if Rust is not available on the build host. The use of Rust can still be explicitly disabled via build flags.
914
+
</p>
915
+
</li>
916
+
<li>
917
+
<p>
918
+
In Git 3.0, the build options will be removed and support for Rust is mandatory.
919
+
</p>
920
+
</li>
921
+
</ol></div>
922
+
</div></div>
923
+
<divclass="paragraph"><p>You can explicitly ask both Meson and our Makefile-based system to enable Rust by saying <code>meson</code><code>configure</code><code>-Drust=enabled</code> and <code>make</code><code>WITH_RUST=YesPlease</code>, respectively.</p></div>
924
+
<divclass="paragraph"><p>The Git project will declare the last version before Git 3.0 to be a long-term support release. This long-term release will receive important bug fixes for at least four release cycles and security fixes for six release cycles. The Git project will hand over maintainership of the long-term release to distributors in case they need to extend the life of that long-term release even further. Details of how this long-term release will be handed over to the community will be discussed once the Git project decides to stop officially supporting it.</p></div>
925
+
<divclass="paragraph"><p>We will evaluate the impact on downstream distributions before making Rust mandatory in Git 3.0. If we see that the impact on downstream distributions would be significant, we may decide to defer this change to a subsequent minor release. This evaluation will also take into account our own experience with how painful it is to keep Rust an optional component.</p></div>
Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/" and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in the repository configuration.
966
+
</p>
967
+
<divclass="paragraph"><p>The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull: short-hand notation for remote repositories., 2005-07-16) and was superseded by 6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin., 2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That commit already mentions an upcoming deprecation of the ".git/branches/" directory, and starting with a1d4aa7424 (Add repository-layout document., 2005-09-01) we have also marked this layout as deprecated. Eventually we also started to migrate away from ".git/remotes/" in favor of config-based remotes, and we have marked the directory as legacy in 3d3d282146 (Documentation: Grammar correction, wording fixes and cleanup, 2011-08-23)</p></div>
968
+
<divclass="paragraph"><p>As our documentation mentions, these directories are unlikely to be used in modern repositories and most users aren’t even aware of these mechanisms. They have been deprecated for almost 20 years and 14 years respectively, and we are not aware of any active users that have complained about this deprecation. Furthermore, the ".git/branches/" directory is nowadays misleadingly named and may cause confusion as "branches" are almost exclusively used in the context of references.</p></div>
969
+
<divclass="paragraph"><p>These features will be removed.</p></div>
970
+
</li>
971
+
<li>
972
+
<p>
973
+
Support for "--stdin" option in the "name-rev" command was deprecated (and hidden from the documentation) in the Git 2.40 timeframe, in preference to its synonym "--annotate-stdin". Git 3.0 removes the support for "--stdin" altogether.
974
+
</p>
975
+
</li>
976
+
<li>
977
+
<p>
978
+
The git-whatchanged(1) command has outlived its usefulness more than 10 years ago, and takes more keystrokes to type than its rough equivalent <code>git</code><code>log</code><code>--raw</code>. We have nominated the command for removal, have changed the command to refuse to work unless the <code>--i-still-use-this</code> option is given, and asked the users to report when they do so.
979
+
</p>
980
+
<divclass="paragraph"><p>The command will be removed.</p></div>
981
+
</li>
982
+
<li>
983
+
<p>
984
+
Support for <code>core.commentString=auto</code> has been deprecated and will be removed in Git 3.0.
Support for <code>core.preferSymlinkRefs=true</code> has been deprecated and will be removed in Git 3.0. Writing symbolic refs as symbolic links will be phased out in favor of using plain files using the textual representation of symbolic refs.
991
+
</p>
992
+
<divclass="paragraph"><p>Symbolic references were initially always stored as a symbolic link. This was changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a textfile., 2005-09-25), where a new textual symref format was introduced to store those symbolic refs in a plain file. In 9f0bb90d16 (core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git project switched the default to use the textual symrefs in favor of symbolic links.</p></div>
993
+
<divclass="paragraph"><p>The migration away from symbolic links has happened almost 20 years ago by now, and there is no known reason why one should prefer them nowadays. Furthermore, symbolic links are not supported on some platforms.</p></div>
994
+
<divclass="paragraph"><p>Note that only the writing side for such symbolic links is deprecated. Reading such symbolic links is still supported for now.</p></div>
0 commit comments