{"thread":{"id":"61428","subject":"[RFC PATCH] docs: document upcoming breaking changes","startedAt":"2024-05-07T08:27:26Z","lastAt":"2024-06-14T16:08:13Z","messageCount":70,"participants":["Patrick Steinhardt","Johannes Schindelin","Junio C Hamano","Phillip Wood","Dragan Simic","Justin Tobler","Karthik Nayak","Todd Zullinger"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"494262","messageId":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","threadId":"61428","inReplyTo":null,"subject":"[RFC PATCH] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-07T08:27:18Z","receivedAt":"2024-05-07T08:27:26Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that lists upcoming breaking changes to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n\nPlease note that this is explicitly marked as a request for comments.\nThe proposed list of changes is neither exhaustive, nor do I necessarily\nthink that every single item on that list is a good idea. The intent is\nto spark discussions, so some of the ideas on the list are controversial\nby design.\n\nFurther note that this is not a \"Git 3.0 is around the corner\"-style\ndocument. I do not want to propose that a breaking Git 3.0 should be\nreleased soonish, and neither do I have the authority to decide that. I\nrather want us to document deprecations such that users, developers,\nhosters and distros are well aware of upcoming deprecations and can\neither speak up or prepare accordingly.\n\nAlso, while a minority of the proposed deprecations does have links to\nmailing list threads, the majority doesn't. If we have good discussions\nto link to I'd love to add those links. I hope that some of the items\nwill spark discussions that I can link to in v2.\n\nPatrick\n\n Documentation/UpcomingBreakingChanges.md | 65 ++++++++++++++++++++++++\n 1 file changed, 65 insertions(+)\n create mode 100644 Documentation/UpcomingBreakingChanges.md\n\ndiff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md\nnew file mode 100644\nindex 0000000000..94d77a8af1\n--- /dev/null\n+++ b/Documentation/UpcomingBreakingChanges.md\n@@ -0,0 +1,65 @@\n+# Upcoming breaking changes\n+\n+The intent of this document is to track upcoming deprecations for the next major\n+Git release. It is supposed to be a living document where proposed changes and\n+deprecations are up for discussion.\n+\n+## Git 3.0\n+\n+### Changes\n+\n+ - The default initial branch name will be changed from \"master\" to \"main\".\n+\n+ Cf. ,\n+ .\n+\n+ - The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\".\n+\n+ - The default ref backend for new repositories will be changed from \"files\" to\n+ \"reftable\".\n+\n+### Removals\n+\n+ - git-config(1) has learned to use subcommands that replace implicit actions\n+ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n+ --unset-all`). The actions will be removed in favor of subcommands.\n+ Prerequisite for this change is that the new subcommands have been out for at\n+ least for two years to give script authors time to migrate.\n+\n+ Cf. .\n+\n+ - git-http-push(1) can be used to push objects to a remote repository via\n+ HTTP/DAV. Support for write support via WebDAV is not in widespread use\n+ nowadays anymore and will be removed together with the command.\n+\n+ - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n+ server like Apache. The protocol has not seen any updates recently and is\n+ neither compatible with alternative hash functions nor with alternative ref\n+ backends. It will thus be removed.\n+\n+ - git-update-server-info(1) generates data required when serving data via the\n+ dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n+ anymore and will be removed together with the protocol. This includes the\n+ \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n+ `git repack -n` flag.\n+\n+ - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n+ shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n+ concept has long been replaced by remotes and will thus be removed.\n+\n+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will\n+ be removed in favor of git-blame(1).\n+\n+ - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n+ HTTP server. These scripts have been unmaintained for a significant amount of\n+ time and will be removed.\n+\n+ - git-filter-branch(1) can be used to rewrite history of a repository. It is\n+ very slow, hard to use and has many gotchas. It will thus be removed in favor\n+ of [git-filter-repo](https://github.com/newren/git-filter-repo).\n+\n+ - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n+ been a source of multiple remote code execution vulnerabilities. The feature\n+ will be removed in favor of `core.hooksDirectory` and the new config-based\n+ hooks.\n-- \n2.45.0\n\n"},{"id":"494266","messageId":"e1350757-80d6-3ca6-3ef1-4b6ba496ba9e@gmx.de","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2024-05-07T10:38:31Z","receivedAt":"2024-05-07T10:38:41Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Patrick,\n\nOn Tue, 7 May 2024, Patrick Steinhardt wrote:\n\n> Over time, Git has grown quite a lot. With this evolution, many ideas\n> that were sensible at the time they were introduced are not anymore and\n> are thus considered to be deprecated. And while some deprecations may be\n> noted in manpages, most of them are actually deprecated in the \"hive\n> mind\" of the Git community, only.\n>\n> Introduce a new document that lists upcoming breaking changes to address\n> this issue. This document serves multiple purposes:\n>\n> - It is a way to facilitate discussion around proposed deprecations.\n>\n> - It allows users to learn about deprecations and speak up in case\n> they have good reasons why a certain feature should not be\n> deprecated.\n>\n> - It states intent and documents where the Git project wants to go.\n\nI love it.\n\nFWIW my first reaction was: These deprecations should be mentioned in the\nrelease notes of the current versions, as a heads-up. But then I saw the\nimpressive list you accumulated and agree that it needs to have its own\ndocument.\n\n> The document is _not_ intended to cast every single discussion into\n> stone. It is supposed to be a living document that may change over time\n> when there are good reasons for it to change.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n>\n> Please note that this is explicitly marked as a request for comments.\n> The proposed list of changes is neither exhaustive, nor do I necessarily\n> think that every single item on that list is a good idea. The intent is\n> to spark discussions, so some of the ideas on the list are controversial\n> by design.\n>\n> Further note that this is not a \"Git 3.0 is around the corner\"-style\n> document. I do not want to propose that a breaking Git 3.0 should be\n> released soonish, and neither do I have the authority to decide that. I\n> rather want us to document deprecations such that users, developers,\n> hosters and distros are well aware of upcoming deprecations and can\n> either speak up or prepare accordingly.\n>\n> Also, while a minority of the proposed deprecations does have links to\n> mailing list threads, the majority doesn't. If we have good discussions\n> to link to I'd love to add those links. I hope that some of the items\n> will spark discussions that I can link to in v2.\n>\n> Patrick\n>\n> Documentation/UpcomingBreakingChanges.md | 65 ++++++++++++++++++++++++\n> 1 file changed, 65 insertions(+)\n> create mode 100644 Documentation/UpcomingBreakingChanges.md\n>\n> diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md\n> new file mode 100644\n> index 0000000000..94d77a8af1\n> --- /dev/null\n> +++ b/Documentation/UpcomingBreakingChanges.md\n> @@ -0,0 +1,65 @@\n> +# Upcoming breaking changes\n> +\n> +The intent of this document is to track upcoming deprecations for the next major\n> +Git release. It is supposed to be a living document where proposed changes and\n> +deprecations are up for discussion.\n> +\n> +## Git 3.0\n> +\n> +### Changes\n> +\n> + - The default initial branch name will be changed from \"master\" to \"main\".\n> +\n> + Cf. ,\n> + .\n> +\n> + - The default hash function for new repositories will be changed from \"sha1\"\n> + to \"sha256\".\n> +\n> + - The default ref backend for new repositories will be changed from \"files\" to\n> + \"reftable\".\n> +\n> +### Removals\n> +\n> + - git-config(1) has learned to use subcommands that replace implicit actions\n> + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> + --unset-all`). The actions will be removed in favor of subcommands.\n> + Prerequisite for this change is that the new subcommands have been out for at\n> + least for two years to give script authors time to migrate.\n> +\n> + Cf. .\n> +\n> + - git-http-push(1) can be used to push objects to a remote repository via\n> + HTTP/DAV. Support for write support via WebDAV is not in widespread use\n> + nowadays anymore and will be removed together with the command.\n> +\n> + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n> + server like Apache. The protocol has not seen any updates recently and is\n> + neither compatible with alternative hash functions nor with alternative ref\n> + backends. It will thus be removed.\n> +\n> + - git-update-server-info(1) generates data required when serving data via the\n> + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n> + anymore and will be removed together with the protocol. This includes the\n> + \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n> + `git repack -n` flag.\n> +\n> + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n> + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n> + concept has long been replaced by remotes and will thus be removed.\n> +\n> + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will\n> + be removed in favor of git-blame(1).\n\nThis is the only item I am not quite sure about. Its maintenance cost is\nnegligible, I would think, and the cost of using a judging command name is\nless negligible.\n\n> +\n> + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n> + HTTP server. These scripts have been unmaintained for a significant amount of\n> + time and will be removed.\n> +\n> + - git-filter-branch(1) can be used to rewrite history of a repository. It is\n> + very slow, hard to use and has many gotchas. It will thus be removed in favor\n> + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n> +\n> + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n> + been a source of multiple remote code execution vulnerabilities. The feature\n> + will be removed in favor of `core.hooksDirectory` and the new config-based\n> + hooks.\n\nSince I already expressed interest in having this document, especially in\nthe proposed form of being a _living_ document, i.e. subject to change, I\nwould like to add:\n\n- The \"dashed form\", i.e. support for calling `git-` instead of\n `git ` in scripts, has been deprecated for a long time and the\n intention is still to remove it.\n\n- The command to import patches from Quilt seems to be used rarely, if\n ever, and will be removed.\n\n- Support for importing repositories from GNU Arch will be removed because\n it would not appear to have any users.\n\n- Support for interacting with CVS repositories (via `cvsimport`,\n `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by\n the number of times these commands have been mentioned recently. The\n code has been essentially unmaintained, too, and will be removed.\n\nCiao,\nJohannes\n"},{"id":"494289","messageId":"xmqqle4lnuvy.fsf@gitster.g","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-07T22:02:09Z","receivedAt":"2024-05-07T22:02:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Over time, Git has grown quite a lot. With this evolution, many ideas\n> that were sensible at the time they were introduced are not anymore and\n> are thus considered to be deprecated. And while some deprecations may be\n> noted in manpages, most of them are actually deprecated in the \"hive\n> mind\" of the Git community, only.\n\nThere may be a new way that we hope is more suitable for folks who\nare learning Git today that achieves the same goal as an old way.\nIt rarely means that the old way goes away, even when the new way is\nmore capable than the old way and the use case the new way covers is\na strict superset of the old way.\n\nSuch an introduction of a new way is *not* a breaking change.\nEverything the first paragraph talks about is a \"deprecation\" that\ndoes not break anything. Documenting them is worthwhile, but it is\nworth pointing out that it not what the title of the topic \"upcoming\nbreaking changes\" covers.\n\nI think you should explicitly say that we deprecate but rarely\nremove and old ways are kept for backward compatibility in that\nintroductory paragraph. Then propose \"But we may want to remove old\nways and deliberately break at a large version bump every 5 years\".\nThat will lead your readers more smoothly to the next paragraph.\n\n> Introduce a new document that lists upcoming breaking changes to address\n> this issue. This document serves multiple purposes:\n>\n> - It is a way to facilitate discussion around proposed deprecations.\n>\n> - It allows users to learn about deprecations and speak up in case\n> they have good reasons why a certain feature should not be\n> deprecated.\n>\n> - It states intent and documents where the Git project wants to go.\n\nAnother thing we may want to describe in such a document is what we\ndo not want to drop and why, even when a new way that is a superset\nis available, which would give newbies with a natural \"why don't we\nforce everybody including the old timers to adopt new ways\" question\na reasonable answer.\n\n> The document is _not_ intended to cast every single discussion into\n> stone. It is supposed to be a living document that may change over time\n> when there are good reasons for it to change.\n\nI'll stop here, as arguing how an individual bullet item is not\nappropriate (i.e., deprecating it is a bad idea) should be left for\nlater stages of the discussion, after we accumulated more ideas.\n\nThanks.\n\n\n"},{"id":"494319","messageId":"077b69f1-cffa-44d5-8614-7f83b63442f8@gmail.com","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2024-05-08T13:15:11Z","receivedAt":"2024-05-08T13:15:14Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Patrick\n\nThanks putting this together, I think it will be a useful way discussing \ndeprecations and removals.\n\nOn 07/05/2024 09:27, Patrick Steinhardt wrote:\n> Over time, Git has grown quite a lot. With this evolution, many ideas\n> that were sensible at the time they were introduced are not anymore and\n> are thus considered to be deprecated. And while some deprecations may be\n> noted in manpages, most of them are actually deprecated in the \"hive\n> mind\" of the Git community, only.\n> \n> Introduce a new document that lists upcoming breaking changes to address\n> this issue. This document serves multiple purposes:\n> \n> - It is a way to facilitate discussion around proposed deprecations.\n> \n> - It allows users to learn about deprecations and speak up in case\n> they have good reasons why a certain feature should not be\n> deprecated.\n >\n> - It states intent and documents where the Git project wants to go.\n\nIs the plan to use this document to track the progress/status of \nproposed deprecations? For example the config based hooks implementation \nis stalled at the moment and would need some work before we can remove \n$GIT_DIR/hooks\n\n> +### Removals\n> +\n> + - git-config(1) has learned to use subcommands that replace implicit actions\n> + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> + --unset-all`). The actions will be removed in favor of subcommands.\n> + Prerequisite for this change is that the new subcommands have been out for at\n> + least for two years to give script authors time to migrate.\n\nI agree we want to allow plenty of time for script authors to migrate \ntheir scripts here.\n\n> + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n> + been a source of multiple remote code execution vulnerabilities.\n\nI'm not sure about the reasoning here as a hook has to be enabled by the \nuser before it is run. There are good reasons to prefer config based \nhooks such as the ability to run multiple scripts per hook event but I \ndon't think they are inherently more secure.\n\nBest Wishes\n\nPhillip\n"},{"id":"494320","messageId":"ZjuEMNsw-KARJjwx@tanuki","threadId":"61428","inReplyTo":"xmqqle4lnuvy.fsf@gitster.g","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-08T13:54:56Z","receivedAt":"2024-05-08T13:55:03Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > Over time, Git has grown quite a lot. With this evolution, many ideas\n> > that were sensible at the time they were introduced are not anymore and\n> > are thus considered to be deprecated. And while some deprecations may be\n> > noted in manpages, most of them are actually deprecated in the \"hive\n> > mind\" of the Git community, only.\n> \n> There may be a new way that we hope is more suitable for folks who\n> are learning Git today that achieves the same goal as an old way.\n> It rarely means that the old way goes away, even when the new way is\n> more capable than the old way and the use case the new way covers is\n> a strict superset of the old way.\n> \n> Such an introduction of a new way is *not* a breaking change.\n> Everything the first paragraph talks about is a \"deprecation\" that\n> does not break anything. Documenting them is worthwhile, but it is\n> worth pointing out that it not what the title of the topic \"upcoming\n> breaking changes\" covers.\n> \n> I think you should explicitly say that we deprecate but rarely\n> remove and old ways are kept for backward compatibility in that\n> introductory paragraph. Then propose \"But we may want to remove old\n> ways and deliberately break at a large version bump every 5 years\".\n> That will lead your readers more smoothly to the next paragraph.\n\nAgreed, I'll something along these lines.\n\n> > Introduce a new document that lists upcoming breaking changes to address\n> > this issue. This document serves multiple purposes:\n> >\n> > - It is a way to facilitate discussion around proposed deprecations.\n> >\n> > - It allows users to learn about deprecations and speak up in case\n> > they have good reasons why a certain feature should not be\n> > deprecated.\n> >\n> > - It states intent and documents where the Git project wants to go.\n> \n> Another thing we may want to describe in such a document is what we\n> do not want to drop and why, even when a new way that is a superset\n> is available, which would give newbies with a natural \"why don't we\n> force everybody including the old timers to adopt new ways\" question\n> a reasonable answer.\n\nOkay, I see how that may make sense for some parts. I guess one of the\nmotivations here is things like git-checkout(1) and git-switch(1) /\ngit-restore(1)?\n\nDo we want to give this class a separate name? Deprecated may feel a bit\ntoo strong in that context as it does imply eventual removal for many\nfolks (including me, I guess). Is \"superseded\" better?\n\nPatrick\n"},{"id":"494321","messageId":"ZjuENtXjDZaX-0B0@tanuki","threadId":"61428","inReplyTo":"e1350757-80d6-3ca6-3ef1-4b6ba496ba9e@gmx.de","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-08T13:55:02Z","receivedAt":"2024-05-08T13:55:06Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, May 07, 2024 at 12:38:31PM +0200, Johannes Schindelin wrote:\n> Hi Patrick,\n> \n> On Tue, 7 May 2024, Patrick Steinhardt wrote:\n> \n> > Over time, Git has grown quite a lot. With this evolution, many ideas\n> > that were sensible at the time they were introduced are not anymore and\n> > are thus considered to be deprecated. And while some deprecations may be\n> > noted in manpages, most of them are actually deprecated in the \"hive\n> > mind\" of the Git community, only.\n> >\n> > Introduce a new document that lists upcoming breaking changes to address\n> > this issue. This document serves multiple purposes:\n> >\n> > - It is a way to facilitate discussion around proposed deprecations.\n> >\n> > - It allows users to learn about deprecations and speak up in case\n> > they have good reasons why a certain feature should not be\n> > deprecated.\n> >\n> > - It states intent and documents where the Git project wants to go.\n> \n> I love it.\n> \n> FWIW my first reaction was: These deprecations should be mentioned in the\n> release notes of the current versions, as a heads-up. But then I saw the\n> impressive list you accumulated and agree that it needs to have its own\n> document.\n\nSome of them are my own, some of them are Junio's.\n\n[snip]\n> > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will\n> > + be removed in favor of git-blame(1).\n> \n> This is the only item I am not quite sure about. Its maintenance cost is\n> negligible, I would think, and the cost of using a judging command name is\n> less negligible.\n\nThere is of course still the problem of having multiple ways of doing\nthe same thing, which does create mental overhead for users. But overall\nit's likely going to be negligible, both on our and on the user's side.\n\nSo overall I don't mind this item much, and neither do I mind which of\nboth commands we use. I do see the argument that git-annotate(1) is less\njudgemental though.\n\n> > + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n> > + HTTP server. These scripts have been unmaintained for a significant amount of\n> > + time and will be removed.\n> > +\n> > + - git-filter-branch(1) can be used to rewrite history of a repository. It is\n> > + very slow, hard to use and has many gotchas. It will thus be removed in favor\n> > + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n> > +\n> > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n> > + been a source of multiple remote code execution vulnerabilities. The feature\n> > + will be removed in favor of `core.hooksDirectory` and the new config-based\n> > + hooks.\n> \n> Since I already expressed interest in having this document, especially in\n> the proposed form of being a _living_ document, i.e. subject to change, I\n> would like to add:\n> \n> - The \"dashed form\", i.e. support for calling `git-` instead of\n> `git ` in scripts, has been deprecated for a long time and the\n> intention is still to remove it.\n\nAgreed!\n\n> - The command to import patches from Quilt seems to be used rarely, if\n> ever, and will be removed.\n> \n> - Support for importing repositories from GNU Arch will be removed because\n> it would not appear to have any users.\n\nWhat even is GNU Arch...? Never heard of it before.\n\n> - Support for interacting with CVS repositories (via `cvsimport`,\n> `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by\n> the number of times these commands have been mentioned recently. The\n> code has been essentially unmaintained, too, and will be removed.\n\nFair.\n\nI'd be happy to add these in v2 unless folks disagree.\n\nPatrick\n"},{"id":"494322","messageId":"ZjuEPmSq3E28U6tJ@tanuki","threadId":"61428","inReplyTo":"077b69f1-cffa-44d5-8614-7f83b63442f8@gmail.com","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-08T13:55:10Z","receivedAt":"2024-05-08T13:55:14Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, May 08, 2024 at 02:15:11PM +0100, Phillip Wood wrote:\n> Hi Patrick\n> \n> Thanks putting this together, I think it will be a useful way discussing\n> deprecations and removals.\n> \n> On 07/05/2024 09:27, Patrick Steinhardt wrote:\n> > Over time, Git has grown quite a lot. With this evolution, many ideas\n> > that were sensible at the time they were introduced are not anymore and\n> > are thus considered to be deprecated. And while some deprecations may be\n> > noted in manpages, most of them are actually deprecated in the \"hive\n> > mind\" of the Git community, only.\n> > \n> > Introduce a new document that lists upcoming breaking changes to address\n> > this issue. This document serves multiple purposes:\n> > \n> > - It is a way to facilitate discussion around proposed deprecations.\n> > \n> > - It allows users to learn about deprecations and speak up in case\n> > they have good reasons why a certain feature should not be\n> > deprecated.\n> >\n> > - It states intent and documents where the Git project wants to go.\n> \n> Is the plan to use this document to track the progress/status of proposed\n> deprecations? For example the config based hooks implementation is stalled\n> at the moment and would need some work before we can remove $GIT_DIR/hooks\n\nI also have it in my backlog to propose a file that may keep a record of\nlong-running projects. The intent would be similar to this patch here,\nbut it should also help newcomers to find projects to work on.\n\nThis would track:\n\n - Large-scale efforts like the past SHA256 migration or removal of\n `the_repository`.\n\n - Small projects or microprojects like we have in GSoC to help out\n newcomers when they want to work on stuff.\n\n - Things we have already discussed, but simply didn't get landed yet\n like the hooks refactoring.\n\nSo agreed, the hook refactorings should not be part of the deprecations\ndocument when it hasn't even landed yet.\n\n> > +### Removals\n> > +\n> > + - git-config(1) has learned to use subcommands that replace implicit actions\n> > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> > + --unset-all`). The actions will be removed in favor of subcommands.\n> > + Prerequisite for this change is that the new subcommands have been out for at\n> > + least for two years to give script authors time to migrate.\n> \n> I agree we want to allow plenty of time for script authors to migrate their\n> scripts here.\n> \n> > + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n> > + been a source of multiple remote code execution vulnerabilities.\n> \n> I'm not sure about the reasoning here as a hook has to be enabled by the\n> user before it is run. There are good reasons to prefer config based hooks\n> such as the ability to run multiple scripts per hook event but I don't think\n> they are inherently more secure.\n\nI'll remove this item for now. We can discuss it again when (if) the\nconfig based mechanisms land.\n\nPatrick\n"},{"id":"494323","messageId":"xmqqy18kxsdr.fsf@gitster.g","threadId":"61428","inReplyTo":"ZjuEMNsw-KARJjwx@tanuki","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-08T14:58:24Z","receivedAt":"2024-05-08T14:58:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> Another thing we may want to describe in such a document is what we\n>> do not want to drop and why, even when a new way that is a superset\n>> is available, which would give newbies with a natural \"why don't we\n>> force everybody including the old timers to adopt new ways\" question\n>> a reasonable answer.\n>\n> Okay, I see how that may make sense for some parts. I guess one of the\n> motivations here is things like git-checkout(1) and git-switch(1) /\n> git-restore(1)?\n\nAnything that we initially think it may make sense to remove but\nturns out that they are so ingrained in workflows that may lead some\nusers to stick to pre-3.0 version. As this is a living document,\ninstead of removing some ideas that are \"voted down\", recording the\nreason why we voted it down would make sense. Checkout and annotate\nare the ones that were named so far in the discussion, but I suspect\nthere will be more.\n\n> Do we want to give this class a separate name? Deprecated may feel a bit\n> too strong in that context as it does imply eventual removal for many\n> folks (including me, I guess). Is \"superseded\" better?\n\nTraditional/established ways that will not go away?\n"},{"id":"494325","messageId":"112b6568912a6de6672bf5592c3a718e@manjaro.org","threadId":"61428","inReplyTo":"ZjuEMNsw-KARJjwx@tanuki","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-05-08T15:59:01Z","receivedAt":"2024-05-08T15:59:05Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Patrick,\n\nOn 2024-05-08 15:54, Patrick Steinhardt wrote:\n> Okay, I see how that may make sense for some parts. I guess one of the\n> motivations here is things like git-checkout(1) and git-switch(1) /\n> git-restore(1)?\n\nAs I wrote already, [1] I really see no reasons why git-switch(1) or\ngit-restore(1) should be deprecated. That would make zero sense to me.\n\n[1] \nhttps://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/\n"},{"id":"494387","messageId":"obsrinbe2uvemiq7q22zrbcln2lmfaukn6lqn7nagrassoicb4@ihwb6ifpjomc","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-05-10T02:15:29Z","receivedAt":"2024-05-10T02:16:53Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 24/05/07 10:27AM, Patrick Steinhardt wrote:\n\n+### Removals\n> +\n> + - git-config(1) has learned to use subcommands that replace implicit actions\n> + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> + --unset-all`). The actions will be removed in favor of subcommands.\n> + Prerequisite for this change is that the new subcommands have been out for at\n> + least for two years to give script authors time to migrate.\n> +\n> + Cf. .\n> +\n> + - git-http-push(1) can be used to push objects to a remote repository via\n> + HTTP/DAV. Support for write support via WebDAV is not in widespread use\n> + nowadays anymore and will be removed together with the command.\n> +\n> + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n> + server like Apache. The protocol has not seen any updates recently and is\n> + neither compatible with alternative hash functions nor with alternative ref\n> + backends. It will thus be removed.\n> +\n> + - git-update-server-info(1) generates data required when serving data via the\n> + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n> + anymore and will be removed together with the protocol. This includes the\n> + \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n> + `git repack -n` flag.\n> +\n> + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n> + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n> + concept has long been replaced by remotes and will thus be removed.\n> +\n> + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will\n> + be removed in favor of git-blame(1).\n> +\n> + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n> + HTTP server. These scripts have been unmaintained for a significant amount of\n> + time and will be removed.\n> +\n> + - git-filter-branch(1) can be used to rewrite history of a repository. It is\n> + very slow, hard to use and has many gotchas. It will thus be removed in favor\n> + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n> +\n> + - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n> + been a source of multiple remote code execution vulnerabilities. The feature\n> + will be removed in favor of `core.hooksDirectory` and the new config-based\n> + hooks.\n\nI would like to see the double dot and triple dot syntax (\"..\" and \"...\")\nremoved from `git-diff(1)` as I think they get easily confused with\nrevision ranges.\n\n-Justin\n"},{"id":"494389","messageId":"xmqq1q6aqnm2.fsf@gitster.g","threadId":"61428","inReplyTo":"obsrinbe2uvemiq7q22zrbcln2lmfaukn6lqn7nagrassoicb4@ihwb6ifpjomc","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T04:47:49Z","receivedAt":"2024-05-10T04:47:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> I would like to see the double dot and triple dot syntax (\"..\" and \"...\")\n> removed from `git-diff(1)` as I think they get easily confused with\n> revision ranges.\n\nI tend to agree that the double-dot notation does not need to exist\nas it can be done with a pair of bog-standard revs. But triple-dot\nnotation needs a replacement syntax that is just as easy to access\nthe feature as the current syntax. After updating a tip of a topic\nbranch,\n\n $ git diff topic@{1}...topic\n\nis extremely useful (in addition to \"git log -p\" and the like, of\ncourse, with the same range). Also during a conflicted merge\n\n $ git diff ...MERGE_BASE\n\nand its reverse are very handy. Having to say \"--merge-base\" is\nprobably a usability regression.\n\nIf somebody wants to pursue this further, my recommendation is to\ntreat the two separately.\n\n * Deprecate and eventually remove double-dot notation.\n\n - First, notice the use of double-dot notation.\n builtin/diff.c:symdiff_prepare() is the place to do so. Issue\n a warning about deprecation and possibility of an eventual\n removal, and tell the users to use \"diff A B\" instead of \"diff\n A..B\".\n\n - Gain consensus that the removal is a good idea. Finish these\n steps long before Git 3.0.\n\n - Remove the support for A..B.\n\n * Deprecate and eventually remove triple-dot notation.\n\n - Introduce a new syntax to allow an access to the \"symmetric\n diff\" feature just as easily as the current syntax. Wait for\n a handful releases to gauge its acceptance by the end users.\n\n - Then notice the use of triple-dot notation. The place to do\n sois the same builtin/diff.c:symdiff_prepare(). Give a warning\n about deprecation and possibility of an eventual removal, and\n tell the users to use that new syntax we introduced.\n\n - Gain consensus that the removal is a good idea. Finish these\n steps long before Git 3.0.\n\n - Remove the support for A...B.\n"},{"id":"494461","messageId":"Zj4Gx6LGSoTGc3eW@tanuki","threadId":"61428","inReplyTo":"112b6568912a6de6672bf5592c3a718e@manjaro.org","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-10T11:36:39Z","receivedAt":"2024-05-10T11:36:44Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, May 08, 2024 at 05:59:01PM +0200, Dragan Simic wrote:\n> Hello Patrick,\n> \n> On 2024-05-08 15:54, Patrick Steinhardt wrote:\n> > Okay, I see how that may make sense for some parts. I guess one of the\n> > motivations here is things like git-checkout(1) and git-switch(1) /\n> > git-restore(1)?\n> \n> As I wrote already, [1] I really see no reasons why git-switch(1) or\n> git-restore(1) should be deprecated. That would make zero sense to me.\n> \n> [1]\n> https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/\n\nNote that the discussion here is the other way round: whether we want to\neventually deprecate tools like git-checkout(1) that have newer\nreplacements. Junio argues that there being a replacement is not by\nitself a good enough reason to eventually remove the old one, which I'm\nfine with.\n\nPatrick\n"},{"id":"494466","messageId":"bcaa054e4081a43bef349a1079895374@manjaro.org","threadId":"61428","inReplyTo":"Zj4Gx6LGSoTGc3eW@tanuki","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-05-10T12:43:42Z","receivedAt":"2024-05-10T12:43:49Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Patrick,\n\nOn 2024-05-10 13:36, Patrick Steinhardt wrote:\n> On Wed, May 08, 2024 at 05:59:01PM +0200, Dragan Simic wrote:\n>> On 2024-05-08 15:54, Patrick Steinhardt wrote:\n>> > Okay, I see how that may make sense for some parts. I guess one of the\n>> > motivations here is things like git-checkout(1) and git-switch(1) /\n>> > git-restore(1)?\n>> \n>> As I wrote already, [1] I really see no reasons why git-switch(1) or\n>> git-restore(1) should be deprecated. That would make zero sense to \n>> me.\n>> \n>> [1] \n>> https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/\n> \n> Note that the discussion here is the other way round: whether we want \n> to\n> eventually deprecate tools like git-checkout(1) that have newer\n> replacements. Junio argues that there being a replacement is not by\n> itself a good enough reason to eventually remove the old one, which I'm\n> fine with.\n\nI agree that not deprecating git-checkout(1) and similar utilities is\nthe way to go. It's rather safe to assume that many users still use\nthem, despite the existence of the newer replacements. Also, not just\nusers, but various scripts.\n\n"},{"id":"494699","messageId":"2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"[RFC PATCH v2] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-14T06:16:44Z","receivedAt":"2024-05-14T06:16:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that lists upcoming breaking changes, but also\ndeprecations which we are not willing to go through with, to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go,\n both in the case where we want to deprecate, but also in the case\n where we don't want to deprecate a specific feature.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n\nI have tried to accommodate for all feedback to v1. Most notably:\n\n - I have introduced a new section that documents concepts that are\n _not_ to be deprecated. The intent is to capture discussions around\n proposed deprecations where we ultimately decide that we do not\n (yet) want to deprecate it.\n\n - I have added some more proposed deprecations. As before, all of this\n is up for discussion and I do not want to force any of the proposed\n deprecations onto anybody.\n\n - I have dropped the \"$GITDIR/hooks\" deprecation item for now. It is\n premature to have it at this point in time given that the\n config-based approach isn't even close to landing.\n\nPatrick\n\nRange-diff against v1:\n1: a78d68ecc2 ! 1: 2ef53ff98b docs: document upcoming breaking changes\n @@ Commit message\n noted in manpages, most of them are actually deprecated in the \"hive\n mind\" of the Git community, only.\n \n - Introduce a new document that lists upcoming breaking changes to address\n + Introduce a new document that lists upcoming breaking changes, but also\n + deprecations which we are not willing to go through with, to address\n this issue. This document serves multiple purposes:\n \n - It is a way to facilitate discussion around proposed deprecations.\n @@ Commit message\n they have good reasons why a certain feature should not be\n deprecated.\n \n - - It states intent and documents where the Git project wants to go.\n + - It states intent and documents where the Git project wants to go,\n + both in the case where we want to deprecate, but also in the case\n + where we don't want to deprecate a specific feature.\n \n The document is _not_ intended to cast every single discussion into\n stone. It is supposed to be a living document that may change over time\n @@ Documentation/UpcomingBreakingChanges.md (new)\n @@\n +# Upcoming breaking changes\n +\n ++The Git project aims to ensure backwards compatibility to the best extent\n ++possible. Minor releases will not break backwards compatibility unless there is\n ++a very strong reason to do so, like for example a security vulnerability.\n ++\n ++Regardless of that, due to the age of the Git project, it is only natural to\n ++accumulate a backlog of backwards-incompatible changes that will eventually be\n ++required to keep the project aligned with a changing world. These changes fall\n ++into several categories:\n ++\n ++ - Changes to long established defaults.\n ++\n ++ - Concepts that have been replaced with a superior design.\n ++\n ++ - Concepts, commands, configuration or options that have been lacking in major\n ++ ways and that cannot be fixed.\n ++\n ++The Git project will thus irregularly release major versions that deliberately\n ++break backwards compatibility with older versions. This is done to ensure that\n ++Git remains relevant, safe and maintainable going forward. The release cadence\n ++of major versions is typically measured in multiple years.\n ++\n +The intent of this document is to track upcoming deprecations for the next major\n -+Git release. It is supposed to be a living document where proposed changes and\n ++Git release. Furthermore, this document also tracks what will _not_ be\n ++deprecated. This is done such that the outcome of discussions documente both\n ++when the discussion favors deprecation, but also when it rejects a deprecation.\n ++\n ++It is supposed to be a living document where proposed changes and\n +deprecations are up for discussion.\n +\n +## Git 3.0\n @@ Documentation/UpcomingBreakingChanges.md (new)\n +\n +### Removals\n +\n -+ - git-config(1) has learned to use subcommands that replace implicit actions\n -+ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n -+ --unset-all`). The actions will be removed in favor of subcommands.\n -+ Prerequisite for this change is that the new subcommands have been out for at\n -+ least for two years to give script authors time to migrate.\n -+\n -+ Cf. .\n -+\n + - git-http-push(1) can be used to push objects to a remote repository via\n + HTTP/DAV. Support for write support via WebDAV is not in widespread use\n + nowadays anymore and will be removed together with the command.\n @@ Documentation/UpcomingBreakingChanges.md (new)\n + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n + concept has long been replaced by remotes and will thus be removed.\n +\n -+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will\n -+ be removed in favor of git-blame(1).\n -+\n + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n + HTTP server. These scripts have been unmaintained for a significant amount of\n + time and will be removed.\n @@ Documentation/UpcomingBreakingChanges.md (new)\n + very slow, hard to use and has many gotchas. It will thus be removed in favor\n + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n +\n -+ - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has\n -+ been a source of multiple remote code execution vulnerabilities. The feature\n -+ will be removed in favor of `core.hooksDirectory` and the new config-based\n -+ hooks.\n ++ - The \"dashed form\", i.e. support for calling `git-` instead of\n ++ `git ` in scripts, has been deprecated for a long time and will be\n ++ removed.\n ++\n ++ - The command to import patches from Quilt seems to be used rarely, if\n ++ ever, and will be removed.\n ++\n ++ - Support for importing repositories from GNU Arch will be removed because\n ++ it would not appear to have any users.\n ++\n ++ - Support for interacting with CVS repositories (via `cvsimport`,\n ++ `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by\n ++ the number of times these commands have been mentioned recently. The\n ++ code has been essentially unmaintained, too, and will be removed.\n ++\n ++ - Support for grafting commits has long been superseded by git-replace(1).\n ++ Grafts are inferior to replacement refs as the mechanism can lead to\n ++ hard-to-diagnose problems when transferring objects between repositories.\n ++ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n ++ 2014-03-05) and will be removed.\n ++\n ++## Superseded features that will not be deprecated\n ++\n ++Some features have gained newer replacements that aim to improve the design in\n ++certain ways. The fact that there is a replacement does not automatically mean\n ++that the old way of doing things will eventually be removed. This section tracks\n ++those superseded features.\n ++\n ++ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As\n ++ the maintenance burden of carrying both of these commands is negligible, both\n ++ commands will stay.\n ++\n ++ - git-restore(1) and git-switch(1) have been introduced as a replacement for\n ++ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n ++ of switching to git-restore(1) and git-switch(1) is contended, all three\n ++ commands will stay.\n ++\n ++ - git-config(1) has learned to use subcommands that replace implicit actions\n ++ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n ++ --unset-all`). The action flags will not be removed in the next major Git\n ++ release as there likely exist a lot of scripts out there that use the old\n ++ syntax.\n ++\n ++ Cf. .\n\n Documentation/UpcomingBreakingChanges.md | 119 +++++++++++++++++++++++\n 1 file changed, 119 insertions(+)\n create mode 100644 Documentation/UpcomingBreakingChanges.md\n\ndiff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md\nnew file mode 100644\nindex 0000000000..8c7a5f2f38\n--- /dev/null\n+++ b/Documentation/UpcomingBreakingChanges.md\n@@ -0,0 +1,119 @@\n+# Upcoming breaking changes\n+\n+The Git project aims to ensure backwards compatibility to the best extent\n+possible. Minor releases will not break backwards compatibility unless there is\n+a very strong reason to do so, like for example a security vulnerability.\n+\n+Regardless of that, due to the age of the Git project, it is only natural to\n+accumulate a backlog of backwards-incompatible changes that will eventually be\n+required to keep the project aligned with a changing world. These changes fall\n+into several categories:\n+\n+ - Changes to long established defaults.\n+\n+ - Concepts that have been replaced with a superior design.\n+\n+ - Concepts, commands, configuration or options that have been lacking in major\n+ ways and that cannot be fixed.\n+\n+The Git project will thus irregularly release major versions that deliberately\n+break backwards compatibility with older versions. This is done to ensure that\n+Git remains relevant, safe and maintainable going forward. The release cadence\n+of major versions is typically measured in multiple years.\n+\n+The intent of this document is to track upcoming deprecations for the next major\n+Git release. Furthermore, this document also tracks what will _not_ be\n+deprecated. This is done such that the outcome of discussions documente both\n+when the discussion favors deprecation, but also when it rejects a deprecation.\n+\n+It is supposed to be a living document where proposed changes and\n+deprecations are up for discussion.\n+\n+## Git 3.0\n+\n+### Changes\n+\n+ - The default initial branch name will be changed from \"master\" to \"main\".\n+\n+ Cf. ,\n+ .\n+\n+ - The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\".\n+\n+ - The default ref backend for new repositories will be changed from \"files\" to\n+ \"reftable\".\n+\n+### Removals\n+\n+ - git-http-push(1) can be used to push objects to a remote repository via\n+ HTTP/DAV. Support for write support via WebDAV is not in widespread use\n+ nowadays anymore and will be removed together with the command.\n+\n+ - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n+ server like Apache. The protocol has not seen any updates recently and is\n+ neither compatible with alternative hash functions nor with alternative ref\n+ backends. It will thus be removed.\n+\n+ - git-update-server-info(1) generates data required when serving data via the\n+ dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n+ anymore and will be removed together with the protocol. This includes the\n+ \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n+ `git repack -n` flag.\n+\n+ - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n+ shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n+ concept has long been replaced by remotes and will thus be removed.\n+\n+ - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n+ HTTP server. These scripts have been unmaintained for a significant amount of\n+ time and will be removed.\n+\n+ - git-filter-branch(1) can be used to rewrite history of a repository. It is\n+ very slow, hard to use and has many gotchas. It will thus be removed in favor\n+ of [git-filter-repo](https://github.com/newren/git-filter-repo).\n+\n+ - The \"dashed form\", i.e. support for calling `git-` instead of\n+ `git ` in scripts, has been deprecated for a long time and will be\n+ removed.\n+\n+ - The command to import patches from Quilt seems to be used rarely, if\n+ ever, and will be removed.\n+\n+ - Support for importing repositories from GNU Arch will be removed because\n+ it would not appear to have any users.\n+\n+ - Support for interacting with CVS repositories (via `cvsimport`,\n+ `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by\n+ the number of times these commands have been mentioned recently. The\n+ code has been essentially unmaintained, too, and will be removed.\n+\n+ - Support for grafting commits has long been superseded by git-replace(1).\n+ Grafts are inferior to replacement refs as the mechanism can lead to\n+ hard-to-diagnose problems when transferring objects between repositories.\n+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n+ 2014-03-05) and will be removed.\n+\n+## Superseded features that will not be deprecated\n+\n+Some features have gained newer replacements that aim to improve the design in\n+certain ways. The fact that there is a replacement does not automatically mean\n+that the old way of doing things will eventually be removed. This section tracks\n+those superseded features.\n+\n+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As\n+ the maintenance burden of carrying both of these commands is negligible, both\n+ commands will stay.\n+\n+ - git-restore(1) and git-switch(1) have been introduced as a replacement for\n+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n+ of switching to git-restore(1) and git-switch(1) is contended, all three\n+ commands will stay.\n+\n+ - git-config(1) has learned to use subcommands that replace implicit actions\n+ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n+ --unset-all`). The action flags will not be removed in the next major Git\n+ release as there likely exist a lot of scripts out there that use the old\n+ syntax.\n+\n+ Cf. .\n-- \n2.45.GIT\n\n"},{"id":"494703","messageId":"ZkMJxxKdr2hd1mzR@tanuki","threadId":"61428","inReplyTo":"xmqq1q6aqnm2.fsf@gitster.g","subject":"Re: [RFC PATCH] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-14T06:50:47Z","receivedAt":"2024-05-14T06:50:53Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, May 09, 2024 at 09:47:49PM -0700, Junio C Hamano wrote:\n> Justin Tobler writes:\n> \n> > I would like to see the double dot and triple dot syntax (\"..\" and \"...\")\n> > removed from `git-diff(1)` as I think they get easily confused with\n> > revision ranges.\n> \n> I tend to agree that the double-dot notation does not need to exist\n> as it can be done with a pair of bog-standard revs. But triple-dot\n> notation needs a replacement syntax that is just as easy to access\n> the feature as the current syntax. After updating a tip of a topic\n> branch,\n> \n> $ git diff topic@{1}...topic\n> \n> is extremely useful (in addition to \"git log -p\" and the like, of\n> course, with the same range). Also during a conflicted merge\n> \n> $ git diff ...MERGE_BASE\n> \n> and its reverse are very handy. Having to say \"--merge-base\" is\n> probably a usability regression.\n> \n> If somebody wants to pursue this further, my recommendation is to\n> treat the two separately.\n> \n> * Deprecate and eventually remove double-dot notation.\n> \n> - First, notice the use of double-dot notation.\n> builtin/diff.c:symdiff_prepare() is the place to do so. Issue\n> a warning about deprecation and possibility of an eventual\n> removal, and tell the users to use \"diff A B\" instead of \"diff\n> A..B\".\n> \n> - Gain consensus that the removal is a good idea. Finish these\n> steps long before Git 3.0.\n> \n> - Remove the support for A..B.\n> \n> * Deprecate and eventually remove triple-dot notation.\n> \n> - Introduce a new syntax to allow an access to the \"symmetric\n> diff\" feature just as easily as the current syntax. Wait for\n> a handful releases to gauge its acceptance by the end users.\n> \n> - Then notice the use of triple-dot notation. The place to do\n> sois the same builtin/diff.c:symdiff_prepare(). Give a warning\n> about deprecation and possibility of an eventual removal, and\n> tell the users to use that new syntax we introduced.\n> \n> - Gain consensus that the removal is a good idea. Finish these\n> steps long before Git 3.0.\n> \n> - Remove the support for A...B.\n\nI'll leave these for a future iteration for now given that there is more\nwork that needs to be done in this context.\n\nPatrick\n"},{"id":"494706","messageId":"CAOLa=ZRkLpi-DSNsTgVf5OCk6gEP7VTx2SeJRKT_Lv+pVu1Nyw@mail.gmail.com","threadId":"61428","inReplyTo":"2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im","subject":"Re: [RFC PATCH v2] docs: document upcoming breaking changes","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-05-14T10:48:38Z","receivedAt":"2024-05-14T10:48:40Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n[snip]\n\n> +### Removals\n> +\n> + - git-http-push(1) can be used to push objects to a remote repository via\n> + HTTP/DAV. Support for write support via WebDAV is not in widespread use\n > + nowadays anymore and will be removed together with the command.\n> +\n> + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n> + server like Apache. The protocol has not seen any updates recently and is\n> + neither compatible with alternative hash functions nor with alternative ref\n> + backends. It will thus be removed.\n> +\n> + - git-update-server-info(1) generates data required when serving data via the\n> + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n> + anymore and will be removed together with the protocol. This includes the\n> + \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n> + `git repack -n` flag.\n> +\n> + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n> + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n> + concept has long been replaced by remotes and will thus be removed.\n> +\n> + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n> + HTTP server. These scripts have been unmaintained for a significant amount of\n> + time and will be removed.\n> +\n> + - git-filter-branch(1) can be used to rewrite history of a repository. It is\n> + very slow, hard to use and has many gotchas. It will thus be removed in favor\n> + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n> +\n> + - The \"dashed form\", i.e. support for calling `git-` instead of\n> + `git ` in scripts, has been deprecated for a long time and will be\n> + removed.\n> +\n> + - The command to import patches from Quilt seems to be used rarely, if\n> + ever, and will be removed.\n> +\n> + - Support for importing repositories from GNU Arch will be removed because\n> + it would not appear to have any users.\n> +\n> + - Support for interacting with CVS repositories (via `cvsimport`,\n> + `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by\n> + the number of times these commands have been mentioned recently. The\n> + code has been essentially unmaintained, too, and will be removed.\n> +\n> + - Support for grafting commits has long been superseded by git-replace(1).\n> + Grafts are inferior to replacement refs as the mechanism can lead to\n> + hard-to-diagnose problems when transferring objects between repositories.\n> + They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n> + 2014-03-05) and will be removed.\n\nI think it is worthwhile also looking at the number of commands we have\nand see that some of these could possibly be marked deprecated, maybe\nremoval could follow too:\n\n* add, stage\nHere, `stage` is synonym and can be just dropped.\n\n* prune, prune-packed\n`prune-packed` prunes objects from packed files, perhaps could be a\nsub-command on the existing `prune` command.\n\n* annotate, blame, pickaxe\nYou've mentioned `annotate` below, but we could also remove `pickaxe`.\n\n* log, whatchanged, shortlog\nHere `log` already handles what the other two commands do.\n\n* for-each-ref, show-ref\nThese two commands do very similar things, i.e. list references. Both\ndiverge in the features they provided, but its not clear why we have the\ntwo.\n\n* verify-commit, verify-pack, verify-tag\nThese could probably be subcommands under the verify command.\n\n* diff, diff-files, diff-index, diff-tree\nHere, `diff` seems to handle everything that the others do.\n\n> +## Superseded features that will not be deprecated\n> +\n> +Some features have gained newer replacements that aim to improve the design in\n> +certain ways. The fact that there is a replacement does not automatically mean\n> +that the old way of doing things will eventually be removed. This section tracks\n> +those superseded features.\n> +\n> + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As\n> + the maintenance burden of carrying both of these commands is negligible, both\n> + commands will stay.\n> +\n>\n\nWhile maintenance burden is an issue for us. There is also an user\nexperience point of view, having similar commands doing similar\noperations is often a cause for confusion.\n\n> + - git-restore(1) and git-switch(1) have been introduced as a replacement for\n> + git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n> + of switching to git-restore(1) and git-switch(1) is contended, all three\n> + commands will stay.\n> +\n> + - git-config(1) has learned to use subcommands that replace implicit actions\n> + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> + --unset-all`). The action flags will not be removed in the next major Git\n> + release as there likely exist a lot of scripts out there that use the old\n> + syntax.\n"},{"id":"494707","messageId":"ZkNJaaKTTKbns8wo@tanuki","threadId":"61428","inReplyTo":"CAOLa=ZRkLpi-DSNsTgVf5OCk6gEP7VTx2SeJRKT_Lv+pVu1Nyw@mail.gmail.com","subject":"Re: [RFC PATCH v2] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-14T11:22:17Z","receivedAt":"2024-05-14T11:22:24Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, May 14, 2024 at 06:48:38AM -0400, Karthik Nayak wrote:\n> Patrick Steinhardt writes:\n[snip]\n> I think it is worthwhile also looking at the number of commands we have\n> and see that some of these could possibly be marked deprecated, maybe\n> removal could follow too:\n> \n> * add, stage\n> Here, `stage` is synonym and can be just dropped.\n\nI wonder whether there are any arguments in favor of git-stage(1). I\nmyself haven't even been aware of this command and have never seen it\nout there in the wild. Which would be an indicator that we can safely\nremove it.\n\nComments?\n\n> * prune, prune-packed\n> `prune-packed` prunes objects from packed files, perhaps could be a\n> sub-command on the existing `prune` command.\n\nI think we should refrain from adding anything to this document that is\nnot yet feasible. In other words, once git-prune(1) learns to prune\npacked objects we may want to think about whether git-prune-packed(1)\ncan be deprecated, but not beforehand.\n\n> * annotate, blame, pickaxe\n> You've mentioned `annotate` below, but we could also remove `pickaxe`.\n\nI think most oldtimers use git-blame(1), whereas git-annotate(1) has\nbeen introduced to make the command less judgemental. I'd thus say that\nthis falls into the category of commands that we wouldn't want to\ndeprecate because they are both used.\n\nFor git-pickaxe(1) it's a bit of a different story though. We do not\neven have a manpage for it anymore. I wouldn't mind deprecating that one\nfully.\n\n> * log, whatchanged, shortlog\n> Here `log` already handles what the other two commands do.\n\nDoes git-log(1) really support everything that git-shortlog(1) does? If\nso then this would be entirely new to me, but you never know with Git :)\n\ngit-whatchanged(1) has been essentially deprecated already. So that may\nbe a worthwhile addition.\n\n> * for-each-ref, show-ref\n> These two commands do very similar things, i.e. list references. Both\n> diverge in the features they provided, but its not clear why we have the\n> two.\n\nTrue, they have clear overlap and both are part of plumbing. I never\nquite know which one to pick. But git-show-ref(1) handles things that\ngit-for-each-ref(1) doesn't (\"--exists\", \"--verify\") and the other way\nround (\"--stdin\", \"--sort=\", many more).\n\nHonestly, I think that both of these are not ideal. I think we should\nthink bigger in this context and introduce a new command with proper\nsubcommands to make the whole story around refs more coherent and\ndiscoverable:\n\n # Replaces git-show-ref(1) and git-for-each-ref(1).\n $ git refs list\n\n # Replaces `git show-ref --exists`.\n $ git refs exist\n\n # Replaces `git show-ref --verify `.\n $ git refs show\n\n # Replaces git-symbolic-ref(1) to show a ref.\n $ git refs resolve\n\n # Replaces git-pack-ref(1).\n $ git refs pack\n\n # Replaces git-update-ref(1).\n $ git refs write\n\n # Replaces git-check-ref-format(1).\n $ git refs check-format\n\nThis is of course a much larger topic and something that is very much up\nfor discussion. But in any case, it indicates that a deprecation would\nbe premature at this point in time.\n\n> * verify-commit, verify-pack, verify-tag\n> These could probably be subcommands under the verify command.\n\nSame here -- as we don't have the command yet, I think it's premature\nthe old commands to a list of deprecations.\n\n> * diff, diff-files, diff-index, diff-tree\n> Here, `diff` seems to handle everything that the others do.\n\nThese do have different scopes though. While git-diff(1) is part of\nporcelain, the others are all part of the plumbing layer. As such, we\nprovide different guarantees. In practice it's likely a different story\nthough as my assumption is that git-diff(1) will be used in scripts a\nlot. But in any case, I think that this is a separate topic that would\nfirst need some discussion.\n\n> > +## Superseded features that will not be deprecated\n> > +\n> > +Some features have gained newer replacements that aim to improve the design in\n> > +certain ways. The fact that there is a replacement does not automatically mean\n> > +that the old way of doing things will eventually be removed. This section tracks\n> > +those superseded features.\n> > +\n> > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As\n> > + the maintenance burden of carrying both of these commands is negligible, both\n> > + commands will stay.\n> > +\n> >\n> \n> While maintenance burden is an issue for us. There is also an user\n> experience point of view, having similar commands doing similar\n> operations is often a cause for confusion.\n\nIn this case I think it's okay as the documentation of git-annotate(1)\nclearly states that it is the same as git-blame(1). But it is certainly\ntrue that synonyms also add to perceived complexity of Git.\n\nPatrick\n"},{"id":"494709","messageId":"f7dbf46360104fe9110526acf19be755@manjaro.org","threadId":"61428","inReplyTo":"CAOLa=ZRkLpi-DSNsTgVf5OCk6gEP7VTx2SeJRKT_Lv+pVu1Nyw@mail.gmail.com","subject":"Re: [RFC PATCH v2] docs: document upcoming breaking changes","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-05-14T12:32:03Z","receivedAt":"2024-05-14T12:32:11Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Karthik,\n\nOn 2024-05-14 12:48, Karthik Nayak wrote:\n> I think it is worthwhile also looking at the number of commands we have\n> and see that some of these could possibly be marked deprecated, maybe\n> removal could follow too:\n> \n> * log, whatchanged, shortlog\n> Here `log` already handles what the other two commands do.\n\nI haven't used \"git shortlog\" myself, but I think it sees a fair amount\nof use in various project maintainer reports. Thus, I don't think it \nshould\nbe marked as deprecated.\n"},{"id":"494722","messageId":"xmqqh6f05rdd.fsf@gitster.g","threadId":"61428","inReplyTo":"ZkNJaaKTTKbns8wo@tanuki","subject":"Re: [RFC PATCH v2] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-14T15:45:50Z","receivedAt":"2024-05-14T15:45:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> * annotate, blame, pickaxe\n>> You've mentioned `annotate` below, but we could also remove `pickaxe`.\n>\n> I think most oldtimers use git-blame(1), whereas git-annotate(1) has\n> been introduced to make the command less judgemental. I'd thus say that\n> this falls into the category of commands that we wouldn't want to\n> deprecate because they are both used.\n\nPersonally I do not think blame is \"judgemental\" in the first place,\nand I do not think being \"judgemental\" is bad to begin with.\n\n\"git annotate\" was there first as a Perl script, added by c65e8987\n(Add git-annotate, a tool for assigning blame., 2006-02-20). It is\nintersting to note that \"annotate\" was advertised as a tool for\nassigning blame.\n\n\"git blame\" was written almost around the same time but with \"-c\"\ncompatiblity mode to mimick \"git annotate\", added by cbfb73d7 (Add\ngit-blame, a tool for assigning blame., 2006-02-21).\n\nA healthy competition between \"annotate\" and \"blame\" continued until\nf789e347 (Remove git-annotate.perl and create a builtin-alias for\ngit-blame, 2006-10-09) retired the \"git annotate\" Perl script, and\nreplaced it with an invocation of \"git blame -c\".\n\n\"git blame\" was rewritten under the codename \"git pickaxe\" (cf.\nhttps://lore.kernel.org/git/7vr6xddm7h.fsf@assigned-by-dhcp.cox.net/),\nand was released at cee7f245 (git-pickaxe: blame rewritten.,\n2006-10-19). acca687f (git-pickaxe: retire pickaxe, 2006-11-08)\nmade it take over the old implementation of \"git blame\".\n\nThe name \"pickaxe\" can be easily removed, as the log message of\nacca687f already said back then. As everybody noticed, it is not\neven documented.\n\n>> * log, whatchanged, shortlog\n>> Here `log` already handles what the other two commands do.\n>\n> Does git-log(1) really support everything that git-shortlog(1) does?\n\nOf course not. The filtering behaviour of shortlog is unique to the\ncommand.\n\n> This is of course a much larger topic and something that is very much up\n> for discussion. But in any case, it indicates that a deprecation would\n> be premature at this point in time.\n\nYes, please exclude anything that needs new development while\ndiscussing this topic. Anybody jumping into this discussion should\ntake the word \"upcoming\" in the title more seriously.\n\nSo I won't talk about unifying \"describe\" and \"name-rev\" somehow ;-)\n\n>> * verify-commit, verify-pack, verify-tag\n>> These could probably be subcommands under the verify command.\n>\n> Same here -- as we don't have the command yet, I think it's premature\n> the old commands to a list of deprecations.\n>\n>> * diff, diff-files, diff-index, diff-tree\n>> Here, `diff` seems to handle everything that the others do.\n\nNo, diff-files, diff-index and diff-tree can do their thing\nwithout getting broken by end-user configuration. Writing your\nscript with \"git diff\" and you can keep both halves.\n"},{"id":"495561","messageId":"84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps@pks.im","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"[PATCH v3] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-24T12:54:48Z","receivedAt":"2024-05-24T12:54:55Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that lists upcoming breaking changes, but also\ndeprecations which we are not willing to go through with, to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go,\n both in the case where we want to deprecate, but also in the case\n where we don't want to deprecate a specific feature.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n\nI've dropped the RFC prefix of this series now. I think that the overall\nidea has been received well, and folks are supportive of documenting\nupcoming breaking changes.\n\nThere's only a single change compared to the second version. In any\ncase, most of the proposed deprecations didn't get much pushback. I'm\nless sure whether this is because people didn't look, or because they\nsilently agree with what I propose for deprecation.\n\nI'm going to assume it's the latter. If you feel otherwise, my proposed\nway forward would be to drop most of the items, merge the document, and\nthen add items via separate threads where we can discuss each\ndeprecation on its own.\n\nPlease let me know your preference!\n\nPatrick\n\nRange-diff against v2:\n1: 8e268a291b ! 1: 84c01f1b0a docs: document upcoming breaking changes\n @@ Documentation/UpcomingBreakingChanges.md (new)\n + They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n + 2014-03-05) and will be removed.\n +\n ++ - git-pickaxe, an alias for git-blame(1), has been retired in acca687fa9\n ++ (git-pickaxe: retire pickaxe, 2006-11-08) and will be removed.\n ++\n +## Superseded features that will not be deprecated\n +\n +Some features have gained newer replacements that aim to improve the design in\n\n Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++\n 1 file changed, 122 insertions(+)\n create mode 100644 Documentation/UpcomingBreakingChanges.md\n\ndiff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md\nnew file mode 100644\nindex 0000000000..d057ef7cb3\n--- /dev/null\n+++ b/Documentation/UpcomingBreakingChanges.md\n@@ -0,0 +1,122 @@\n+# Upcoming breaking changes\n+\n+The Git project aims to ensure backwards compatibility to the best extent\n+possible. Minor releases will not break backwards compatibility unless there is\n+a very strong reason to do so, like for example a security vulnerability.\n+\n+Regardless of that, due to the age of the Git project, it is only natural to\n+accumulate a backlog of backwards-incompatible changes that will eventually be\n+required to keep the project aligned with a changing world. These changes fall\n+into several categories:\n+\n+ - Changes to long established defaults.\n+\n+ - Concepts that have been replaced with a superior design.\n+\n+ - Concepts, commands, configuration or options that have been lacking in major\n+ ways and that cannot be fixed.\n+\n+The Git project will thus irregularly release major versions that deliberately\n+break backwards compatibility with older versions. This is done to ensure that\n+Git remains relevant, safe and maintainable going forward. The release cadence\n+of major versions is typically measured in multiple years.\n+\n+The intent of this document is to track upcoming deprecations for the next major\n+Git release. Furthermore, this document also tracks what will _not_ be\n+deprecated. This is done such that the outcome of discussions documente both\n+when the discussion favors deprecation, but also when it rejects a deprecation.\n+\n+It is supposed to be a living document where proposed changes and\n+deprecations are up for discussion.\n+\n+## Git 3.0\n+\n+### Changes\n+\n+ - The default initial branch name will be changed from \"master\" to \"main\".\n+\n+ Cf. ,\n+ .\n+\n+ - The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\".\n+\n+ - The default ref backend for new repositories will be changed from \"files\" to\n+ \"reftable\".\n+\n+### Removals\n+\n+ - git-http-push(1) can be used to push objects to a remote repository via\n+ HTTP/DAV. Support for write support via WebDAV is not in widespread use\n+ nowadays anymore and will be removed together with the command.\n+\n+ - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n+ server like Apache. The protocol has not seen any updates recently and is\n+ neither compatible with alternative hash functions nor with alternative ref\n+ backends. It will thus be removed.\n+\n+ - git-update-server-info(1) generates data required when serving data via the\n+ dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n+ anymore and will be removed together with the protocol. This includes the\n+ \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n+ `git repack -n` flag.\n+\n+ - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n+ shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n+ concept has long been replaced by remotes and will thus be removed.\n+\n+ - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n+ HTTP server. These scripts have been unmaintained for a significant amount of\n+ time and will be removed.\n+\n+ - git-filter-branch(1) can be used to rewrite history of a repository. It is\n+ very slow, hard to use and has many gotchas. It will thus be removed in favor\n+ of [git-filter-repo](https://github.com/newren/git-filter-repo).\n+\n+ - The \"dashed form\", i.e. support for calling `git-` instead of\n+ `git ` in scripts, has been deprecated for a long time and will be\n+ removed.\n+\n+ - The command to import patches from Quilt seems to be used rarely, if\n+ ever, and will be removed.\n+\n+ - Support for importing repositories from GNU Arch will be removed because\n+ it would not appear to have any users.\n+\n+ - Support for interacting with CVS repositories (via `cvsimport`,\n+ `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by\n+ the number of times these commands have been mentioned recently. The\n+ code has been essentially unmaintained, too, and will be removed.\n+\n+ - Support for grafting commits has long been superseded by git-replace(1).\n+ Grafts are inferior to replacement refs as the mechanism can lead to\n+ hard-to-diagnose problems when transferring objects between repositories.\n+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n+ 2014-03-05) and will be removed.\n+\n+ - git-pickaxe, an alias for git-blame(1), has been retired in acca687fa9\n+ (git-pickaxe: retire pickaxe, 2006-11-08) and will be removed.\n+\n+## Superseded features that will not be deprecated\n+\n+Some features have gained newer replacements that aim to improve the design in\n+certain ways. The fact that there is a replacement does not automatically mean\n+that the old way of doing things will eventually be removed. This section tracks\n+those superseded features.\n+\n+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As\n+ the maintenance burden of carrying both of these commands is negligible, both\n+ commands will stay.\n+\n+ - git-restore(1) and git-switch(1) have been introduced as a replacement for\n+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n+ of switching to git-restore(1) and git-switch(1) is contended, all three\n+ commands will stay.\n+\n+ - git-config(1) has learned to use subcommands that replace implicit actions\n+ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n+ --unset-all`). The action flags will not be removed in the next major Git\n+ release as there likely exist a lot of scripts out there that use the old\n+ syntax.\n+\n+ Cf. .\n\nbase-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f\n-- \n2.45.1.246.gb9cfe4845c.dirty\n\n"},{"id":"495579","messageId":"xmqqsey7ktn2.fsf@gitster.g","threadId":"61428","inReplyTo":"84c01f1b0a2d24d7de912606f548623601c0d715.1716555034.git.ps@pks.im","subject":"Re: [PATCH v3] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-24T17:27:13Z","receivedAt":"2024-05-24T17:27:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> case, most of the proposed deprecations didn't get much pushback. I'm\n> less sure whether this is because people didn't look, or because they\n> silently agree with what I propose for deprecation.\n\nOr because I explicitly said that first we'll brainstorm, in order\nto encourage generation of more ideas, without shooting other\npeople's ideas down?\n\n> Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++\n> 1 file changed, 122 insertions(+)\n> create mode 100644 Documentation/UpcomingBreakingChanges.md\n>\n> diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md\n> new file mode 100644\n> index 0000000000..d057ef7cb3\n> --- /dev/null\n> +++ b/Documentation/UpcomingBreakingChanges.md\n> @@ -0,0 +1,122 @@\n> +# Upcoming breaking changes\n> +\n> +The Git project aims to ensure backwards compatibility to the best extent\n> +possible. Minor releases will not break backwards compatibility unless there is\n> +a very strong reason to do so, like for example a security vulnerability.\n> +\n> +Regardless of that, due to the age of the Git project, it is only natural to\n> +accumulate a backlog of backwards-incompatible changes that will eventually be\n> +required to keep the project aligned with a changing world. These changes fall\n> +into several categories:\n> +\n> + - Changes to long established defaults.\n> +\n> + - Concepts that have been replaced with a superior design.\n> +\n> + - Concepts, commands, configuration or options that have been lacking in major\n> + ways and that cannot be fixed.\n> +\n> +The Git project will thus irregularly release major versions that deliberately\n> +break backwards compatibility with older versions. This is done to ensure that\n> +Git remains relevant, safe and maintainable going forward. The release cadence\n> +of major versions is typically measured in multiple years.\n> +\n> +The intent of this document is to track upcoming deprecations for the next major\n> +Git release. Furthermore, this document also tracks what will _not_ be\n> +deprecated. This is done such that the outcome of discussions documente both\n> +when the discussion favors deprecation, but also when it rejects a deprecation.\n> +\n> +It is supposed to be a living document where proposed changes and\n> +deprecations are up for discussion.\n\nOK.\n\n> +## Git 3.0\n\nQuestion. \n\nWill we have \"## Git 4.0\" etc., to indicate the timelines (some\nstuff we might eventually replace/change, but we may not ready yet\nby the time 3.0 comes)? Or do we assme that an idea we agree enough\non to add to this document would all be ready to be implemented by\n3.0?\n\n> +### Changes\n> +\n> + - The default initial branch name will be changed from \"master\" to \"main\".\n> +\n> + Cf. ,\n> + .\n\nForcing readers to read entire threads for these two discussions\nsomehow feels brutal at least to me. And reading only these two\nindividual messages does not give readers much insight.\n\nSaying \"this was discussed in the past in late 2020, and because\nmajor hosting sites give 'main' as the initial branch by default for\nnew users unless configured these days, we will match to avoid end\nuser confusion\", if we want to explain why we are changing it,\nshould be sufficient. But seeing that the other two items below do\nnot have any such explanation, we may be better of not having it\nhere, perhaps?\n\nI take this iteration to illustrate the format of items (and what\nkinds of items) we want to have in the document. If the proposal\nmade by the above item is:\n\n Once we have a discussion thread that shows clear concensus\n (neither of the above two are not), we'd record the decision and\n have a reference to the thread.\n\nthen I 100% agree with the plan for this document.\n\n> + - The default hash function for new repositories will be changed from \"sha1\"\n> + to \"sha256\".\n> +\n> + - The default ref backend for new repositories will be changed from \"files\" to\n> + \"reftable\".\n> +\n> +### Removals\n> +\n> + - git-http-push(1) can be used to push objects to a remote repository via\n> + HTTP/DAV. Support for write support via WebDAV is not in widespread use\n> + nowadays anymore and will be removed together with the command.\n> +\n> + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n> + server like Apache. The protocol has not seen any updates recently and is\n> + neither compatible with alternative hash functions nor with alternative ref\n> + backends. It will thus be removed.\n> +\n> + - git-update-server-info(1) generates data required when serving data via the\n> + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n> + anymore and will be removed together with the protocol. This includes the\n> + \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n> + `git repack -n` flag.\n> +\n> + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n> + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n> + concept has long been replaced by remotes and will thus be removed.\n\n\"remotes\" -> \"the 'remotes.*.*' configuration variables\", perhaps?\n\n> + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n> + HTTP server. These scripts have been unmaintained for a significant amount of\n> + time and will be removed.\n\nDo we want to give plausible alternatives (or merely hinting\nexistence of alternatives might be sufficient)?\n\n> + - git-filter-branch(1) can be used to rewrite history of a repository. It is\n> + very slow, hard to use and has many gotchas. It will thus be removed in favor\n> + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n> +\n> + - The \"dashed form\", i.e. support for calling `git-` instead of\n> + `git ` in scripts, has been deprecated for a long time and will be\n> + removed.\n\nI find this questionable but as you said, we'll start from skeletal\nform of this document (without any items), have discussion thread on\neach of these items, and add back those we have concensus on, so\nI'll not further talk about this item in this message.\n\n> + - The command to import patches from Quilt seems to be used rarely, if\n> + ever, and will be removed.\n\nNot limited to this item, but do we want to mention in this document\nhow we measured the actual usage, which we base our deprecation\ndecision on? I do not think such a comment should be attached to\neach of these items (this one and the next one are proposed for the\nsame reason),...\n\n> + - Support for importing repositories from GNU Arch will be removed because\n> + it would not appear to have any users.\n\n... but in a preamble of the document, e.g., \"methodology and\ncriteria we used to propose these removals\". Random ideas that may\nor may not work:\n\n - debian popcon?\n - google trends, counting the appearance of queries?\n - telemetry from commands that call home (we do not have any)?\n\n> + - git-config(1) has learned to use subcommands that replace implicit actions\n> + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> + --unset-all`). The action flags will not be removed in the next major Git\n> + release as there likely exist a lot of scripts out there that use the old\n> + syntax.\n> +\n> + Cf. .\n\nThis is a good example of \"we had a concensus back when this was\ndiscussed; see the thread this message is on\". I think it would be\nbeneficial to write down what these references _mean_ at the beginning\nof the document, e.g.\n\n When this document refers to a message-ID, you can visit\n\n https://lore.kernel.org/git/$message_id/\n\n to see the message and its surrounding discussion. Such a\n reference is there to make it easier for you to find that the\n project reached concensus on the described item back then. As\n this is a living document, and the environment surrounding the\n project changes over time, an earlier decision to deprecate or\n change something may need to be revisited from time to time, so\n do not take these references to mean \"it is settled, do not\n waste our time bringing it up again\".\n\nor something like that.\n\nThanks.\n\n"},{"id":"495924","messageId":"ZlhrY6y829bcHVoZ@tanuki","threadId":"61428","inReplyTo":"xmqqsey7ktn2.fsf@gitster.g","subject":"Re: [PATCH v3] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-30T12:04:51Z","receivedAt":"2024-05-30T12:04:58Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, May 24, 2024 at 10:27:13AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > case, most of the proposed deprecations didn't get much pushback. I'm\n> > less sure whether this is because people didn't look, or because they\n> > silently agree with what I propose for deprecation.\n> \n> Or because I explicitly said that first we'll brainstorm, in order\n> to encourage generation of more ideas, without shooting other\n> people's ideas down?\n\nFair, I guess.\n\n[snip]\n> > +## Git 3.0\n> \n> Question. \n> \n> Will we have \"## Git 4.0\" etc., to indicate the timelines (some\n> stuff we might eventually replace/change, but we may not ready yet\n> by the time 3.0 comes)? Or do we assme that an idea we agree enough\n> on to add to this document would all be ready to be implemented by\n> 3.0?\n\nGood question. For now I have added such items to the \"Superseded\nfeatures that will not be deprecated\" section, with a hint that we may\nrevisit the deprecation in the future. E.g. for the git-config(1)\nactions I say the following:\n\n The action flags will not be removed in the next major Git release\n as there likely exist a lot of scripts out there that use the old\n syntax.\n\nI think that this is easiest to manage for other features where we are\nnot yet ready to commit to a deprecation, as well, due to whatever\nreason. Those items can be added along with a condition that, once met,\nmay prompt us to revisit a deprecation.\n\n> > +### Changes\n> > +\n> > + - The default initial branch name will be changed from \"master\" to \"main\".\n> > +\n> > + Cf. ,\n> > + .\n> \n> Forcing readers to read entire threads for these two discussions\n> somehow feels brutal at least to me. And reading only these two\n> individual messages does not give readers much insight.\n> \n> Saying \"this was discussed in the past in late 2020, and because\n> major hosting sites give 'main' as the initial branch by default for\n> new users unless configured these days, we will match to avoid end\n> user confusion\", if we want to explain why we are changing it,\n> should be sufficient. But seeing that the other two items below do\n> not have any such explanation, we may be better of not having it\n> here, perhaps?\n> \n> I take this iteration to illustrate the format of items (and what\n> kinds of items) we want to have in the document. If the proposal\n> made by the above item is:\n> \n> Once we have a discussion thread that shows clear concensus\n> (neither of the above two are not), we'd record the decision and\n> have a reference to the thread.\n> \n> then I 100% agree with the plan for this document.\n\nYes, that's my intent. The bullet item should be self-explaining,\npotentially with one or two sentences explaining why. The reference to\nthe mailing list thread is supposed to give a pointer where, when and\nwhy this decision was made so that people can revisit the discussion.\n\nSo the two bullet points below are certainly quite lazy because they do\nnot provide any context whatsoever.\n\n> > + - The default hash function for new repositories will be changed from \"sha1\"\n> > + to \"sha256\".\n> > +\n> > + - The default ref backend for new repositories will be changed from \"files\" to\n> > + \"reftable\".\n> > +\n> > +### Removals\n> > +\n> > + - git-http-push(1) can be used to push objects to a remote repository via\n> > + HTTP/DAV. Support for write support via WebDAV is not in widespread use\n> > + nowadays anymore and will be removed together with the command.\n> > +\n> > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP\n> > + server like Apache. The protocol has not seen any updates recently and is\n> > + neither compatible with alternative hash functions nor with alternative ref\n> > + backends. It will thus be removed.\n> > +\n> > + - git-update-server-info(1) generates data required when serving data via the\n> > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose\n> > + anymore and will be removed together with the protocol. This includes the\n> > + \"receive.updateServerInfo\" and \"repack.updateServerInfo\" config keys and the\n> > + `git repack -n` flag.\n> > +\n> > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify\n> > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This\n> > + concept has long been replaced by remotes and will thus be removed.\n> \n> \"remotes\" -> \"the 'remotes.*.*' configuration variables\", perhaps?\n> \n> > + - \"gitweb\" and git-instaweb(1) can be used to browse Git repositories via an\n> > + HTTP server. These scripts have been unmaintained for a significant amount of\n> > + time and will be removed.\n> \n> Do we want to give plausible alternatives (or merely hinting\n> existence of alternatives might be sufficient)?\n\nI guess that would be solutions like cgit, right? While those\nrecommendations may go stale over time, I still think it'd be worthwhile\nto help our users in case they do rely on any deprecated feature.\n\n> > + - git-filter-branch(1) can be used to rewrite history of a repository. It is\n> > + very slow, hard to use and has many gotchas. It will thus be removed in favor\n> > + of [git-filter-repo](https://github.com/newren/git-filter-repo).\n> > +\n> > + - The \"dashed form\", i.e. support for calling `git-` instead of\n> > + `git ` in scripts, has been deprecated for a long time and will be\n> > + removed.\n> \n> I find this questionable but as you said, we'll start from skeletal\n> form of this document (without any items), have discussion thread on\n> each of these items, and add back those we have concensus on, so\n> I'll not further talk about this item in this message.\n\nI'd propose to have one (hopefully uncontroversial) item per section\njust to demonstrate how the format is supposed to look like. But other\nthan that I'm happy to drop most of these items.\n\n> > + - The command to import patches from Quilt seems to be used rarely, if\n> > + ever, and will be removed.\n> \n> Not limited to this item, but do we want to mention in this document\n> how we measured the actual usage, which we base our deprecation\n> decision on? I do not think such a comment should be attached to\n> each of these items (this one and the next one are proposed for the\n> same reason),...\n> \n> > + - Support for importing repositories from GNU Arch will be removed because\n> > + it would not appear to have any users.\n> \n> ... but in a preamble of the document, e.g., \"methodology and\n> criteria we used to propose these removals\". Random ideas that may\n> or may not work:\n> \n> - debian popcon?\n> - google trends, counting the appearance of queries?\n> - telemetry from commands that call home (we do not have any)?\n\nThat would certainly be helpful to give us a better base to argue.\n\n> > + - git-config(1) has learned to use subcommands that replace implicit actions\n> > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config\n> > + --unset-all`). The action flags will not be removed in the next major Git\n> > + release as there likely exist a lot of scripts out there that use the old\n> > + syntax.\n> > +\n> > + Cf. .\n> \n> This is a good example of \"we had a concensus back when this was\n> discussed; see the thread this message is on\". I think it would be\n> beneficial to write down what these references _mean_ at the beginning\n> of the document, e.g.\n> \n> When this document refers to a message-ID, you can visit\n> \n> https://lore.kernel.org/git/$message_id/\n> \n> to see the message and its surrounding discussion. Such a\n> reference is there to make it easier for you to find that the\n> project reached concensus on the described item back then. As\n> this is a living document, and the environment surrounding the\n> project changes over time, an earlier decision to deprecate or\n> change something may need to be revisited from time to time, so\n> do not take these references to mean \"it is settled, do not\n> waste our time bringing it up again\".\n> \n> or something like that.\n\nGood idea, will do.\n\nPatrick\n"},{"id":"495974","messageId":"cover.1717141598.git.ps@pks.im","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"[PATCH v4 0/4] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-31T07:56:27Z","receivedAt":"2024-05-31T07:56:34Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nthis is the fourth version of my patch series that documents upcoming\nbreaking changes.\n\nI have restructured this series now, booting out most of the proposed\ndeprecations. This is not because I think that those deprecations\nshouldn't be done, but merely to bring this series into a format that\ncan be merged.\n\nThe first patch introduces the document in a skeletal form. The next\nthree patches then introduce one item each to the three sections that we\nhave in this document. The intent of this is to start out with examples\nof how this should look like. I have tried to pick topics which may be\nthe least controversial ones for each of those sections while still\nbeing interesting enough to demonstrate the proposed format. Let's see\nwhether I succeeded with that goal :)\n\nAs said, I do not have the intent to shut down any of the other proposed\ndeprecations. When this document lands, I'd encourage folks to propose\ntheir deprecations in standalone threads, ideally together with a patch\nto \"BreakingChanges.md\".\n\nYou may have noticed that I dropped the \"Upcoming\" prefix from\n\"UpcomingBreakingChanges.md\". This is supposed to reflect the fact that\nwe also have a section that point out features that we are _not_\ndeprecating. Those aren't upcoming, so I thought a rename makes sense.\n\nThanks!\n\nPatrick\n\nPatrick Steinhardt (4):\n docs: introduce document to announce breaking changes\n BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n BreakingChanges: document removal of grafting\n BreakingChanges: document that we do not plan to deprecate\n git-checkout\n\n Documentation/BreakingChanges.md | 113 +++++++++++++++++++++++++++++++\n 1 file changed, 113 insertions(+)\n create mode 100644 Documentation/BreakingChanges.md\n\n\nbase-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"495975","messageId":"993b9363484627cd828362e39f15c4905ecaf3e2.1717141598.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717141598.git.ps@pks.im","subject":"[PATCH v4 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-31T07:56:32Z","receivedAt":"2024-05-31T07:56:37Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that tracks such breaking changes, but also\ndeprecations which we are not willing to go through with, to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go,\n both in the case where we want to deprecate, but also in the case\n where we don't want to deprecate a specific feature.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++\n 1 file changed, 66 insertions(+)\n create mode 100644 Documentation/BreakingChanges.md\n\ndiff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md\nnew file mode 100644\nindex 0000000000..d8a26c9bf9\n--- /dev/null\n+++ b/Documentation/BreakingChanges.md\n@@ -0,0 +1,66 @@\n+# Upcoming breaking changes\n+\n+The Git project aims to ensure backwards compatibility to the best extent\n+possible. Minor releases will not break backwards compatibility unless there is\n+a very strong reason to do so, like for example a security vulnerability.\n+\n+Regardless of that, due to the age of the Git project, it is only natural to\n+accumulate a backlog of backwards-incompatible changes that will eventually be\n+required to keep the project aligned with a changing world. These changes fall\n+into several categories:\n+\n+ - Changes to long established defaults.\n+\n+ - Concepts that have been replaced with a superior design.\n+\n+ - Concepts, commands, configuration or options that have been lacking in major\n+ ways and that cannot be fixed.\n+\n+The Git project will thus irregularly release major versions that deliberately\n+break backwards compatibility with older versions. This is done to ensure that\n+Git remains relevant, safe and maintainable going forward. The release cadence\n+of major versions is typically measured in multiple years.\n+\n+The intent of this document is to track upcoming deprecations for the next\n+major Git release. Furthermore, this document also tracks what will _not_ be\n+deprecated. This is done such that the outcome of discussions documente both\n+when the discussion favors deprecation, but also when it rejects a deprecation.\n+\n+Items should have a self-sufficient explanation why we want or do not want to\n+deprecate a given feature. If there are alternatives to the deprecated feature,\n+those alternatives should be pointed out to our users.\n+\n+All items should be accompanied by references to relevant mailing list threads\n+where the deprecation was discussed. These references use message-IDs, which\n+can visited via\n+\n+ https://lore.kernel.org/git/$message_id/\n+\n+to see the message and its surrounding discussion. Such a reference is there to\n+make it easier for you to find how the project reached concensus on the\n+described item back then.\n+\n+This is a living document as the environment surrounding the project changes\n+over time. An earlier decision to deprecate or change something may need to be\n+revisited from time to time. So do not take items on this list to mean \"it is\n+settled, do not waste our time bringing it up again\".\n+\n+## Git 3.0\n+\n+The following subsections document upcoming breaking changes for Git 3.0. There\n+is no planned release date for this major version yet.\n+\n+Proposed changes and removals only include items which are \"ready\" to be done.\n+In other words, this is not supposed to be a wishlist of features that should\n+be changed to or replaced in case the alternative was implemented already.\n+\n+### Changes\n+\n+### Removals\n+\n+## Superseded features that will not be deprecated\n+\n+Some features have gained newer replacements that aim to improve the design in\n+certain ways. The fact that there is a replacement does not automatically mean\n+that the old way of doing things will eventually be removed. This section tracks\n+those superseded features.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"495976","messageId":"7c84b2f957595a3d8bc6d28970a009339c5fbf5c.1717141598.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717141598.git.ps@pks.im","subject":"[PATCH v4 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-31T07:56:37Z","receivedAt":"2024-05-31T07:56:41Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Starting with 8e42eb0e9a (doc: sha256 is no longer experimental,\n2023-07-31), the \"sha256\" object format is no longer considered to be\nexperimental. Furthermore, the SHA-1 hash function is actively\nrecommended against by for example NIST and FIPS 140-2, and attacks\nagainst it are becoming more practical both due to new weaknesses\n(SHAppening, SHAttered, Shambles) and due to the ever-increasing\ncomputing power. It is only a matter of time before it can be considered\nto be broken completely.\n\nLet's plan for this event by being active instead of waiting for it to\nhappend and announce that the default object format is going to change\nfrom \"sha1\" to \"sha256\" with Git 3.0.\n\nAll major Git implementations (libgit2, JGit, go-git) support the\n\"sha256\" object format and are thus prepared for this change. The most\nimportant missing piece in the puzzle is support in forges. But while\nGitLab recently gained experimental support for the \"sha256\" object\nformat though, to the best of my knowledge GitHub doesn't support it\nyet. Ideally, announcing this upcoming change will encourage forges to\nstart building that support.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++\n 1 file changed, 27 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md\nindex d8a26c9bf9..1b0a357e65 100644\n--- a/Documentation/BreakingChanges.md\n+++ b/Documentation/BreakingChanges.md\n@@ -56,6 +56,33 @@ be changed to or replaced in case the alternative was implemented already.\n \n ### Changes\n \n+ - The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n+ recommended against in FIPS 140-2 and similar certifications. Furthermore,\n+ there are practical attacks on SHA-1 that weaken its cryptographic properties:\n+\n+ - The SHAppening (2015). The first demonstration of a practical attack\n+ against SHA-1 with 2^57 operations.\n+\n+ - SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n+\n+ - Birthday-Near-Collision (2019). This attack allows for chosen prefix\n+ attacks with 2^68 operations.\n+\n+ - Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n+ operations.\n+\n+ While we have protections in place against known attacks, it is expected\n+ that more attacks against SHA-1 will be found by future research. Paired\n+ with the ever-growing capability of hardware, it is only a matter of time\n+ before SHA-1 will be considered broken completely. We want to be prepared\n+ and will thus change the default hash algorithm to \"sha256\" for newly\n+ initialized repositories.\n+\n+ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n+ <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n+ .\n+\n ### Removals\n \n ## Superseded features that will not be deprecated\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"495977","messageId":"91d78490c2358b417e32694d8dc125b93a4e389d.1717141598.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717141598.git.ps@pks.im","subject":"[PATCH v4 3/4] BreakingChanges: document removal of grafting","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-31T07:56:41Z","receivedAt":"2024-05-31T07:56:46Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The grafting mechanism for objects has been deprecated in e650d0643b\n(docs: mark info/grafts as outdated, 2014-03-05), which is more than a\ndecade ago. The mechanism can lead to hard-to-debug issues and has a\nsuperior replacement with replace refs.\n\nFollow through with the deprecation and mark grafts for removal in Git\n3.0.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.md | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md\nindex 1b0a357e65..14c0972b08 100644\n--- a/Documentation/BreakingChanges.md\n+++ b/Documentation/BreakingChanges.md\n@@ -85,6 +85,14 @@ be changed to or replaced in case the alternative was implemented already.\n \n ### Removals\n \n+ - Support for grafting commits has long been superseded by git-replace(1).\n+ Grafts are inferior to replacement refs as the mechanism can lead to\n+ hard-to-diagnose problems when transferring objects between repositories.\n+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n+ 2014-03-05) and will be removed.\n+\n+ Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n+\n ## Superseded features that will not be deprecated\n \n Some features have gained newer replacements that aim to improve the design in\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"495978","messageId":"40594bda5c8050c2a863df8c9f6f92cd98ea8484.1717141598.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717141598.git.ps@pks.im","subject":"[PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-31T07:56:46Z","receivedAt":"2024-05-31T07:56:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The git-checkout(1) command is seen by many as hard to understand\nbecause it connects two somewhat unrelated features: switching between\nbranches and restoring worktree files from arbitrary revisions. In 2019,\nwe thus implemented two new commands git-switch(1) and git-restore(1) to\nsplit out these separate concerns into standalone functions.\n\nThis \"replacement\" of git-checkout(1) has repeatedly triggered concerns\nfor our userbase that git-checkout(1) will eventually go away. This is\nnot the case though: the use of that command is still widespread, and it\nis not expected that this will change anytime soon.\n\nDocument that neither of these commands will not go away anytime soon.\nThis decision may be revisited in case we ever figure out that most\neveryone has given up on any of the commands.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.md | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md\nindex 14c0972b08..fb2c8ddf5a 100644\n--- a/Documentation/BreakingChanges.md\n+++ b/Documentation/BreakingChanges.md\n@@ -99,3 +99,15 @@ Some features have gained newer replacements that aim to improve the design in\n certain ways. The fact that there is a replacement does not automatically mean\n that the old way of doing things will eventually be removed. This section tracks\n those superseded features.\n+\n+ - git-restore(1) and git-switch(1) have been introduced as a replacement for\n+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n+ of switching to git-restore(1) and git-switch(1) is contended, all three\n+ commands will stay.\n+\n+ This decision may get revisited in case we ever figure out that there are\n+ almost no users of any of the commands anymore.\n+\n+ Cf. ,\n+ ,\n+ <112b6568912a6de6672bf5592c3a718e@manjaro.org>.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"495982","messageId":"xmqqr0dijrrh.fsf@gitster.g","threadId":"61428","inReplyTo":"cover.1717141598.git.ps@pks.im","subject":"Re: [PATCH v4 0/4] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-31T08:43:30Z","receivedAt":"2024-05-31T08:43:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> You may have noticed that I dropped the \"Upcoming\" prefix from\n> \"UpcomingBreakingChanges.md\". This is supposed to reflect the fact that\n> we also have a section that point out features that we are _not_\n> deprecating. Those aren't upcoming, so I thought a rename makes sense.\n\nI do not mind missing upcoming, but why markdown? The mark-up we as\nthe project chose is AsciiDoc and unless there is a compelling reason\nto use something else, we should stick to it.\n\nYes, README.md is not AsciiDoc but that is primarily because what\nGitHub does on the project page.\n"},{"id":"495985","messageId":"ZlmxaNF94XbaTxxY@tanuki","threadId":"61428","inReplyTo":"xmqqr0dijrrh.fsf@gitster.g","subject":"Re: [PATCH v4 0/4] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-05-31T11:15:52Z","receivedAt":"2024-05-31T11:16:00Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, May 31, 2024 at 01:43:30AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > You may have noticed that I dropped the \"Upcoming\" prefix from\n> > \"UpcomingBreakingChanges.md\". This is supposed to reflect the fact that\n> > we also have a section that point out features that we are _not_\n> > deprecating. Those aren't upcoming, so I thought a rename makes sense.\n> \n> I do not mind missing upcoming, but why markdown? The mark-up we as\n> the project chose is AsciiDoc and unless there is a compelling reason\n> to use something else, we should stick to it.\n> \n> Yes, README.md is not AsciiDoc but that is primarily because what\n> GitHub does on the project page.\n\nOh well, fair enough. I'll convert it to AsciiDoc in the next version,\nbut will wait a bit longer for feedback.\n\nThanks!\n\nPatrick\n"},{"id":"496021","messageId":"xmqqr0dhgc1e.fsf@gitster.g","threadId":"61428","inReplyTo":"993b9363484627cd828362e39f15c4905ecaf3e2.1717141598.git.ps@pks.im","subject":"Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-31T16:51:25Z","receivedAt":"2024-05-31T16:51:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Over time, Git has grown quite a lot. With this evolution, many ideas\n> that were sensible at the time they were introduced are not anymore and\n> are thus considered to be deprecated. And while some deprecations may be\n> noted in manpages, most of them are actually deprecated in the \"hive\n> mind\" of the Git community, only.\n>\n> Introduce a new document that tracks such breaking changes, but also\n> deprecations which we are not willing to go through with, to address\n> this issue. This document serves multiple purposes:\n>\n> - It is a way to facilitate discussion around proposed deprecations.\n>\n> - It allows users to learn about deprecations and speak up in case\n> they have good reasons why a certain feature should not be\n> deprecated.\n>\n> - It states intent and documents where the Git project wants to go,\n> both in the case where we want to deprecate, but also in the case\n> where we don't want to deprecate a specific feature.\n>\n> The document is _not_ intended to cast every single discussion into\n> stone. It is supposed to be a living document that may change over time\n> when there are good reasons for it to change.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++\n> 1 file changed, 66 insertions(+)\n> create mode 100644 Documentation/BreakingChanges.md\n>\n> diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md\n> new file mode 100644\n> index 0000000000..d8a26c9bf9\n> --- /dev/null\n> +++ b/Documentation/BreakingChanges.md\n> @@ -0,0 +1,66 @@\n> +# Upcoming breaking changes\n> +\n> +The Git project aims to ensure backwards compatibility to the best extent\n> +possible. Minor releases will not break backwards compatibility unless there is\n> +a very strong reason to do so, like for example a security vulnerability.\n> +\n> +Regardless of that, due to the age of the Git project, it is only natural to\n> +accumulate a backlog of backwards-incompatible changes that will eventually be\n> +required to keep the project aligned with a changing world. These changes fall\n> +into several categories:\n> +\n> + - Changes to long established defaults.\n> +\n> + - Concepts that have been replaced with a superior design.\n> +\n> + - Concepts, commands, configuration or options that have been lacking in major\n> + ways and that cannot be fixed.\n\nThe first two are easy to imagine. If we change the default, people\nmay have to retrain their fingers or rewrite their scripts. If\n\"log\" that came later is so good that even those who were using\n\"whatchanged\" have long switched to it, there will come time when\nnobody even notices a removal of \"whatchanged\".\n\nBut the third one is puzzling. If something falls into the \"cannot\nbe fixed\" category, is it still one of \"These changes\" that \"will\neventually be required to [be made]\"?\n\n> +The Git project will thus irregularly release major versions that deliberately\n> +break backwards compatibility with older versions. This is done to ensure that\n> +Git remains relevant, safe and maintainable going forward. The release cadence\n> +of major versions is typically measured in multiple years.\n\nReleases vX.Y.Z (0 < Z) are \"maintenance releases\", and I have been\ncalling vX.Y.0 \"feature releases\" instead of calling them \"major\nversions\", so the above use of the phrase \"major version\" can fit\nin, but a more descriptive name, e.g., \"breaking versions\", might\nconvey the intention better, perhaps?\n\nIt may be more assuring to cite the last time such a breaking\nversion happened. Was \"Git 2.0\" a breaking version? If so, when\ndid it happen? Were there other breaking versions in the past?\n\n> +The intent of this document is to track upcoming deprecations for the next\n> +major Git release. Furthermore, this document also tracks what will _not_ be\n> +deprecated. This is done such that the outcome of discussions documente both\n> +when the discussion favors deprecation, but also when it rejects a deprecation.\n\nWe seem to focus on removals and changes; will there be a case where\nan upcoming addition is equally disrupting as removing an established\nthing? If we wanted to avoid focusing on deprecation/removals too\nnarrowly, we could tweak the wording below, with \"deprecate a given\nfeature\" -> \"make the described change\", etc.\n\n> +Items should have a self-sufficient explanation why we want or do not want to\n> +deprecate a given feature. If there are alternatives to the deprecated feature,\n> +those alternatives should be pointed out to our users.\n> ...\n\nOK.\n\n> +## Git 3.0\n> +\n> +The following subsections document upcoming breaking changes for Git 3.0. There\n> +is no planned release date for this major version yet.\n\n\"upcoming breaking changes for\" -> \"breaking changes we plan to make in\"?\n\n> +Proposed changes and removals only include items which are \"ready\" to be done.\n> +In other words, this is not supposed to be a wishlist of features that should\n> +be changed to or replaced in case the alternative was implemented already.\n\nOK.\n\n> +### Changes\n> +\n> +### Removals\n> +\n> +## Superseded features that will not be deprecated\n> +\n> +Some features have gained newer replacements that aim to improve the design in\n> +certain ways. The fact that there is a replacement does not automatically mean\n> +that the old way of doing things will eventually be removed. This section tracks\n> +those superseded features.\n\nAs the title says \"superseded\", to help non native speakers like me,\nlet's use a different and easier phrase with the same meaning in the\nbody text. \"... tracks those features with newer alternatives\",\nperhaps?\n\nThanks.\n"},{"id":"496022","messageId":"xmqqikytgbmc.fsf@gitster.g","threadId":"61428","inReplyTo":"7c84b2f957595a3d8bc6d28970a009339c5fbf5c.1717141598.git.ps@pks.im","subject":"Re: [PATCH v4 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-31T17:00:27Z","receivedAt":"2024-05-31T17:00:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Let's plan for this event by being active instead of waiting for it to\n> happend and announce that the default object format is going to change\n> from \"sha1\" to \"sha256\" with Git 3.0.\n\n\"happened\" -> \"happen,\"\n\n> All major Git implementations (libgit2, JGit, go-git) support the\n> \"sha256\" object format and are thus prepared for this change. The most\n> important missing piece in the puzzle is support in forges. But while\n> GitLab recently gained experimental support for the \"sha256\" object\n> format though, to the best of my knowledge GitHub doesn't support it\n> yet. Ideally, announcing this upcoming change will encourage forges to\n> start building that support.\n\n;-) Nevertheless, we probably want some of that in the body text.\n\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++\n> 1 file changed, 27 insertions(+)\n>\n> diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md\n> index d8a26c9bf9..1b0a357e65 100644\n> --- a/Documentation/BreakingChanges.md\n> +++ b/Documentation/BreakingChanges.md\n> @@ -56,6 +56,33 @@ be changed to or replaced in case the alternative was implemented already.\n> \n> ### Changes\n> \n> + - The default hash function for new repositories will be changed from \"sha1\"\n> + to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n> + recommended against in FIPS 140-2 and similar certifications. Furthermore,\n> + there are practical attacks on SHA-1 that weaken its cryptographic properties:\n> +\n> + - The SHAppening (2015). The first demonstration of a practical attack\n> + against SHA-1 with 2^57 operations.\n> +\n> + - SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n> +\n> + - Birthday-Near-Collision (2019). This attack allows for chosen prefix\n> + attacks with 2^68 operations.\n> +\n> + - Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n> + operations.\n> +\n> + While we have protections in place against known attacks, it is expected\n> + that more attacks against SHA-1 will be found by future research. Paired\n> + with the ever-growing capability of hardware, it is only a matter of time\n> + before SHA-1 will be considered broken completely. We want to be prepared\n> + and will thus change the default hash algorithm to \"sha256\" for newly\n> + initialized repositories.\n> +\n> + Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n> + <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n> + .\n\nWe probably need to at least briefly mention external constraints\nhere. Even though in our ideal world, what we say here will force\nothers like GitHub to follow, in the real world that is not always\nthe case. As this particular commit is about establishing the\npattern, expected form of each entry, how about adding convention to\nhave a paragraph on \"foreseen risks\", in addition to the \"what we\nplan to do\", and \"why we want to go there\" we see above?\n\n> ### Removals\n> \n> ## Superseded features that will not be deprecated\n\nThanks.\n"},{"id":"496023","messageId":"xmqqcyp1gbej.fsf@gitster.g","threadId":"61428","inReplyTo":"40594bda5c8050c2a863df8c9f6f92cd98ea8484.1717141598.git.ps@pks.im","subject":"Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-31T17:05:08Z","receivedAt":"2024-05-31T17:05:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> The git-checkout(1) command is seen by many as hard to understand\n> because it connects two somewhat unrelated features: switching between\n> branches and restoring worktree files from arbitrary revisions. In 2019,\n> we thus implemented two new commands git-switch(1) and git-restore(1) to\n> split out these separate concerns into standalone functions.\n>\n> This \"replacement\" of git-checkout(1) has repeatedly triggered concerns\n> for our userbase that git-checkout(1) will eventually go away. This is\n> not the case though: the use of that command is still widespread, and it\n> is not expected that this will change anytime soon.\n>\n> Document that neither of these commands will not go away anytime soon.\n\n\"neither\" -> \"none\"? It is accepted to use neither to pick among\nthree things these days, but the latter is clearer.\n\n"},{"id":"496034","messageId":"Zlpe0lOjR45gXYXI@teonanacatl.net","threadId":"61428","inReplyTo":"xmqqcyp1gbej.fsf@gitster.g","subject":"Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2024-05-31T23:35:46Z","receivedAt":"2024-05-31T23:35:57Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n>> The git-checkout(1) command is seen by many as hard to understand\n>> because it connects two somewhat unrelated features: switching between\n>> branches and restoring worktree files from arbitrary revisions. In 2019,\n>> we thus implemented two new commands git-switch(1) and git-restore(1) to\n>> split out these separate concerns into standalone functions.\n>>\n>> This \"replacement\" of git-checkout(1) has repeatedly triggered concerns\n>> for our userbase that git-checkout(1) will eventually go away. This is\n>> not the case though: the use of that command is still widespread, and it\n>> is not expected that this will change anytime soon.\n>>\n>> Document that neither of these commands will not go away anytime soon.\n> \n> \"neither\" -> \"none\"? It is accepted to use neither to pick among\n> three things these days, but the latter is clearer.\n\nI think 'will not' should lose the 'not' as well:\n\n Document that neither|none of these commands will go\n away anytime soon.\n\nAlternately, the neither/none question could be resolved by\ndropping it entirely:\n\n Document that these commands will not go away anytime\n soon.\n\nI'm not sure that's better; it leaves ambiguity about what\n\"these commands\" includes.\n\nMaybe:\n\n Document that all three commands will remain for the\n foreseeable future.\n\nBut after writing all that, I only just noticed this is in\nthe commit message. And while that's important, the more\nimportant content of the change itself uses clear language\nto say all three commands will stay. :)\n\n-- \nTodd\n"},{"id":"496069","messageId":"cover.1717402497.git.ps@pks.im","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"[PATCH v5 0/4] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-03T09:28:18Z","receivedAt":"2024-06-03T09:28:26Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nthis is another iteration of my patch series that intends to start\ntracking upcoming breaking changes in Git.\n\nChanges compared to v4:\n\n - Converted the document to use AsciiDoc instead of MarkDown.\n\n - Reword \"major release\" to \"breaking release\".\n\n - Note Git 2.0, which is the last major breaking release.\n\n - Note that minor bug fixes that lead to user visible changes in\n behavior do not require a breaking release.\n\n - Clarify that misdesigned features may be removed without\n replacement, if necessary.\n\n - Fix double negation in commit message of the last commit.\n\nThanks!\n\nPatrick\n\nPatrick Steinhardt (4):\n docs: introduce document to announce breaking changes\n BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n BreakingChanges: document removal of grafting\n BreakingChanges: document that we do not plan to deprecate\n git-checkout\n\n Documentation/BreakingChanges.txt | 115 ++++++++++++++++++++++++++++++\n 1 file changed, 115 insertions(+)\n create mode 100644 Documentation/BreakingChanges.txt\n\nRange-diff against v4:\n1: 993b936348 ! 1: 67cb4de5cb docs: introduce document to announce breaking changes\n @@ Commit message\n \n Signed-off-by: Patrick Steinhardt \n \n - ## Documentation/BreakingChanges.md (new) ##\n + ## Documentation/BreakingChanges.txt (new) ##\n @@\n -+# Upcoming breaking changes\n ++= Upcoming breaking changes\n +\n +The Git project aims to ensure backwards compatibility to the best extent\n +possible. Minor releases will not break backwards compatibility unless there is\n @@ Documentation/BreakingChanges.md (new)\n +required to keep the project aligned with a changing world. These changes fall\n +into several categories:\n +\n -+ - Changes to long established defaults.\n ++* Changes to long established defaults.\n ++* Concepts that have been replaced with a superior design.\n ++* Concepts, commands, configuration or options that have been lacking in major\n ++ ways and that cannot be fixed and which will thus be removed without any\n ++ replacement.\n +\n -+ - Concepts that have been replaced with a superior design.\n ++Explicitly not included in this list are fixes to minor bugs that may cause a\n ++change in user-visible behavior.\n +\n -+ - Concepts, commands, configuration or options that have been lacking in major\n -+ ways and that cannot be fixed.\n ++The Git project irregularly releases breaking versions that deliberately break\n ++backwards compatibility with older versions. This is done to ensure that Git\n ++remains relevant, safe and maintainable going forward. The release cadence of\n ++breaking versions is typically measured in multiple years. The last breaking\n ++releases were:\n +\n -+The Git project will thus irregularly release major versions that deliberately\n -+break backwards compatibility with older versions. This is done to ensure that\n -+Git remains relevant, safe and maintainable going forward. The release cadence\n -+of major versions is typically measured in multiple years.\n ++* Git 2.0, released in May 2014.\n +\n +The intent of this document is to track upcoming deprecations for the next\n +major Git release. Furthermore, this document also tracks what will _not_ be\n @@ Documentation/BreakingChanges.md (new)\n +when the discussion favors deprecation, but also when it rejects a deprecation.\n +\n +Items should have a self-sufficient explanation why we want or do not want to\n -+deprecate a given feature. If there are alternatives to the deprecated feature,\n ++make the described change. If there are alternatives to the changed feature,\n +those alternatives should be pointed out to our users.\n +\n +All items should be accompanied by references to relevant mailing list threads\n @@ Documentation/BreakingChanges.md (new)\n +revisited from time to time. So do not take items on this list to mean \"it is\n +settled, do not waste our time bringing it up again\".\n +\n -+## Git 3.0\n ++== Git 3.0\n +\n +The following subsections document upcoming breaking changes for Git 3.0. There\n -+is no planned release date for this major version yet.\n ++is no planned release date for this breaking version yet.\n +\n +Proposed changes and removals only include items which are \"ready\" to be done.\n +In other words, this is not supposed to be a wishlist of features that should\n +be changed to or replaced in case the alternative was implemented already.\n +\n -+### Changes\n ++=== Changes\n +\n -+### Removals\n ++=== Removals\n +\n -+## Superseded features that will not be deprecated\n ++== Superseded features that will not be deprecated\n +\n +Some features have gained newer replacements that aim to improve the design in\n +certain ways. The fact that there is a replacement does not automatically mean\n +that the old way of doing things will eventually be removed. This section tracks\n -+those superseded features.\n ++those features with newer alternatives.\n2: 7c84b2f957 ! 2: b36ffcbaa6 BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n @@ Commit message\n \n Signed-off-by: Patrick Steinhardt \n \n - ## Documentation/BreakingChanges.md ##\n -@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already.\n + ## Documentation/BreakingChanges.txt ##\n +@@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alternative was implemented already.\n \n - ### Changes\n + === Changes\n \n -+ - The default hash function for new repositories will be changed from \"sha1\"\n -+ to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n -+ recommended against in FIPS 140-2 and similar certifications. Furthermore,\n -+ there are practical attacks on SHA-1 that weaken its cryptographic properties:\n ++* The default hash function for new repositories will be changed from \"sha1\"\n ++ to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n ++ recommended against in FIPS 140-2 and similar certifications. Furthermore,\n ++ there are practical attacks on SHA-1 that weaken its cryptographic properties:\n +++\n ++ ** The SHAppening (2015). The first demonstration of a practical attack\n ++ against SHA-1 with 2^57 operations.\n ++ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n ++ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix\n ++ attacks with 2^68 operations.\n ++ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n ++ operations.\n +++\n ++While we have protections in place against known attacks, it is expected\n ++that more attacks against SHA-1 will be found by future research. Paired\n ++with the ever-growing capability of hardware, it is only a matter of time\n ++before SHA-1 will be considered broken completely. We want to be prepared\n ++and will thus change the default hash algorithm to \"sha256\" for newly\n ++initialized repositories.\n +++\n ++Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n ++<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n ++.\n +\n -+ - The SHAppening (2015). The first demonstration of a practical attack\n -+ against SHA-1 with 2^57 operations.\n -+\n -+ - SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n -+\n -+ - Birthday-Near-Collision (2019). This attack allows for chosen prefix\n -+ attacks with 2^68 operations.\n -+\n -+ - Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n -+ operations.\n -+\n -+ While we have protections in place against known attacks, it is expected\n -+ that more attacks against SHA-1 will be found by future research. Paired\n -+ with the ever-growing capability of hardware, it is only a matter of time\n -+ before SHA-1 will be considered broken completely. We want to be prepared\n -+ and will thus change the default hash algorithm to \"sha256\" for newly\n -+ initialized repositories.\n -+\n -+ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n -+ <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n -+ .\n -+\n - ### Removals\n + === Removals\n \n - ## Superseded features that will not be deprecated\n + == Superseded features that will not be deprecated\n3: 91d78490c2 ! 3: 4142e472ac BreakingChanges: document removal of grafting\n @@ Commit message\n \n Signed-off-by: Patrick Steinhardt \n \n - ## Documentation/BreakingChanges.md ##\n -@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already.\n + ## Documentation/BreakingChanges.txt ##\n +@@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n \n - ### Removals\n + === Removals\n \n -+ - Support for grafting commits has long been superseded by git-replace(1).\n -+ Grafts are inferior to replacement refs as the mechanism can lead to\n -+ hard-to-diagnose problems when transferring objects between repositories.\n -+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n -+ 2014-03-05) and will be removed.\n ++* Support for grafting commits has long been superseded by git-replace(1).\n ++ Grafts are inferior to replacement refs as the mechanism can lead to\n ++ hard-to-diagnose problems when transferring objects between repositories.\n ++ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n ++ 2014-03-05) and will be removed.\n +++\n ++Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n +\n -+ Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n -+\n - ## Superseded features that will not be deprecated\n + == Superseded features that will not be deprecated\n \n Some features have gained newer replacements that aim to improve the design in\n4: 40594bda5c ! 4: 9ff94b6f32 BreakingChanges: document that we do not plan to deprecate git-checkout\n @@ Commit message\n not the case though: the use of that command is still widespread, and it\n is not expected that this will change anytime soon.\n \n - Document that neither of these commands will not go away anytime soon.\n + Document that all three commands will remain for the foreseeable future.\n This decision may be revisited in case we ever figure out that most\n everyone has given up on any of the commands.\n \n Signed-off-by: Patrick Steinhardt \n \n - ## Documentation/BreakingChanges.md ##\n -@@ Documentation/BreakingChanges.md: Some features have gained newer replacements that aim to improve the design in\n + ## Documentation/BreakingChanges.txt ##\n +@@ Documentation/BreakingChanges.txt: Some features have gained newer replacements that aim to improve the design in\n certain ways. The fact that there is a replacement does not automatically mean\n that the old way of doing things will eventually be removed. This section tracks\n - those superseded features.\n + those features with newer alternatives.\n +\n -+ - git-restore(1) and git-switch(1) have been introduced as a replacement for\n -+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n -+ of switching to git-restore(1) and git-switch(1) is contended, all three\n -+ commands will stay.\n -+\n -+ This decision may get revisited in case we ever figure out that there are\n -+ almost no users of any of the commands anymore.\n -+\n -+ Cf. ,\n -+ ,\n -+ <112b6568912a6de6672bf5592c3a718e@manjaro.org>.\n ++* git-restore(1) and git-switch(1) have been introduced as a replacement for\n ++ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n ++ of switching to git-restore(1) and git-switch(1) is contended, all three\n ++ commands will stay.\n +++\n ++This decision may get revisited in case we ever figure out that there are\n ++almost no users of any of the commands anymore.\n +++\n ++Cf. ,\n ++,\n ++<112b6568912a6de6672bf5592c3a718e@manjaro.org>.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496070","messageId":"67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717402497.git.ps@pks.im","subject":"[PATCH v5 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-03T09:28:22Z","receivedAt":"2024-06-03T09:28:28Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that tracks such breaking changes, but also\ndeprecations which we are not willing to go through with, to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go,\n both in the case where we want to deprecate, but also in the case\n where we don't want to deprecate a specific feature.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 71 +++++++++++++++++++++++++++++++\n 1 file changed, 71 insertions(+)\n create mode 100644 Documentation/BreakingChanges.txt\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nnew file mode 100644\nindex 0000000000..ddce7cc301\n--- /dev/null\n+++ b/Documentation/BreakingChanges.txt\n@@ -0,0 +1,71 @@\n+= Upcoming breaking changes\n+\n+The Git project aims to ensure backwards compatibility to the best extent\n+possible. Minor releases will not break backwards compatibility unless there is\n+a very strong reason to do so, like for example a security vulnerability.\n+\n+Regardless of that, due to the age of the Git project, it is only natural to\n+accumulate a backlog of backwards-incompatible changes that will eventually be\n+required to keep the project aligned with a changing world. These changes fall\n+into several categories:\n+\n+* Changes to long established defaults.\n+* Concepts that have been replaced with a superior design.\n+* Concepts, commands, configuration or options that have been lacking in major\n+ ways and that cannot be fixed and which will thus be removed without any\n+ replacement.\n+\n+Explicitly not included in this list are fixes to minor bugs that may cause a\n+change in user-visible behavior.\n+\n+The Git project irregularly releases breaking versions that deliberately break\n+backwards compatibility with older versions. This is done to ensure that Git\n+remains relevant, safe and maintainable going forward. The release cadence of\n+breaking versions is typically measured in multiple years. The last breaking\n+releases were:\n+\n+* Git 2.0, released in May 2014.\n+\n+The intent of this document is to track upcoming deprecations for the next\n+major Git release. Furthermore, this document also tracks what will _not_ be\n+deprecated. This is done such that the outcome of discussions documente both\n+when the discussion favors deprecation, but also when it rejects a deprecation.\n+\n+Items should have a self-sufficient explanation why we want or do not want to\n+make the described change. If there are alternatives to the changed feature,\n+those alternatives should be pointed out to our users.\n+\n+All items should be accompanied by references to relevant mailing list threads\n+where the deprecation was discussed. These references use message-IDs, which\n+can visited via\n+\n+ https://lore.kernel.org/git/$message_id/\n+\n+to see the message and its surrounding discussion. Such a reference is there to\n+make it easier for you to find how the project reached concensus on the\n+described item back then.\n+\n+This is a living document as the environment surrounding the project changes\n+over time. An earlier decision to deprecate or change something may need to be\n+revisited from time to time. So do not take items on this list to mean \"it is\n+settled, do not waste our time bringing it up again\".\n+\n+== Git 3.0\n+\n+The following subsections document upcoming breaking changes for Git 3.0. There\n+is no planned release date for this breaking version yet.\n+\n+Proposed changes and removals only include items which are \"ready\" to be done.\n+In other words, this is not supposed to be a wishlist of features that should\n+be changed to or replaced in case the alternative was implemented already.\n+\n+=== Changes\n+\n+=== Removals\n+\n+== Superseded features that will not be deprecated\n+\n+Some features have gained newer replacements that aim to improve the design in\n+certain ways. The fact that there is a replacement does not automatically mean\n+that the old way of doing things will eventually be removed. This section tracks\n+those features with newer alternatives.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496071","messageId":"b36ffcbaa67dcdada630e2d582e75da623512743.1717402497.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717402497.git.ps@pks.im","subject":"[PATCH v5 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-03T09:28:27Z","receivedAt":"2024-06-03T09:28:32Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Starting with 8e42eb0e9a (doc: sha256 is no longer experimental,\n2023-07-31), the \"sha256\" object format is no longer considered to be\nexperimental. Furthermore, the SHA-1 hash function is actively\nrecommended against by for example NIST and FIPS 140-2, and attacks\nagainst it are becoming more practical both due to new weaknesses\n(SHAppening, SHAttered, Shambles) and due to the ever-increasing\ncomputing power. It is only a matter of time before it can be considered\nto be broken completely.\n\nLet's plan for this event by being active instead of waiting for it to\nhappend and announce that the default object format is going to change\nfrom \"sha1\" to \"sha256\" with Git 3.0.\n\nAll major Git implementations (libgit2, JGit, go-git) support the\n\"sha256\" object format and are thus prepared for this change. The most\nimportant missing piece in the puzzle is support in forges. But while\nGitLab recently gained experimental support for the \"sha256\" object\nformat though, to the best of my knowledge GitHub doesn't support it\nyet. Ideally, announcing this upcoming change will encourage forges to\nstart building that support.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++\n 1 file changed, 24 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex ddce7cc301..904857a636 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already.\n \n === Changes\n \n+* The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n+ recommended against in FIPS 140-2 and similar certifications. Furthermore,\n+ there are practical attacks on SHA-1 that weaken its cryptographic properties:\n++\n+ ** The SHAppening (2015). The first demonstration of a practical attack\n+ against SHA-1 with 2^57 operations.\n+ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n+ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix\n+ attacks with 2^68 operations.\n+ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n+ operations.\n++\n+While we have protections in place against known attacks, it is expected\n+that more attacks against SHA-1 will be found by future research. Paired\n+with the ever-growing capability of hardware, it is only a matter of time\n+before SHA-1 will be considered broken completely. We want to be prepared\n+and will thus change the default hash algorithm to \"sha256\" for newly\n+initialized repositories.\n++\n+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n+.\n+\n === Removals\n \n == Superseded features that will not be deprecated\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496072","messageId":"4142e472ac54f5008b0566fdb967f86677171491.1717402497.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717402497.git.ps@pks.im","subject":"[PATCH v5 3/4] BreakingChanges: document removal of grafting","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-03T09:28:32Z","receivedAt":"2024-06-03T09:28:37Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The grafting mechanism for objects has been deprecated in e650d0643b\n(docs: mark info/grafts as outdated, 2014-03-05), which is more than a\ndecade ago. The mechanism can lead to hard-to-debug issues and has a\nsuperior replacement with replace refs.\n\nFollow through with the deprecation and mark grafts for removal in Git\n3.0.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 904857a636..b5088dcce2 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n \n === Removals\n \n+* Support for grafting commits has long been superseded by git-replace(1).\n+ Grafts are inferior to replacement refs as the mechanism can lead to\n+ hard-to-diagnose problems when transferring objects between repositories.\n+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n+ 2014-03-05) and will be removed.\n++\n+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n+\n == Superseded features that will not be deprecated\n \n Some features have gained newer replacements that aim to improve the design in\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496073","messageId":"9ff94b6f320d76e6b7c767e855038f33b69f4155.1717402497.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717402497.git.ps@pks.im","subject":"[PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-03T09:28:37Z","receivedAt":"2024-06-03T09:28:42Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The git-checkout(1) command is seen by many as hard to understand\nbecause it connects two somewhat unrelated features: switching between\nbranches and restoring worktree files from arbitrary revisions. In 2019,\nwe thus implemented two new commands git-switch(1) and git-restore(1) to\nsplit out these separate concerns into standalone functions.\n\nThis \"replacement\" of git-checkout(1) has repeatedly triggered concerns\nfor our userbase that git-checkout(1) will eventually go away. This is\nnot the case though: the use of that command is still widespread, and it\nis not expected that this will change anytime soon.\n\nDocument that all three commands will remain for the foreseeable future.\nThis decision may be revisited in case we ever figure out that most\neveryone has given up on any of the commands.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex b5088dcce2..3c38676f49 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -101,3 +101,15 @@ Some features have gained newer replacements that aim to improve the design in\n certain ways. The fact that there is a replacement does not automatically mean\n that the old way of doing things will eventually be removed. This section tracks\n those features with newer alternatives.\n+\n+* git-restore(1) and git-switch(1) have been introduced as a replacement for\n+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n+ of switching to git-restore(1) and git-switch(1) is contended, all three\n+ commands will stay.\n++\n+This decision may get revisited in case we ever figure out that there are\n+almost no users of any of the commands anymore.\n++\n+Cf. ,\n+,\n+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496088","messageId":"Zl2Np9qNcA6Z1q5U@framework","threadId":"61428","inReplyTo":"xmqqr0dhgc1e.fsf@gitster.g","subject":"Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-03T09:32:23Z","receivedAt":"2024-06-03T09:32:28Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, May 31, 2024 at 09:51:25AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n[snip]\n> > +Regardless of that, due to the age of the Git project, it is only natural to\n> > +accumulate a backlog of backwards-incompatible changes that will eventually be\n> > +required to keep the project aligned with a changing world. These changes fall\n> > +into several categories:\n> > +\n> > + - Changes to long established defaults.\n> > +\n> > + - Concepts that have been replaced with a superior design.\n> > +\n> > + - Concepts, commands, configuration or options that have been lacking in major\n> > + ways and that cannot be fixed.\n> \n> The first two are easy to imagine. If we change the default, people\n> may have to retrain their fingers or rewrite their scripts. If\n> \"log\" that came later is so good that even those who were using\n> \"whatchanged\" have long switched to it, there will come time when\n> nobody even notices a removal of \"whatchanged\".\n> \n> But the third one is puzzling. If something falls into the \"cannot\n> be fixed\" category, is it still one of \"These changes\" that \"will\n> eventually be required to [be made]\"?\n\nWell, for a wider definition of \"change\", yes. In this case the change\nwould be that the broken concept will be ripped out of Git without any\nreplacement.\n\nI'll clarify this a bit further.\n\n> > +The Git project will thus irregularly release major versions that deliberately\n> > +break backwards compatibility with older versions. This is done to ensure that\n> > +Git remains relevant, safe and maintainable going forward. The release cadence\n> > +of major versions is typically measured in multiple years.\n> \n> Releases vX.Y.Z (0 < Z) are \"maintenance releases\", and I have been\n> calling vX.Y.0 \"feature releases\" instead of calling them \"major\n> versions\", so the above use of the phrase \"major version\" can fit\n> in, but a more descriptive name, e.g., \"breaking versions\", might\n> convey the intention better, perhaps?\n\nI was trying to stick to the names that semantic versioning uses here,\nbut I'm happy to adapt this accordingly.\n\n> It may be more assuring to cite the last time such a breaking\n> version happened. Was \"Git 2.0\" a breaking version? If so, when\n> did it happen? Were there other breaking versions in the past?\n\nI would definitely call Git 2.0 a breaking release as the changes to\ngit-push(1)'s defaults were quite significant.\n\nOther than that I think lines are a bit blurry. We do minor breaking\nchanges sometimes in case certain behaviour is deemed to be buggy, and\nfixing such buggy behaviour may at times result in user visible changes\nin behaviour. I wouldn't call that a breaking release though, because we\ncertainly want to retain the ability to fix such bugs without bumping\nthe major version every single time. Going down that path just means\nthat the whole versioning schema becomes meaningless, like it has become\nfor so many other projects nowadays.\n\nI'll also include a sentence along this line.\n\n> > +The intent of this document is to track upcoming deprecations for the next\n> > +major Git release. Furthermore, this document also tracks what will _not_ be\n> > +deprecated. This is done such that the outcome of discussions documente both\n> > +when the discussion favors deprecation, but also when it rejects a deprecation.\n> \n> We seem to focus on removals and changes; will there be a case where\n> an upcoming addition is equally disrupting as removing an established\n> thing? If we wanted to avoid focusing on deprecation/removals too\n> narrowly, we could tweak the wording below, with \"deprecate a given\n> feature\" -> \"make the described change\", etc.\n\nHard to predict, I guess. Let's just rephrase it to be a bit more\ngeneric.\n\n[snip]\n> > +### Changes\n> > +\n> > +### Removals\n> > +\n> > +## Superseded features that will not be deprecated\n> > +\n> > +Some features have gained newer replacements that aim to improve the design in\n> > +certain ways. The fact that there is a replacement does not automatically mean\n> > +that the old way of doing things will eventually be removed. This section tracks\n> > +those superseded features.\n> \n> As the title says \"superseded\", to help non native speakers like me,\n> let's use a different and easier phrase with the same meaning in the\n> body text. \"... tracks those features with newer alternatives\",\n> perhaps?\n\nSure, makes sense.\n\nPatrick\n"},{"id":"496151","messageId":"c2129c09-dd71-4cc7-802c-bf662db93435@gmail.com","threadId":"61428","inReplyTo":"67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im","subject":"Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2024-06-03T14:08:30Z","receivedAt":"2024-06-03T14:08:33Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Patrick\n\nThanks for working on this, I've left a couple of small comments below \nbut I'm not sure they're worth a re-roll on their own. All of the \npatches look sensible to me.\n\nOn 03/06/2024 10:28, Patrick Steinhardt wrote:\n> +The intent of this document is to track upcoming deprecations for the next\n> +major Git release. Furthermore, this document also tracks what will _not_ be\n> +deprecated. This is done such that the outcome of discussions documente both\n> +when the discussion favors deprecation, but also when it rejects a deprecation.\n> +\n> +Items should have a self-sufficient explanation why we want or do not want to\n > +make the described change.\n\n\"self-sufficient explanation\" strikes me as a slightly add turn of \nphrase, maybe something like\n\n Items should have a clear summary of the reasons why we do or do not\n want to make the described change that can be easily understood\n without having to read the mailing list discussions.\n\n\n> If there are alternatives to the changed feature,\n> +those alternatives should be pointed out to our users.\n> +\n> +All items should be accompanied by references to relevant mailing list threads\n> +where the deprecation was discussed. These references use message-IDs, which\n> +can visited via\n> +\n> + https://lore.kernel.org/git/$message_id/\n> +\n> +to see the message and its surrounding discussion. Such a reference is there to\n> +make it easier for you to find how the project reached concensus on the\n> +described item back then.\n> +\n> +This is a living document as the environment surrounding the project changes\n> +over time. An earlier decision to deprecate or change something may need to be\n> +revisited from time to time. So do not take items on this list to mean \"it is\n> +settled, do not waste our time bringing it up again\".\n\nWe could possibly add \"If circumstances change\" to the start of the \nsecond sentence to discourage repeated discussions of the same issue \nwhen someone has a bee in their bonnet about a particular change but I \nthink we can probably handle that on the mailing list without any \nchanges here.\n\nBest Wishes\n\nPhillip\n"},{"id":"496158","messageId":"xmqq34pu6lwm.fsf@gitster.g","threadId":"61428","inReplyTo":"Zl2Np9qNcA6Z1q5U@framework","subject":"Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T16:17:29Z","receivedAt":"2024-06-03T16:17:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> I would definitely call Git 2.0 a breaking release as the changes to\n> git-push(1)'s defaults were quite significant.\n\nGit 1.6.0 was certainly a lot more controversial than the change in\nGit 2.0, as the end-users never expected Git will change even with\nample pre-warning. We originally had all the \"git-foo\" in $PATH\nsince 2005 when Git started, and we announced that we'll stop doing\nso in the release notes to Git 1.5.4 with instructions on how to\nadjust the scripts that use \"git-foo\" form. Even then end-users\n(back then they were a lot smaller population---we are talking about\nAug 2008) complained quite loudly.\n\n[Readings]\n\n* https://git.github.io/htmldocs/RelNotes/1.5.4.txt\n* https://git.github.io/htmldocs/RelNotes/1.6.0.txt\n* https://lore.kernel.org/git/7vprnzt7d5.fsf@gitster.siamese.dyndns.org/\n"},{"id":"496159","messageId":"xmqqv82q56zz.fsf@gitster.g","threadId":"61428","inReplyTo":"67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im","subject":"Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T16:24:48Z","receivedAt":"2024-06-03T16:24:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> +The intent of this document is to track upcoming deprecations for the next\n> +major Git release. Furthermore, this document also tracks what will _not_ be\n> +deprecated. This is done such that the outcome of discussions documente both\n> +when the discussion favors deprecation, but also when it rejects a deprecation.\n\n\"next major Git release\" -> \"future breaking release(s)\". I do not\nknow offhand if we want to plan for longer timespans that may cover\nmultiple breaking releases, hence (s) in parentheses.\n\n\"documente\" -> \"document\".\n\n> +This is a living document as the environment surrounding the project changes\n> +over time. An earlier decision to deprecate or change something may need to be\n> +revisited from time to time. So do not take items on this list to mean \"it is\n> +settled, do not waste our time bringing it up again\".\n\nBut you are expected to be aware of past discussion, and if you are\nnot bringing anything new to the table, you are wasting our time.\nNote that pointing out an old rationale no longer applies to today's\nworld still counts as a new datapoint in a renewed discussion.\n"},{"id":"496160","messageId":"xmqqfrtu56fo.fsf@gitster.g","threadId":"61428","inReplyTo":"b36ffcbaa67dcdada630e2d582e75da623512743.1717402497.git.ps@pks.im","subject":"Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T16:36:59Z","receivedAt":"2024-06-03T16:37:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Starting with 8e42eb0e9a (doc: sha256 is no longer experimental,\n> 2023-07-31), the \"sha256\" object format is no longer considered to be\n> experimental. Furthermore, the SHA-1 hash function is actively\n> recommended against by for example NIST and FIPS 140-2, and attacks\n> against it are becoming more practical both due to new weaknesses\n> (SHAppening, SHAttered, Shambles) and due to the ever-increasing\n> computing power. It is only a matter of time before it can be considered\n> to be broken completely.\n>\n> Let's plan for this event by being active instead of waiting for it to\n> happend and announce that the default object format is going to change\n> from \"sha1\" to \"sha256\" with Git 3.0.\n>\n> All major Git implementations (libgit2, JGit, go-git) support the\n> \"sha256\" object format and are thus prepared for this change. The most\n> important missing piece in the puzzle is support in forges. But while\n> GitLab recently gained experimental support for the \"sha256\" object\n> format though, to the best of my knowledge GitHub doesn't support it\n> yet. Ideally, announcing this upcoming change will encourage forges to\n> start building that support.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++\n> 1 file changed, 24 insertions(+)\n>\n> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n> index ddce7cc301..904857a636 100644\n> --- a/Documentation/BreakingChanges.txt\n> +++ b/Documentation/BreakingChanges.txt\n> @@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already.\n> \n> === Changes\n> \n> +* The default hash function for new repositories will be changed from \"sha1\"\n> + to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n> + recommended against in FIPS 140-2 and similar certifications. Furthermore,\n> + there are practical attacks on SHA-1 that weaken its cryptographic properties:\n> ++\n> + ** The SHAppening (2015). The first demonstration of a practical attack\n> + against SHA-1 with 2^57 operations.\n> + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n> + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix\n> + attacks with 2^68 operations.\n> + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n> + operations.\n> ++\n> +While we have protections in place against known attacks, it is expected\n> +that more attacks against SHA-1 will be found by future research. Paired\n> +with the ever-growing capability of hardware, it is only a matter of time\n> +before SHA-1 will be considered broken completely. We want to be prepared\n> +and will thus change the default hash algorithm to \"sha256\" for newly\n> +initialized repositories.\n> ++\n> +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n> +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n> +.\n\nA few things we should probably list are:\n\n - Even if you can locally use SHA-256 in your project and\n push/fetch the history around, public forges may not be ready.\n\n - The strategy to migrate existing SHA-1 project to SHA-256 without\n going through a flag day change has been designed but not\n implemented or deployed.\n\n - This is only about the change of the default; we currently have\n no plan to drop support for SHA-1 repositories.\n\nIMHO, we would want each and every item in this document to mention\nthe risk factors that may prevent us from going forward even if we\nwanted to, and the first item above is an example.\n\nThanks.\n"},{"id":"496161","messageId":"xmqq8qzm566y.fsf@gitster.g","threadId":"61428","inReplyTo":"4142e472ac54f5008b0566fdb967f86677171491.1717402497.git.ps@pks.im","subject":"Re: [PATCH v5 3/4] BreakingChanges: document removal of grafting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T16:42:13Z","receivedAt":"2024-06-03T16:42:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> The grafting mechanism for objects has been deprecated in e650d0643b\n> (docs: mark info/grafts as outdated, 2014-03-05), which is more than a\n> decade ago. The mechanism can lead to hard-to-debug issues and has a\n> superior replacement with replace refs.\n>\n> Follow through with the deprecation and mark grafts for removal in Git\n> 3.0.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/BreakingChanges.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n>\n> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n> index 904857a636..b5088dcce2 100644\n> --- a/Documentation/BreakingChanges.txt\n> +++ b/Documentation/BreakingChanges.txt\n> @@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n> \n> === Removals\n> \n> +* Support for grafting commits has long been superseded by git-replace(1).\n> + Grafts are inferior to replacement refs as the mechanism can lead to\n> + hard-to-diagnose problems when transferring objects between repositories.\n\nThe replace refs will be transferred, but the graft is a purely\nlocal mechanism and there is no way (other than by human\nintervention) to communicate the graft entries across repositories.\n\nThat is the primary thing we should list as the reason why the\nreplace mechanism is a better alternative over the graft mechanism.\n\n> + They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n> + 2014-03-05) and will be removed.\n> ++\n> +Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n> +\n> == Superseded features that will not be deprecated\n> \n> Some features have gained newer replacements that aim to improve the design in\n"},{"id":"496162","messageId":"xmqqo78i3r5a.fsf@gitster.g","threadId":"61428","inReplyTo":"9ff94b6f320d76e6b7c767e855038f33b69f4155.1717402497.git.ps@pks.im","subject":"Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T16:52:33Z","receivedAt":"2024-06-03T16:52:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> +\n> +* git-restore(1) and git-switch(1) have been introduced as a replacement for\n> + git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n> + of switching to git-restore(1) and git-switch(1) is contended, all three\n> + commands will stay.\n\n\"As a replacement\" is probably a bit different from the truth [*],\nbut I suspect that the reason why they were introduced no longer has\nmuch relevance. How about\n\n The features git-checkout(1) offers are covered by the pair of\n commands git-restore(1) and git-switch(1). Because the use of\n git-checkout(1) is still widespread, and it is not expected that\n this will change anytime soon.\n\nor something (borrowing from your proposed log message)?\n\n[Footnote]\n\n * If we were to mention the history behind the introduction, we'd\n end up saying: as an experiment, we introduced the pair of\n commands that do different half of the original command to see if\n they can replace the original.\n\n The decision to keep the original would lead to implication that\n this was a failed experiment, which makes people (unnecessarily)\n wonder if the failed experiment should be removed. I am trying\n to avoid such unnecessary implication here.\n"},{"id":"496199","messageId":"Zl67SnAQbtnxzAxS@framework","threadId":"61428","inReplyTo":"xmqqv82q56zz.fsf@gitster.g","subject":"Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T06:59:22Z","receivedAt":"2024-06-04T06:59:29Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Jun 03, 2024 at 09:24:48AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> > +This is a living document as the environment surrounding the project changes\n> > +over time. An earlier decision to deprecate or change something may need to be\n> > +revisited from time to time. So do not take items on this list to mean \"it is\n> > +settled, do not waste our time bringing it up again\".\n> \n> But you are expected to be aware of past discussion, and if you are\n> not bringing anything new to the table, you are wasting our time.\n> Note that pointing out an old rationale no longer applies to today's\n> world still counts as a new datapoint in a renewed discussion.\n\nYeah. I like Phillip's proposal here, which adds \"If circumstances\nchange\" to the second sentence to clarify that we do not want to rehash\nthe same arguments.\n\nPatrick\n"},{"id":"496200","messageId":"Zl682Dk6RcFOC2rA@framework","threadId":"61428","inReplyTo":"xmqqfrtu56fo.fsf@gitster.g","subject":"Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T07:06:00Z","receivedAt":"2024-06-04T07:06:06Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Jun 03, 2024 at 09:36:59AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > Starting with 8e42eb0e9a (doc: sha256 is no longer experimental,\n> > 2023-07-31), the \"sha256\" object format is no longer considered to be\n> > experimental. Furthermore, the SHA-1 hash function is actively\n> > recommended against by for example NIST and FIPS 140-2, and attacks\n> > against it are becoming more practical both due to new weaknesses\n> > (SHAppening, SHAttered, Shambles) and due to the ever-increasing\n> > computing power. It is only a matter of time before it can be considered\n> > to be broken completely.\n> >\n> > Let's plan for this event by being active instead of waiting for it to\n> > happend and announce that the default object format is going to change\n> > from \"sha1\" to \"sha256\" with Git 3.0.\n> >\n> > All major Git implementations (libgit2, JGit, go-git) support the\n> > \"sha256\" object format and are thus prepared for this change. The most\n> > important missing piece in the puzzle is support in forges. But while\n> > GitLab recently gained experimental support for the \"sha256\" object\n> > format though, to the best of my knowledge GitHub doesn't support it\n> > yet. Ideally, announcing this upcoming change will encourage forges to\n> > start building that support.\n> >\n> > Signed-off-by: Patrick Steinhardt \n> > ---\n> > Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++\n> > 1 file changed, 24 insertions(+)\n> >\n> > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n> > index ddce7cc301..904857a636 100644\n> > --- a/Documentation/BreakingChanges.txt\n> > +++ b/Documentation/BreakingChanges.txt\n> > @@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already.\n> > \n> > === Changes\n> > \n> > +* The default hash function for new repositories will be changed from \"sha1\"\n> > + to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n> > + recommended against in FIPS 140-2 and similar certifications. Furthermore,\n> > + there are practical attacks on SHA-1 that weaken its cryptographic properties:\n> > ++\n> > + ** The SHAppening (2015). The first demonstration of a practical attack\n> > + against SHA-1 with 2^57 operations.\n> > + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n> > + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix\n> > + attacks with 2^68 operations.\n> > + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n> > + operations.\n> > ++\n> > +While we have protections in place against known attacks, it is expected\n> > +that more attacks against SHA-1 will be found by future research. Paired\n> > +with the ever-growing capability of hardware, it is only a matter of time\n> > +before SHA-1 will be considered broken completely. We want to be prepared\n> > +and will thus change the default hash algorithm to \"sha256\" for newly\n> > +initialized repositories.\n> > ++\n> > +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n> > +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n> > +.\n> \n> A few things we should probably list are:\n> \n> - Even if you can locally use SHA-256 in your project and\n> push/fetch the history around, public forges may not be ready.\n> \n> - The strategy to migrate existing SHA-1 project to SHA-256 without\n> going through a flag day change has been designed but not\n> implemented or deployed.\n> \n> - This is only about the change of the default; we currently have\n> no plan to drop support for SHA-1 repositories.\n> \n> IMHO, we would want each and every item in this document to mention\n> the risk factors that may prevent us from going forward even if we\n> wanted to, and the first item above is an example.\n> \n> Thanks.\n\nI agree that explicitly mentioning (1) and (3) is sensible. Is the\nsecond one important though given that this is about the default when\ncreating _new_ repositories? I don't think interop code is a requirement\nto make \"sha256\" the default, is it?\n\nPatrick\n"},{"id":"496201","messageId":"Zl6-IXA_REOy05wh@framework","threadId":"61428","inReplyTo":"xmqqo78i3r5a.fsf@gitster.g","subject":"Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T07:11:29Z","receivedAt":"2024-06-04T07:11:36Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Jun 03, 2024 at 09:52:33AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > +\n> > +* git-restore(1) and git-switch(1) have been introduced as a replacement for\n> > + git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n> > + of switching to git-restore(1) and git-switch(1) is contended, all three\n> > + commands will stay.\n> \n> \"As a replacement\" is probably a bit different from the truth [*],\n> but I suspect that the reason why they were introduced no longer has\n> much relevance. How about\n> \n> The features git-checkout(1) offers are covered by the pair of\n> commands git-restore(1) and git-switch(1). Because the use of\n> git-checkout(1) is still widespread, and it is not expected that\n> this will change anytime soon.\n> \n> or something (borrowing from your proposed log message)?\n\nFair enough, let's add it like this. Thanks!\n\nPatrick\n"},{"id":"496204","messageId":"Zl7FdB2juCFkHuba@framework","threadId":"61428","inReplyTo":"xmqq34pu6lwm.fsf@gitster.g","subject":"Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T07:42:44Z","receivedAt":"2024-06-04T07:42:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Jun 03, 2024 at 09:17:29AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > I would definitely call Git 2.0 a breaking release as the changes to\n> > git-push(1)'s defaults were quite significant.\n> \n> Git 1.6.0 was certainly a lot more controversial than the change in\n> Git 2.0, as the end-users never expected Git will change even with\n> ample pre-warning. We originally had all the \"git-foo\" in $PATH\n> since 2005 when Git started, and we announced that we'll stop doing\n> so in the release notes to Git 1.5.4 with instructions on how to\n> adjust the scripts that use \"git-foo\" form. Even then end-users\n> (back then they were a lot smaller population---we are talking about\n> Aug 2008) complained quite loudly.\n> \n> [Readings]\n> \n> * https://git.github.io/htmldocs/RelNotes/1.5.4.txt\n> * https://git.github.io/htmldocs/RelNotes/1.6.0.txt\n> * https://lore.kernel.org/git/7vprnzt7d5.fsf@gitster.siamese.dyndns.org/\n\nI had it in my mind that Git 1.6 was controversial, but I didn't quite\nknow why exactly as I haven't been around at that point in time yet. I\ndid read through its release notes to double check, but it seems like I\nmissed the important part even though it was up front.\n\nThanks for the history lesson, will add!\n\nPatrick\n"},{"id":"496245","messageId":"cover.1717504292.git.ps@pks.im","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"[PATCH v6 0/4] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T12:32:32Z","receivedAt":"2024-06-04T12:32:38Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nanother day, another version of this patch series that aims to give a\nframework for documenting upcoming breaking changes in Git.\n\nChanges compared to v5:\n\n - Note that Git 1.6 was a breaking release, despite the fact that its\n major version wasn't bumped.\n\n - Several smallish rewordings.\n\n - Note that items on the lists should only be discussed anew when\n circumstances have changed.\n\n - Add some conditions to the move to \"sha256\". Also, note that we do\n not plan to deprecate \"sha1\".\n\n - Note that replacement refs are also superior over grafts because\n they can be carried across repos.\n\nThanks!\n\nPatrick\n\nPatrick Steinhardt (4):\n docs: introduce document to announce breaking changes\n BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n BreakingChanges: document removal of grafting\n BreakingChanges: document that we do not plan to deprecate\n git-checkout\n\n Documentation/BreakingChanges.txt | 128 ++++++++++++++++++++++++++++++\n 1 file changed, 128 insertions(+)\n create mode 100644 Documentation/BreakingChanges.txt\n\nRange-diff against v5:\n1: 67cb4de5cb ! 1: a260bbf281 docs: introduce document to announce breaking changes\n @@ Documentation/BreakingChanges.txt (new)\n +breaking versions is typically measured in multiple years. The last breaking\n +releases were:\n +\n ++* Git 1.6, released in August 2008. In retrospect, this release should likely\n ++ have bumped the major version.\n +* Git 2.0, released in May 2014.\n +\n -+The intent of this document is to track upcoming deprecations for the next\n -+major Git release. Furthermore, this document also tracks what will _not_ be\n -+deprecated. This is done such that the outcome of discussions documente both\n ++The intent of this document is to track upcoming deprecations for future\n ++breaking releases. Furthermore, this document also tracks what will _not_ be\n ++deprecated. This is done such that the outcome of discussions document both\n +when the discussion favors deprecation, but also when it rejects a deprecation.\n +\n -+Items should have a self-sufficient explanation why we want or do not want to\n -+make the described change. If there are alternatives to the changed feature,\n ++Items should have a clear summary of the reasons why we do or do not want to\n ++make the described change that can be easily understood without having to read\n ++the mailing list discussions. If there are alternatives to the changed feature,\n +those alternatives should be pointed out to our users.\n +\n +All items should be accompanied by references to relevant mailing list threads\n @@ Documentation/BreakingChanges.txt (new)\n +described item back then.\n +\n +This is a living document as the environment surrounding the project changes\n -+over time. An earlier decision to deprecate or change something may need to be\n -+revisited from time to time. So do not take items on this list to mean \"it is\n -+settled, do not waste our time bringing it up again\".\n ++over time. If circumstances change, an earlier decision to deprecate or change\n ++something may need to be revisited from time to time. So do not take items on\n ++this list to mean \"it is settled, do not waste our time bringing it up again\".\n +\n +== Git 3.0\n +\n2: b36ffcbaa6 ! 2: f7c6a66f71 BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n @@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alterna\n +and will thus change the default hash algorithm to \"sha256\" for newly\n +initialized repositories.\n ++\n ++An important requirement for this change is that the ecosystem is ready to\n ++support the \"sha256\" object format. This includes popular Git libraries,\n ++applications and forges.\n +++\n ++There is no plan to deprecate the \"sha1\" object format at this point in time.\n +++\n +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n +.\n3: 4142e472ac ! 3: b25b91a5e7 BreakingChanges: document removal of grafting\n @@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom\n === Removals\n \n +* Support for grafting commits has long been superseded by git-replace(1).\n -+ Grafts are inferior to replacement refs as the mechanism can lead to\n -+ hard-to-diagnose problems when transferring objects between repositories.\n -+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n -+ 2014-03-05) and will be removed.\n ++ Grafts are inferior to replacement refs:\n +++\n ++ ** Grafts are a local-only mechanism and cannot be shared across reositories.\n ++ ** Grafts can lead to hard-to-diagnose problems when transferring objects\n ++ between repositories.\n +++\n ++The grafting mechanism has been marked as outdated since e650d0643b (docs: mark\n ++info/grafts as outdated, 2014-03-05) and will be removed.\n ++\n +Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n +\n4: 9ff94b6f32 ! 4: 4fafccc3b9 BreakingChanges: document that we do not plan to deprecate git-checkout\n @@ Documentation/BreakingChanges.txt: Some features have gained newer replacements\n that the old way of doing things will eventually be removed. This section tracks\n those features with newer alternatives.\n +\n -+* git-restore(1) and git-switch(1) have been introduced as a replacement for\n -+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n -+ of switching to git-restore(1) and git-switch(1) is contended, all three\n -+ commands will stay.\n ++* The features git-checkout(1) offers are covered by the pair of commands\n ++ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still\n ++ widespread, and it is not expected that this will change anytime soon, all\n ++ three commands will stay.\n ++\n +This decision may get revisited in case we ever figure out that there are\n +almost no users of any of the commands anymore.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496246","messageId":"a260bbf281d2975562a042a71ca0dd7f88f03da4.1717504292.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717504292.git.ps@pks.im","subject":"[PATCH v6 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T12:32:36Z","receivedAt":"2024-06-04T12:32:41Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that tracks such breaking changes, but also\ndeprecations which we are not willing to go through with, to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go,\n both in the case where we want to deprecate, but also in the case\n where we don't want to deprecate a specific feature.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 74 +++++++++++++++++++++++++++++++\n 1 file changed, 74 insertions(+)\n create mode 100644 Documentation/BreakingChanges.txt\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nnew file mode 100644\nindex 0000000000..36327b13b8\n--- /dev/null\n+++ b/Documentation/BreakingChanges.txt\n@@ -0,0 +1,74 @@\n+= Upcoming breaking changes\n+\n+The Git project aims to ensure backwards compatibility to the best extent\n+possible. Minor releases will not break backwards compatibility unless there is\n+a very strong reason to do so, like for example a security vulnerability.\n+\n+Regardless of that, due to the age of the Git project, it is only natural to\n+accumulate a backlog of backwards-incompatible changes that will eventually be\n+required to keep the project aligned with a changing world. These changes fall\n+into several categories:\n+\n+* Changes to long established defaults.\n+* Concepts that have been replaced with a superior design.\n+* Concepts, commands, configuration or options that have been lacking in major\n+ ways and that cannot be fixed and which will thus be removed without any\n+ replacement.\n+\n+Explicitly not included in this list are fixes to minor bugs that may cause a\n+change in user-visible behavior.\n+\n+The Git project irregularly releases breaking versions that deliberately break\n+backwards compatibility with older versions. This is done to ensure that Git\n+remains relevant, safe and maintainable going forward. The release cadence of\n+breaking versions is typically measured in multiple years. The last breaking\n+releases were:\n+\n+* Git 1.6, released in August 2008. In retrospect, this release should likely\n+ have bumped the major version.\n+* Git 2.0, released in May 2014.\n+\n+The intent of this document is to track upcoming deprecations for future\n+breaking releases. Furthermore, this document also tracks what will _not_ be\n+deprecated. This is done such that the outcome of discussions document both\n+when the discussion favors deprecation, but also when it rejects a deprecation.\n+\n+Items should have a clear summary of the reasons why we do or do not want to\n+make the described change that can be easily understood without having to read\n+the mailing list discussions. If there are alternatives to the changed feature,\n+those alternatives should be pointed out to our users.\n+\n+All items should be accompanied by references to relevant mailing list threads\n+where the deprecation was discussed. These references use message-IDs, which\n+can visited via\n+\n+ https://lore.kernel.org/git/$message_id/\n+\n+to see the message and its surrounding discussion. Such a reference is there to\n+make it easier for you to find how the project reached concensus on the\n+described item back then.\n+\n+This is a living document as the environment surrounding the project changes\n+over time. If circumstances change, an earlier decision to deprecate or change\n+something may need to be revisited from time to time. So do not take items on\n+this list to mean \"it is settled, do not waste our time bringing it up again\".\n+\n+== Git 3.0\n+\n+The following subsections document upcoming breaking changes for Git 3.0. There\n+is no planned release date for this breaking version yet.\n+\n+Proposed changes and removals only include items which are \"ready\" to be done.\n+In other words, this is not supposed to be a wishlist of features that should\n+be changed to or replaced in case the alternative was implemented already.\n+\n+=== Changes\n+\n+=== Removals\n+\n+== Superseded features that will not be deprecated\n+\n+Some features have gained newer replacements that aim to improve the design in\n+certain ways. The fact that there is a replacement does not automatically mean\n+that the old way of doing things will eventually be removed. This section tracks\n+those features with newer alternatives.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496247","messageId":"f7c6a66f7180a4d469fa269b1be3991b98f36c66.1717504292.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717504292.git.ps@pks.im","subject":"[PATCH v6 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T12:32:41Z","receivedAt":"2024-06-04T12:32:46Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Starting with 8e42eb0e9a (doc: sha256 is no longer experimental,\n2023-07-31), the \"sha256\" object format is no longer considered to be\nexperimental. Furthermore, the SHA-1 hash function is actively\nrecommended against by for example NIST and FIPS 140-2, and attacks\nagainst it are becoming more practical both due to new weaknesses\n(SHAppening, SHAttered, Shambles) and due to the ever-increasing\ncomputing power. It is only a matter of time before it can be considered\nto be broken completely.\n\nLet's plan for this event by being active instead of waiting for it to\nhappend and announce that the default object format is going to change\nfrom \"sha1\" to \"sha256\" with Git 3.0.\n\nAll major Git implementations (libgit2, JGit, go-git) support the\n\"sha256\" object format and are thus prepared for this change. The most\nimportant missing piece in the puzzle is support in forges. But while\nGitLab recently gained experimental support for the \"sha256\" object\nformat though, to the best of my knowledge GitHub doesn't support it\nyet. Ideally, announcing this upcoming change will encourage forges to\nstart building that support.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++\n 1 file changed, 30 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 36327b13b8..5d7e80aebb 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -64,6 +64,36 @@ be changed to or replaced in case the alternative was implemented already.\n \n === Changes\n \n+* The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n+ recommended against in FIPS 140-2 and similar certifications. Furthermore,\n+ there are practical attacks on SHA-1 that weaken its cryptographic properties:\n++\n+ ** The SHAppening (2015). The first demonstration of a practical attack\n+ against SHA-1 with 2^57 operations.\n+ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n+ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix\n+ attacks with 2^68 operations.\n+ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n+ operations.\n++\n+While we have protections in place against known attacks, it is expected\n+that more attacks against SHA-1 will be found by future research. Paired\n+with the ever-growing capability of hardware, it is only a matter of time\n+before SHA-1 will be considered broken completely. We want to be prepared\n+and will thus change the default hash algorithm to \"sha256\" for newly\n+initialized repositories.\n++\n+An important requirement for this change is that the ecosystem is ready to\n+support the \"sha256\" object format. This includes popular Git libraries,\n+applications and forges.\n++\n+There is no plan to deprecate the \"sha1\" object format at this point in time.\n++\n+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n+.\n+\n === Removals\n \n == Superseded features that will not be deprecated\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496248","messageId":"b25b91a5e707f671785012c1b4a68c36241e537e.1717504292.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717504292.git.ps@pks.im","subject":"[PATCH v6 3/4] BreakingChanges: document removal of grafting","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T12:32:46Z","receivedAt":"2024-06-04T12:32:51Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The grafting mechanism for objects has been deprecated in e650d0643b\n(docs: mark info/grafts as outdated, 2014-03-05), which is more than a\ndecade ago. The mechanism can lead to hard-to-debug issues and has a\nsuperior replacement with replace refs.\n\nFollow through with the deprecation and mark grafts for removal in Git\n3.0.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 5d7e80aebb..9fb6d8c78a 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -96,6 +96,18 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n \n === Removals\n \n+* Support for grafting commits has long been superseded by git-replace(1).\n+ Grafts are inferior to replacement refs:\n++\n+ ** Grafts are a local-only mechanism and cannot be shared across reositories.\n+ ** Grafts can lead to hard-to-diagnose problems when transferring objects\n+ between repositories.\n++\n+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark\n+info/grafts as outdated, 2014-03-05) and will be removed.\n++\n+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n+\n == Superseded features that will not be deprecated\n \n Some features have gained newer replacements that aim to improve the design in\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496249","messageId":"4fafccc3b919d68c51f83b2cb0c04f8621c17426.1717504292.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1717504292.git.ps@pks.im","subject":"[PATCH v6 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T12:32:51Z","receivedAt":"2024-06-04T12:32:56Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The git-checkout(1) command is seen by many as hard to understand\nbecause it connects two somewhat unrelated features: switching between\nbranches and restoring worktree files from arbitrary revisions. In 2019,\nwe thus implemented two new commands git-switch(1) and git-restore(1) to\nsplit out these separate concerns into standalone functions.\n\nThis \"replacement\" of git-checkout(1) has repeatedly triggered concerns\nfor our userbase that git-checkout(1) will eventually go away. This is\nnot the case though: the use of that command is still widespread, and it\nis not expected that this will change anytime soon.\n\nDocument that all three commands will remain for the foreseeable future.\nThis decision may be revisited in case we ever figure out that most\neveryone has given up on any of the commands.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 9fb6d8c78a..0fd60a7776 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -114,3 +114,15 @@ Some features have gained newer replacements that aim to improve the design in\n certain ways. The fact that there is a replacement does not automatically mean\n that the old way of doing things will eventually be removed. This section tracks\n those features with newer alternatives.\n+\n+* The features git-checkout(1) offers are covered by the pair of commands\n+ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still\n+ widespread, and it is not expected that this will change anytime soon, all\n+ three commands will stay.\n++\n+This decision may get revisited in case we ever figure out that there are\n+almost no users of any of the commands anymore.\n++\n+Cf. ,\n+,\n+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.\n-- \n2.45.1.410.g58bac47f8e.dirty\n\n"},{"id":"496282","messageId":"f231d5ff-08e5-47b3-aadc-0f88566c2588@gmail.com","threadId":"61428","inReplyTo":"cover.1717504292.git.ps@pks.im","subject":"Re: [PATCH v6 0/4] docs: document upcoming breaking changes","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2024-06-04T14:23:09Z","receivedAt":"2024-06-04T14:23:12Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Patrick\n\nOn 04/06/2024 13:32, Patrick Steinhardt wrote:\n> Hi,\n> \n> another day, another version of this patch series that aims to give a\n> framework for documenting upcoming breaking changes in Git.\n> \n> Changes compared to v5:\n> \n> - Note that Git 1.6 was a breaking release, despite the fact that its\n> major version wasn't bumped.\n> \n> - Several smallish rewordings.\n> \n> - Note that items on the lists should only be discussed anew when\n> circumstances have changed.\n> \n> - Add some conditions to the move to \"sha256\". Also, note that we do\n> not plan to deprecate \"sha1\".\n> \n> - Note that replacement refs are also superior over grafts because\n> they can be carried across repos.\n\nThis version looks good to me\n\nThanks for writing this document\n\nPhillip\n\n> Thanks!\n> \n> Patrick\n> \n> Patrick Steinhardt (4):\n> docs: introduce document to announce breaking changes\n> BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n> BreakingChanges: document removal of grafting\n> BreakingChanges: document that we do not plan to deprecate\n> git-checkout\n> \n> Documentation/BreakingChanges.txt | 128 ++++++++++++++++++++++++++++++\n> 1 file changed, 128 insertions(+)\n> create mode 100644 Documentation/BreakingChanges.txt\n> \n> Range-diff against v5:\n> 1: 67cb4de5cb ! 1: a260bbf281 docs: introduce document to announce breaking changes\n> @@ Documentation/BreakingChanges.txt (new)\n> +breaking versions is typically measured in multiple years. The last breaking\n> +releases were:\n> +\n> ++* Git 1.6, released in August 2008. In retrospect, this release should likely\n> ++ have bumped the major version.\n> +* Git 2.0, released in May 2014.\n> +\n> -+The intent of this document is to track upcoming deprecations for the next\n> -+major Git release. Furthermore, this document also tracks what will _not_ be\n> -+deprecated. This is done such that the outcome of discussions documente both\n> ++The intent of this document is to track upcoming deprecations for future\n> ++breaking releases. Furthermore, this document also tracks what will _not_ be\n> ++deprecated. This is done such that the outcome of discussions document both\n> +when the discussion favors deprecation, but also when it rejects a deprecation.\n> +\n> -+Items should have a self-sufficient explanation why we want or do not want to\n> -+make the described change. If there are alternatives to the changed feature,\n> ++Items should have a clear summary of the reasons why we do or do not want to\n> ++make the described change that can be easily understood without having to read\n> ++the mailing list discussions. If there are alternatives to the changed feature,\n> +those alternatives should be pointed out to our users.\n> +\n> +All items should be accompanied by references to relevant mailing list threads\n> @@ Documentation/BreakingChanges.txt (new)\n> +described item back then.\n> +\n> +This is a living document as the environment surrounding the project changes\n> -+over time. An earlier decision to deprecate or change something may need to be\n> -+revisited from time to time. So do not take items on this list to mean \"it is\n> -+settled, do not waste our time bringing it up again\".\n> ++over time. If circumstances change, an earlier decision to deprecate or change\n> ++something may need to be revisited from time to time. So do not take items on\n> ++this list to mean \"it is settled, do not waste our time bringing it up again\".\n> +\n> +== Git 3.0\n> +\n> 2: b36ffcbaa6 ! 2: f7c6a66f71 BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n> @@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alterna\n> +and will thus change the default hash algorithm to \"sha256\" for newly\n> +initialized repositories.\n> ++\n> ++An important requirement for this change is that the ecosystem is ready to\n> ++support the \"sha256\" object format. This includes popular Git libraries,\n> ++applications and forges.\n> +++\n> ++There is no plan to deprecate the \"sha1\" object format at this point in time.\n> +++\n> +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n> +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n> +.\n> 3: 4142e472ac ! 3: b25b91a5e7 BreakingChanges: document removal of grafting\n> @@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom\n> === Removals\n> \n> +* Support for grafting commits has long been superseded by git-replace(1).\n> -+ Grafts are inferior to replacement refs as the mechanism can lead to\n> -+ hard-to-diagnose problems when transferring objects between repositories.\n> -+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,\n> -+ 2014-03-05) and will be removed.\n> ++ Grafts are inferior to replacement refs:\n> +++\n> ++ ** Grafts are a local-only mechanism and cannot be shared across reositories.\n> ++ ** Grafts can lead to hard-to-diagnose problems when transferring objects\n> ++ between repositories.\n> +++\n> ++The grafting mechanism has been marked as outdated since e650d0643b (docs: mark\n> ++info/grafts as outdated, 2014-03-05) and will be removed.\n> ++\n> +Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n> +\n> 4: 9ff94b6f32 ! 4: 4fafccc3b9 BreakingChanges: document that we do not plan to deprecate git-checkout\n> @@ Documentation/BreakingChanges.txt: Some features have gained newer replacements\n> that the old way of doing things will eventually be removed. This section tracks\n> those features with newer alternatives.\n> +\n> -+* git-restore(1) and git-switch(1) have been introduced as a replacement for\n> -+ git-checkout(1). As git-checkout(1) is quite established, and as the benefit\n> -+ of switching to git-restore(1) and git-switch(1) is contended, all three\n> -+ commands will stay.\n> ++* The features git-checkout(1) offers are covered by the pair of commands\n> ++ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still\n> ++ widespread, and it is not expected that this will change anytime soon, all\n> ++ three commands will stay.\n> ++\n> +This decision may get revisited in case we ever figure out that there are\n> +almost no users of any of the commands anymore.\n"},{"id":"496291","messageId":"xmqqtti8wruz.fsf@gitster.g","threadId":"61428","inReplyTo":"Zl682Dk6RcFOC2rA@framework","subject":"Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T17:16:36Z","receivedAt":"2024-06-04T17:16:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> I agree that explicitly mentioning (1) and (3) is sensible. Is the\n> second one important though given that this is about the default when\n> creating _new_ repositories? I don't think interop code is a requirement\n> to make \"sha256\" the default, is it?\n\nLet's drop (2) from the list, as I do not think there ever was a\nconcensus on it, and also for the sake of brevity.\n\nThanks.\n"},{"id":"496298","messageId":"xmqqsexsvbaf.fsf@gitster.g","threadId":"61428","inReplyTo":"a260bbf281d2975562a042a71ca0dd7f88f03da4.1717504292.git.ps@pks.im","subject":"Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T17:59:52Z","receivedAt":"2024-06-04T17:59:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> +* Git 1.6, released in August 2008. In retrospect, this release should likely\n> + have bumped the major version.\n\nNo need to reroll just for this alone, but back then, a non-zero\nthird component did not mean they are maintenance releases (e.g.,\nv1.5.3.3 was the third maintenance update for the v1.5.3 series) and\nv1.6.0 _was_ a departure, a breaking change from the v1.5.x series.\n\nIt is more recent tradition that we only use three numbers. I'd\nstrike the whole \"In retrospect\" comment if I were writing this.\n\n> +to see the message and its surrounding discussion. Such a reference is there to\n> +make it easier for you to find how the project reached concensus on the\n\n\"concensus\" -> \"consensus\".\n\n"},{"id":"496299","messageId":"xmqqo78gvb9w.fsf@gitster.g","threadId":"61428","inReplyTo":"b25b91a5e707f671785012c1b4a68c36241e537e.1717504292.git.ps@pks.im","subject":"Re: [PATCH v6 3/4] BreakingChanges: document removal of grafting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T18:00:11Z","receivedAt":"2024-06-04T18:00:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> The grafting mechanism for objects has been deprecated in e650d0643b\n> (docs: mark info/grafts as outdated, 2014-03-05), which is more than a\n> decade ago. The mechanism can lead to hard-to-debug issues and has a\n> superior replacement with replace refs.\n>\n> Follow through with the deprecation and mark grafts for removal in Git\n> 3.0.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/BreakingChanges.txt | 12 ++++++++++++\n> 1 file changed, 12 insertions(+)\n>\n> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n> index 5d7e80aebb..9fb6d8c78a 100644\n> --- a/Documentation/BreakingChanges.txt\n> +++ b/Documentation/BreakingChanges.txt\n> @@ -96,6 +96,18 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n> \n> === Removals\n> \n> +* Support for grafting commits has long been superseded by git-replace(1).\n> + Grafts are inferior to replacement refs:\n> ++\n> + ** Grafts are a local-only mechanism and cannot be shared across reositories.\n\n\"reositories\" -> \"repositories\".\n\n> + ** Grafts can lead to hard-to-diagnose problems when transferring objects\n> + between repositories.\n> ++\n> +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark\n> +info/grafts as outdated, 2014-03-05) and will be removed.\n> ++\n> +Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n> +\n> == Superseded features that will not be deprecated\n> \n> Some features have gained newer replacements that aim to improve the design in\n"},{"id":"496300","messageId":"xmqqjzj4vb7y.fsf@gitster.g","threadId":"61428","inReplyTo":"f231d5ff-08e5-47b3-aadc-0f88566c2588@gmail.com","subject":"Re: [PATCH v6 0/4] docs: document upcoming breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T18:01:21Z","receivedAt":"2024-06-04T18:01:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n> Hi Patrick\n>\n> On 04/06/2024 13:32, Patrick Steinhardt wrote:\n>> Hi,\n>> another day, another version of this patch series that aims to give\n>> a\n>> framework for documenting upcoming breaking changes in Git.\n>> Changes compared to v5:\n>> - Note that Git 1.6 was a breaking release, despite the fact that\n>> its\n>> major version wasn't bumped.\n>> - Several smallish rewordings.\n>> - Note that items on the lists should only be discussed anew when\n>> circumstances have changed.\n>> - Add some conditions to the move to \"sha256\". Also, note that we\n>> do\n>> not plan to deprecate \"sha1\".\n>> - Note that replacement refs are also superior over grafts\n>> because\n>> they can be carried across repos.\n>\n> This version looks good to me\n>\n> Thanks for writing this document\n\nYup, aside from two typos and a misstatement I did not spot anything\nthat need correction. Will queue.\n\nThanks.\n"},{"id":"496331","messageId":"Zl_4IIqFmoPhx1Gc@tanuki","threadId":"61428","inReplyTo":"xmqqsexsvbaf.fsf@gitster.g","subject":"Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-05T05:31:12Z","receivedAt":"2024-06-05T05:31:18Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > +* Git 1.6, released in August 2008. In retrospect, this release should likely\n> > + have bumped the major version.\n> \n> No need to reroll just for this alone, but back then, a non-zero\n> third component did not mean they are maintenance releases (e.g.,\n> v1.5.3.3 was the third maintenance update for the v1.5.3 series) and\n> v1.6.0 _was_ a departure, a breaking change from the v1.5.x series.\n> \n> It is more recent tradition that we only use three numbers. I'd\n> strike the whole \"In retrospect\" comment if I were writing this.\n\nThe reason why I included it is that I didn't want to create the\nimpression that breaking releases may also happen when bumping the\nsecond version component. It did happen with v1.6.0, but in the future I\nthink we'd want to always bump the first component on such releases, do\nwe?\n\nPatrick\n"},{"id":"496332","messageId":"Zl_4dDkmj8sJegrp@tanuki","threadId":"61428","inReplyTo":"xmqqjzj4vb7y.fsf@gitster.g","subject":"Re: [PATCH v6 0/4] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-05T05:32:36Z","receivedAt":"2024-06-05T05:32:42Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Jun 04, 2024 at 11:01:21AM -0700, Junio C Hamano wrote:\n> Phillip Wood writes:\n> \n> > Hi Patrick\n> >\n> > On 04/06/2024 13:32, Patrick Steinhardt wrote:\n> >> Hi,\n> >> another day, another version of this patch series that aims to give\n> >> a\n> >> framework for documenting upcoming breaking changes in Git.\n> >> Changes compared to v5:\n> >> - Note that Git 1.6 was a breaking release, despite the fact that\n> >> its\n> >> major version wasn't bumped.\n> >> - Several smallish rewordings.\n> >> - Note that items on the lists should only be discussed anew when\n> >> circumstances have changed.\n> >> - Add some conditions to the move to \"sha256\". Also, note that we\n> >> do\n> >> not plan to deprecate \"sha1\".\n> >> - Note that replacement refs are also superior over grafts\n> >> because\n> >> they can be carried across repos.\n> >\n> > This version looks good to me\n> >\n> > Thanks for writing this document\n> \n> Yup, aside from two typos and a misstatement I did not spot anything\n> that need correction. Will queue.\n> \n> Thanks.\n\nThanks to both of you!\n\nPatrick\n"},{"id":"496373","messageId":"xmqqjzj3wf4m.fsf@gitster.g","threadId":"61428","inReplyTo":"Zl_4IIqFmoPhx1Gc@tanuki","subject":"Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-05T16:03:53Z","receivedAt":"2024-06-05T16:03:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote:\n>> Patrick Steinhardt writes:\n>> \n>> > +* Git 1.6, released in August 2008. In retrospect, this release should likely\n>> > + have bumped the major version.\n>> \n>> No need to reroll just for this alone, but back then, a non-zero\n>> third component did not mean they are maintenance releases (e.g.,\n>> v1.5.3.3 was the third maintenance update for the v1.5.3 series) and\n>> v1.6.0 _was_ a departure, a breaking change from the v1.5.x series.\n>> \n>> It is more recent tradition that we only use three numbers. I'd\n>> strike the whole \"In retrospect\" comment if I were writing this.\n>\n> The reason why I included it is that I didn't want to create the\n> impression that breaking releases may also happen when bumping the\n> second version component. It did happen with v1.6.0, but in the future I\n> think we'd want to always bump the first component on such releases, do\n> we?\n\nBut \"in retrospect we should have called it 2.0\" is patently false;\nswitching from 3-tuple version numbers to 2-tuple version numbers\nhas nothing to do with introducing breaking changes.\n\nIt needs to be rewritten in such a way that the readers would\nunderstand the following:\n\n\tGit 1.6.0, released in August 2008.\n\n\tThese days, we use two-tuple numbers for feature releases\n\t(e.g. Git 2.45 and Git 2.45.0 with 0 as the third number are\n\tthe same things) and maintenance releases have non-zero\n\tthird number, so instead of going from Git 2.56 to Git 2.57,\n\twe would jump to Git 3.0 if we decide to make Git 2.56 the\n\tlast feature release of the Git 2.0 series.\n\n\tWith the versioning scheme used back then, going from Git\n\t1.5.6 to Git 1.5.7 would have been equivalent move to Git\n\t2.56 to Git 2.57, i.e. incremental and non-breaking feature\n\trelease progression. Deciding to go from Git 1.5.6 to Git\n\t1.6.0, instead of going to Git 1.5.7, was akin to moving to\n\tGit 3.0, signalling a breaking change, in today's versioning\n\tscheme. We were reserving the increment to the first digit\n\tfor even larger breaking changes until Git 2.0 happened.\n\nBetween Git 1.6.6 and Git 1.7.0, there were breaking changes. The\nsame is true for the transtions between Git 1.7.12 and Git 1.8.0,\nbetween Git 1.4.4 and Git 1.5.0, and so on. They weren't as huge\nand controversial as the jump to Git 1.6.0, though.\n"},{"id":"496388","messageId":"xmqqplsvs2et.fsf@gitster.g","threadId":"61428","inReplyTo":"xmqqjzj3wf4m.fsf@gitster.g","subject":"Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-05T17:52:10Z","receivedAt":"2024-06-05T17:52:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> But \"in retrospect we should have called it 2.0\" is patently false;\n> switching from 3-tuple version numbers to 2-tuple version numbers\n> has nothing to do with introducing breaking changes.\n\nI tried to make it concise, and came up with the following on top of\ntweaked [v6 1/4] on 'seen'.\n\n Documentation/BreakingChanges.txt | 13 ++++++++++---\n 1 file changed, 10 insertions(+), 3 deletions(-)\n\ndiff --git c/Documentation/BreakingChanges.txt w/Documentation/BreakingChanges.txt\nindex d977915e52..9c2c5f2328 100644\n--- c/Documentation/BreakingChanges.txt\n+++ w/Documentation/BreakingChanges.txt\n@@ -21,12 +21,19 @@ change in user-visible behavior.\n The Git project irregularly releases breaking versions that deliberately break\n backwards compatibility with older versions. This is done to ensure that Git\n remains relevant, safe and maintainable going forward. The release cadence of\n-breaking versions is typically measured in multiple years. The last breaking\n-releases were:\n+breaking versions is typically measured in multiple years. We had major\n+breaking releases like these in the past:\n \n-* Git 1.6, released in August 2008.\n+* Git 1.6.0, released in August 2008.\n * Git 2.0, released in May 2014.\n \n+We use . release numbers these days, starting from Git\n+2.0, for feature releases, our plan is to increment in the\n+release number when we make the next breaking release (before Git 2.0,\n+the release numbers were 1.. with the intention to increment\n+ for \"usual\" breaking releases, reserving the jump to Git 2.0 for\n+really large backward-compatibility breaking changes).\n+\n The intent of this document is to track upcoming deprecations for future\n breaking releases. Furthermore, this document also tracks what will _not_ be\n deprecated. This is done such that the outcome of discussions document both\n"},{"id":"496409","messageId":"ZmE8myG5c99UJeCA@tanuki","threadId":"61428","inReplyTo":"xmqqplsvs2et.fsf@gitster.g","subject":"Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-06T04:35:39Z","receivedAt":"2024-06-06T04:35:47Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Jun 05, 2024 at 10:52:10AM -0700, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n> > But \"in retrospect we should have called it 2.0\" is patently false;\n> > switching from 3-tuple version numbers to 2-tuple version numbers\n> > has nothing to do with introducing breaking changes.\n> \n> I tried to make it concise, and came up with the following on top of\n> tweaked [v6 1/4] on 'seen'.\n\nThat is a good addition indeed and nicely explains what was going on\nback then, and how we handle it today. Thanks!\n\nPatrick\n"},{"id":"497126","messageId":"cover.1718345026.git.ps@pks.im","threadId":"61428","inReplyTo":"fc1a9fa03de7330f79dc56b0f2712834cb236b5a.1715070296.git.ps@pks.im","subject":"[PATCH v7 0/4] docs: document upcoming breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-14T06:42:30Z","receivedAt":"2024-06-14T06:42:37Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Hi,\n\nthis is another and hopefully the last version of this patch series that\nstarts to document upcoming breaking changes in Git.\n\nChanges compared to v6:\n\n - Fix a typo in the third commit.\n\n - Document the version number schema and when we bump which part of\n our version, including historical 1.x days.\n\n - Drop the wrong remark that Git 1.6 should've been 2.0.\n\nThanks!\n\nPatrick\n\nPatrick Steinhardt (4):\n docs: introduce document to announce breaking changes\n BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n BreakingChanges: document removal of grafting\n BreakingChanges: document that we do not plan to deprecate\n git-checkout\n\n Documentation/BreakingChanges.txt | 135 ++++++++++++++++++++++++++++++\n 1 file changed, 135 insertions(+)\n create mode 100644 Documentation/BreakingChanges.txt\n\nRange-diff against v6:\n1: a260bbf281 ! 1: 6348f27b59 docs: introduce document to announce breaking changes\n @@ Documentation/BreakingChanges.txt (new)\n +The Git project irregularly releases breaking versions that deliberately break\n +backwards compatibility with older versions. This is done to ensure that Git\n +remains relevant, safe and maintainable going forward. The release cadence of\n -+breaking versions is typically measured in multiple years. The last breaking\n -+releases were:\n ++breaking versions is typically measured in multiple years. We had the following\n ++major breaking releases in the past:\n +\n -+* Git 1.6, released in August 2008. In retrospect, this release should likely\n -+ have bumped the major version.\n ++* Git 1.6.0, released in August 2008.\n +* Git 2.0, released in May 2014.\n +\n ++We use . release numbers these days, starting from Git 2.0. For\n ++future releases, our plan is to increment in the release number when we\n ++make the next breaking release. Before Git 2.0, the release numbers were\n ++1.. with the intention to increment for \"usual\" breaking\n ++releases, reserving the jump to Git 2.0 for really large backward-compatibility\n ++breaking changes.\n ++\n +The intent of this document is to track upcoming deprecations for future\n +breaking releases. Furthermore, this document also tracks what will _not_ be\n +deprecated. This is done such that the outcome of discussions document both\n2: f7c6a66f71 = 2: d0ec38a25a BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"\n3: b25b91a5e7 ! 3: deee0bbf66 BreakingChanges: document removal of grafting\n @@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom\n +* Support for grafting commits has long been superseded by git-replace(1).\n + Grafts are inferior to replacement refs:\n ++\n -+ ** Grafts are a local-only mechanism and cannot be shared across reositories.\n ++ ** Grafts are a local-only mechanism and cannot be shared across\n ++ repositories.\n + ** Grafts can lead to hard-to-diagnose problems when transferring objects\n + between repositories.\n ++\n4: 4fafccc3b9 = 4: 25b20bb0ca BreakingChanges: document that we do not plan to deprecate git-checkout\n-- \n2.45.2.457.g8d94cfb545.dirty\n\n"},{"id":"497127","messageId":"6348f27b591f306d79c69594ed3157e22ac4774c.1718345026.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1718345026.git.ps@pks.im","subject":"[PATCH v7 1/4] docs: introduce document to announce breaking changes","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-14T06:42:34Z","receivedAt":"2024-06-14T06:42:39Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Over time, Git has grown quite a lot. With this evolution, many ideas\nthat were sensible at the time they were introduced are not anymore and\nare thus considered to be deprecated. And while some deprecations may be\nnoted in manpages, most of them are actually deprecated in the \"hive\nmind\" of the Git community, only.\n\nIntroduce a new document that tracks such breaking changes, but also\ndeprecations which we are not willing to go through with, to address\nthis issue. This document serves multiple purposes:\n\n - It is a way to facilitate discussion around proposed deprecations.\n\n - It allows users to learn about deprecations and speak up in case\n they have good reasons why a certain feature should not be\n deprecated.\n\n - It states intent and documents where the Git project wants to go,\n both in the case where we want to deprecate, but also in the case\n where we don't want to deprecate a specific feature.\n\nThe document is _not_ intended to cast every single discussion into\nstone. It is supposed to be a living document that may change over time\nwhen there are good reasons for it to change.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 80 +++++++++++++++++++++++++++++++\n 1 file changed, 80 insertions(+)\n create mode 100644 Documentation/BreakingChanges.txt\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nnew file mode 100644\nindex 0000000000..cb7e30312f\n--- /dev/null\n+++ b/Documentation/BreakingChanges.txt\n@@ -0,0 +1,80 @@\n+= Upcoming breaking changes\n+\n+The Git project aims to ensure backwards compatibility to the best extent\n+possible. Minor releases will not break backwards compatibility unless there is\n+a very strong reason to do so, like for example a security vulnerability.\n+\n+Regardless of that, due to the age of the Git project, it is only natural to\n+accumulate a backlog of backwards-incompatible changes that will eventually be\n+required to keep the project aligned with a changing world. These changes fall\n+into several categories:\n+\n+* Changes to long established defaults.\n+* Concepts that have been replaced with a superior design.\n+* Concepts, commands, configuration or options that have been lacking in major\n+ ways and that cannot be fixed and which will thus be removed without any\n+ replacement.\n+\n+Explicitly not included in this list are fixes to minor bugs that may cause a\n+change in user-visible behavior.\n+\n+The Git project irregularly releases breaking versions that deliberately break\n+backwards compatibility with older versions. This is done to ensure that Git\n+remains relevant, safe and maintainable going forward. The release cadence of\n+breaking versions is typically measured in multiple years. We had the following\n+major breaking releases in the past:\n+\n+* Git 1.6.0, released in August 2008.\n+* Git 2.0, released in May 2014.\n+\n+We use . release numbers these days, starting from Git 2.0. For\n+future releases, our plan is to increment in the release number when we\n+make the next breaking release. Before Git 2.0, the release numbers were\n+1.. with the intention to increment for \"usual\" breaking\n+releases, reserving the jump to Git 2.0 for really large backward-compatibility\n+breaking changes.\n+\n+The intent of this document is to track upcoming deprecations for future\n+breaking releases. Furthermore, this document also tracks what will _not_ be\n+deprecated. This is done such that the outcome of discussions document both\n+when the discussion favors deprecation, but also when it rejects a deprecation.\n+\n+Items should have a clear summary of the reasons why we do or do not want to\n+make the described change that can be easily understood without having to read\n+the mailing list discussions. If there are alternatives to the changed feature,\n+those alternatives should be pointed out to our users.\n+\n+All items should be accompanied by references to relevant mailing list threads\n+where the deprecation was discussed. These references use message-IDs, which\n+can visited via\n+\n+ https://lore.kernel.org/git/$message_id/\n+\n+to see the message and its surrounding discussion. Such a reference is there to\n+make it easier for you to find how the project reached concensus on the\n+described item back then.\n+\n+This is a living document as the environment surrounding the project changes\n+over time. If circumstances change, an earlier decision to deprecate or change\n+something may need to be revisited from time to time. So do not take items on\n+this list to mean \"it is settled, do not waste our time bringing it up again\".\n+\n+== Git 3.0\n+\n+The following subsections document upcoming breaking changes for Git 3.0. There\n+is no planned release date for this breaking version yet.\n+\n+Proposed changes and removals only include items which are \"ready\" to be done.\n+In other words, this is not supposed to be a wishlist of features that should\n+be changed to or replaced in case the alternative was implemented already.\n+\n+=== Changes\n+\n+=== Removals\n+\n+== Superseded features that will not be deprecated\n+\n+Some features have gained newer replacements that aim to improve the design in\n+certain ways. The fact that there is a replacement does not automatically mean\n+that the old way of doing things will eventually be removed. This section tracks\n+those features with newer alternatives.\n-- \n2.45.2.457.g8d94cfb545.dirty\n\n"},{"id":"497128","messageId":"d0ec38a25ab4fbdcb8ffa726931ead3fc68662b4.1718345026.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1718345026.git.ps@pks.im","subject":"[PATCH v7 2/4] BreakingChanges: document upcoming change from \"sha1\" to \"sha256\"","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-14T06:42:39Z","receivedAt":"2024-06-14T06:42:44Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"Starting with 8e42eb0e9a (doc: sha256 is no longer experimental,\n2023-07-31), the \"sha256\" object format is no longer considered to be\nexperimental. Furthermore, the SHA-1 hash function is actively\nrecommended against by for example NIST and FIPS 140-2, and attacks\nagainst it are becoming more practical both due to new weaknesses\n(SHAppening, SHAttered, Shambles) and due to the ever-increasing\ncomputing power. It is only a matter of time before it can be considered\nto be broken completely.\n\nLet's plan for this event by being active instead of waiting for it to\nhappend and announce that the default object format is going to change\nfrom \"sha1\" to \"sha256\" with Git 3.0.\n\nAll major Git implementations (libgit2, JGit, go-git) support the\n\"sha256\" object format and are thus prepared for this change. The most\nimportant missing piece in the puzzle is support in forges. But while\nGitLab recently gained experimental support for the \"sha256\" object\nformat though, to the best of my knowledge GitHub doesn't support it\nyet. Ideally, announcing this upcoming change will encourage forges to\nstart building that support.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++\n 1 file changed, 30 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex cb7e30312f..68ad42d805 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -70,6 +70,36 @@ be changed to or replaced in case the alternative was implemented already.\n \n === Changes\n \n+* The default hash function for new repositories will be changed from \"sha1\"\n+ to \"sha256\". SHA-1 has been deprecated by NIST in 2011 and is nowadays\n+ recommended against in FIPS 140-2 and similar certifications. Furthermore,\n+ there are practical attacks on SHA-1 that weaken its cryptographic properties:\n++\n+ ** The SHAppening (2015). The first demonstration of a practical attack\n+ against SHA-1 with 2^57 operations.\n+ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.\n+ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix\n+ attacks with 2^68 operations.\n+ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63\n+ operations.\n++\n+While we have protections in place against known attacks, it is expected\n+that more attacks against SHA-1 will be found by future research. Paired\n+with the ever-growing capability of hardware, it is only a matter of time\n+before SHA-1 will be considered broken completely. We want to be prepared\n+and will thus change the default hash algorithm to \"sha256\" for newly\n+initialized repositories.\n++\n+An important requirement for this change is that the ecosystem is ready to\n+support the \"sha256\" object format. This includes popular Git libraries,\n+applications and forges.\n++\n+There is no plan to deprecate the \"sha1\" object format at this point in time.\n++\n+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,\n+.\n+\n === Removals\n \n == Superseded features that will not be deprecated\n-- \n2.45.2.457.g8d94cfb545.dirty\n\n"},{"id":"497129","messageId":"deee0bbf667892141b2c79567d946521517fe943.1718345026.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1718345026.git.ps@pks.im","subject":"[PATCH v7 3/4] BreakingChanges: document removal of grafting","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-14T06:42:44Z","receivedAt":"2024-06-14T06:42:49Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The grafting mechanism for objects has been deprecated in e650d0643b\n(docs: mark info/grafts as outdated, 2014-03-05), which is more than a\ndecade ago. The mechanism can lead to hard-to-debug issues and has a\nsuperior replacement with replace refs.\n\nFollow through with the deprecation and mark grafts for removal in Git\n3.0.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 68ad42d805..62695ec2e1 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -102,6 +102,19 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,\n \n === Removals\n \n+* Support for grafting commits has long been superseded by git-replace(1).\n+ Grafts are inferior to replacement refs:\n++\n+ ** Grafts are a local-only mechanism and cannot be shared across\n+ repositories.\n+ ** Grafts can lead to hard-to-diagnose problems when transferring objects\n+ between repositories.\n++\n+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark\n+info/grafts as outdated, 2014-03-05) and will be removed.\n++\n+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.\n+\n == Superseded features that will not be deprecated\n \n Some features have gained newer replacements that aim to improve the design in\n-- \n2.45.2.457.g8d94cfb545.dirty\n\n"},{"id":"497130","messageId":"25b20bb0ca84e6c97d27688f5e7a5f28c7ad5d1b.1718345026.git.ps@pks.im","threadId":"61428","inReplyTo":"cover.1718345026.git.ps@pks.im","subject":"[PATCH v7 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-14T06:42:48Z","receivedAt":"2024-06-14T06:42:54Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The git-checkout(1) command is seen by many as hard to understand\nbecause it connects two somewhat unrelated features: switching between\nbranches and restoring worktree files from arbitrary revisions. In 2019,\nwe thus implemented two new commands git-switch(1) and git-restore(1) to\nsplit out these separate concerns into standalone functions.\n\nThis \"replacement\" of git-checkout(1) has repeatedly triggered concerns\nfor our userbase that git-checkout(1) will eventually go away. This is\nnot the case though: the use of that command is still widespread, and it\nis not expected that this will change anytime soon.\n\nDocument that all three commands will remain for the foreseeable future.\nThis decision may be revisited in case we ever figure out that most\neveryone has given up on any of the commands.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/BreakingChanges.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 62695ec2e1..ba86c0224d 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -121,3 +121,15 @@ Some features have gained newer replacements that aim to improve the design in\n certain ways. The fact that there is a replacement does not automatically mean\n that the old way of doing things will eventually be removed. This section tracks\n those features with newer alternatives.\n+\n+* The features git-checkout(1) offers are covered by the pair of commands\n+ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still\n+ widespread, and it is not expected that this will change anytime soon, all\n+ three commands will stay.\n++\n+This decision may get revisited in case we ever figure out that there are\n+almost no users of any of the commands anymore.\n++\n+Cf. ,\n+,\n+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.\n-- \n2.45.2.457.g8d94cfb545.dirty\n\n"},{"id":"497177","messageId":"xmqq1q4zik2m.fsf@gitster.g","threadId":"61428","inReplyTo":"6348f27b591f306d79c69594ed3157e22ac4774c.1718345026.git.ps@pks.im","subject":"Re: [PATCH v7 1/4] docs: introduce document to announce breaking changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-14T16:08:01Z","receivedAt":"2024-06-14T16:08:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> +to see the message and its surrounding discussion. Such a reference is there to\n> +make it easier for you to find how the project reached concensus on the\n> +described item back then.\n\nSorry if I typofixed silently and locally without mentioning in my\nreviews for the earlier cycles, but I noticed that the fix\n\"concensus\" -> \"consensus\" I had in 'seen' is gone from this\nversion.\n\nI'll locally amend.\n\nThanks.\n"}]}