| Message ID | 2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [RFC,v2] docs: document upcoming breaking changes | expand |
Patrick Steinhardt <ps@pks.im> writes: [snip] > +### Removals > + > + - git-http-push(1) can be used to push objects to a remote repository via > + HTTP/DAV. Support for write support via WebDAV is not in widespread use > + nowadays anymore and will be removed together with the command. > + > + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP > + server like Apache. The protocol has not seen any updates recently and is > + neither compatible with alternative hash functions nor with alternative ref > + backends. It will thus be removed. > + > + - git-update-server-info(1) generates data required when serving data via the > + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose > + anymore and will be removed together with the protocol. This includes the > + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the > + `git repack -n` flag. > + > + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify > + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This > + concept has long been replaced by remotes and will thus be removed. > + > + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an > + HTTP server. These scripts have been unmaintained for a significant amount of > + time and will be removed. > + > + - git-filter-branch(1) can be used to rewrite history of a repository. It is > + very slow, hard to use and has many gotchas. It will thus be removed in favor > + of [git-filter-repo](https://github.com/newren/git-filter-repo). > + > + - The "dashed form", i.e. support for calling `git-<command>` instead of > + `git <command>` in scripts, has been deprecated for a long time and will be > + removed. > + > + - The command to import patches from Quilt seems to be used rarely, if > + ever, and will be removed. > + > + - Support for importing repositories from GNU Arch will be removed because > + it would not appear to have any users. > + > + - Support for interacting with CVS repositories (via `cvsimport`, > + `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by > + the number of times these commands have been mentioned recently. The > + code has been essentially unmaintained, too, and will be removed. > + > + - Support for grafting commits has long been superseded by git-replace(1). > + Grafts are inferior to replacement refs as the mechanism can lead to > + hard-to-diagnose problems when transferring objects between repositories. > + They have been outdated since e650d0643b (docs: mark info/grafts as outdated, > + 2014-03-05) and will be removed. I think it is worthwhile also looking at the number of commands we have and see that some of these could possibly be marked deprecated, maybe removal could follow too: * add, stage Here, `stage` is synonym and can be just dropped. * prune, prune-packed `prune-packed` prunes objects from packed files, perhaps could be a sub-command on the existing `prune` command. * annotate, blame, pickaxe You've mentioned `annotate` below, but we could also remove `pickaxe`. * log, whatchanged, shortlog Here `log` already handles what the other two commands do. * for-each-ref, show-ref These two commands do very similar things, i.e. list references. Both diverge in the features they provided, but its not clear why we have the two. * verify-commit, verify-pack, verify-tag These could probably be subcommands under the verify command. * diff, diff-files, diff-index, diff-tree Here, `diff` seems to handle everything that the others do. > +## Superseded features that will not be deprecated > + > +Some features have gained newer replacements that aim to improve the design in > +certain ways. The fact that there is a replacement does not automatically mean > +that the old way of doing things will eventually be removed. This section tracks > +those superseded features. > + > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As > + the maintenance burden of carrying both of these commands is negligible, both > + commands will stay. > + > While maintenance burden is an issue for us. There is also an user experience point of view, having similar commands doing similar operations is often a cause for confusion. > + - git-restore(1) and git-switch(1) have been introduced as a replacement for > + git-checkout(1). As git-checkout(1) is quite established, and as the benefit > + of switching to git-restore(1) and git-switch(1) is contended, all three > + commands will stay. > + > + - git-config(1) has learned to use subcommands that replace implicit actions > + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config > + --unset-all`). The action flags will not be removed in the next major Git > + release as there likely exist a lot of scripts out there that use the old > + syntax.
On Tue, May 14, 2024 at 06:48:38AM -0400, Karthik Nayak wrote: > Patrick Steinhardt <ps@pks.im> writes: [snip] > I think it is worthwhile also looking at the number of commands we have > and see that some of these could possibly be marked deprecated, maybe > removal could follow too: > > * add, stage > Here, `stage` is synonym and can be just dropped. I wonder whether there are any arguments in favor of git-stage(1). I myself haven't even been aware of this command and have never seen it out there in the wild. Which would be an indicator that we can safely remove it. Comments? > * prune, prune-packed > `prune-packed` prunes objects from packed files, perhaps could be a > sub-command on the existing `prune` command. I think we should refrain from adding anything to this document that is not yet feasible. In other words, once git-prune(1) learns to prune packed objects we may want to think about whether git-prune-packed(1) can be deprecated, but not beforehand. > * annotate, blame, pickaxe > You've mentioned `annotate` below, but we could also remove `pickaxe`. I think most oldtimers use git-blame(1), whereas git-annotate(1) has been introduced to make the command less judgemental. I'd thus say that this falls into the category of commands that we wouldn't want to deprecate because they are both used. For git-pickaxe(1) it's a bit of a different story though. We do not even have a manpage for it anymore. I wouldn't mind deprecating that one fully. > * log, whatchanged, shortlog > Here `log` already handles what the other two commands do. Does git-log(1) really support everything that git-shortlog(1) does? If so then this would be entirely new to me, but you never know with Git :) git-whatchanged(1) has been essentially deprecated already. So that may be a worthwhile addition. > * for-each-ref, show-ref > These two commands do very similar things, i.e. list references. Both > diverge in the features they provided, but its not clear why we have the > two. True, they have clear overlap and both are part of plumbing. I never quite know which one to pick. But git-show-ref(1) handles things that git-for-each-ref(1) doesn't ("--exists", "--verify") and the other way round ("--stdin", "--sort=", many more). Honestly, I think that both of these are not ideal. I think we should think bigger in this context and introduce a new command with proper subcommands to make the whole story around refs more coherent and discoverable: # Replaces git-show-ref(1) and git-for-each-ref(1). $ git refs list # Replaces `git show-ref --exists`. $ git refs exist # Replaces `git show-ref --verify <ref>`. $ git refs show # Replaces git-symbolic-ref(1) to show a ref. $ git refs resolve # Replaces git-pack-ref(1). $ git refs pack # Replaces git-update-ref(1). $ git refs write # Replaces git-check-ref-format(1). $ git refs check-format This is of course a much larger topic and something that is very much up for discussion. But in any case, it indicates that a deprecation would be premature at this point in time. > * verify-commit, verify-pack, verify-tag > These could probably be subcommands under the verify command. Same here -- as we don't have the command yet, I think it's premature the old commands to a list of deprecations. > * diff, diff-files, diff-index, diff-tree > Here, `diff` seems to handle everything that the others do. These do have different scopes though. While git-diff(1) is part of porcelain, the others are all part of the plumbing layer. As such, we provide different guarantees. In practice it's likely a different story though as my assumption is that git-diff(1) will be used in scripts a lot. But in any case, I think that this is a separate topic that would first need some discussion. > > +## Superseded features that will not be deprecated > > + > > +Some features have gained newer replacements that aim to improve the design in > > +certain ways. The fact that there is a replacement does not automatically mean > > +that the old way of doing things will eventually be removed. This section tracks > > +those superseded features. > > + > > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As > > + the maintenance burden of carrying both of these commands is negligible, both > > + commands will stay. > > + > > > > While maintenance burden is an issue for us. There is also an user > experience point of view, having similar commands doing similar > operations is often a cause for confusion. In this case I think it's okay as the documentation of git-annotate(1) clearly states that it is the same as git-blame(1). But it is certainly true that synonyms also add to perceived complexity of Git. Patrick
Hello Karthik, On 2024-05-14 12:48, Karthik Nayak wrote: > I think it is worthwhile also looking at the number of commands we have > and see that some of these could possibly be marked deprecated, maybe > removal could follow too: > > * log, whatchanged, shortlog > Here `log` already handles what the other two commands do. I haven't used "git shortlog" myself, but I think it sees a fair amount of use in various project maintainer reports. Thus, I don't think it should be marked as deprecated.
Patrick Steinhardt <ps@pks.im> writes: >> * annotate, blame, pickaxe >> You've mentioned `annotate` below, but we could also remove `pickaxe`. > > I think most oldtimers use git-blame(1), whereas git-annotate(1) has > been introduced to make the command less judgemental. I'd thus say that > this falls into the category of commands that we wouldn't want to > deprecate because they are both used. Personally I do not think blame is "judgemental" in the first place, and I do not think being "judgemental" is bad to begin with. "git annotate" was there first as a Perl script, added by c65e8987 (Add git-annotate, a tool for assigning blame., 2006-02-20). It is intersting to note that "annotate" was advertised as a tool for assigning blame. "git blame" was written almost around the same time but with "-c" compatiblity mode to mimick "git annotate", added by cbfb73d7 (Add git-blame, a tool for assigning blame., 2006-02-21). A healthy competition between "annotate" and "blame" continued until f789e347 (Remove git-annotate.perl and create a builtin-alias for git-blame, 2006-10-09) retired the "git annotate" Perl script, and replaced it with an invocation of "git blame -c". "git blame" was rewritten under the codename "git pickaxe" (cf. https://lore.kernel.org/git/7vr6xddm7h.fsf@assigned-by-dhcp.cox.net/), and was released at cee7f245 (git-pickaxe: blame rewritten., 2006-10-19). acca687f (git-pickaxe: retire pickaxe, 2006-11-08) made it take over the old implementation of "git blame". The name "pickaxe" can be easily removed, as the log message of acca687f already said back then. As everybody noticed, it is not even documented. >> * log, whatchanged, shortlog >> Here `log` already handles what the other two commands do. > > Does git-log(1) really support everything that git-shortlog(1) does? Of course not. The filtering behaviour of shortlog is unique to the command. > This is of course a much larger topic and something that is very much up > for discussion. But in any case, it indicates that a deprecation would > be premature at this point in time. Yes, please exclude anything that needs new development while discussing this topic. Anybody jumping into this discussion should take the word "upcoming" in the title more seriously. So I won't talk about unifying "describe" and "name-rev" somehow ;-) >> * verify-commit, verify-pack, verify-tag >> These could probably be subcommands under the verify command. > > Same here -- as we don't have the command yet, I think it's premature > the old commands to a list of deprecations. > >> * diff, diff-files, diff-index, diff-tree >> Here, `diff` seems to handle everything that the others do. No, diff-files, diff-index and diff-tree can do their thing without getting broken by end-user configuration. Writing your script with "git diff" and you can keep both halves.
diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md new file mode 100644 index 0000000000..8c7a5f2f38 --- /dev/null +++ b/Documentation/UpcomingBreakingChanges.md @@ -0,0 +1,119 @@ +# Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + + - Changes to long established defaults. + + - Concepts that have been replaced with a superior design. + + - Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed. + +The Git project will thus irregularly release major versions that deliberately +break backwards compatibility with older versions. This is done to ensure that +Git remains relevant, safe and maintainable going forward. The release cadence +of major versions is typically measured in multiple years. + +The intent of this document is to track upcoming deprecations for the next major +Git release. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions documente both +when the discussion favors deprecation, but also when it rejects a deprecation. + +It is supposed to be a living document where proposed changes and +deprecations are up for discussion. + +## Git 3.0 + +### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. <pull.762.git.1605221038.gitgitgadget@gmail.com>, + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>. + + - The default hash function for new repositories will be changed from "sha1" + to "sha256". + + - The default ref backend for new repositories will be changed from "files" to + "reftable". + +### Removals + + - git-http-push(1) can be used to push objects to a remote repository via + HTTP/DAV. Support for write support via WebDAV is not in widespread use + nowadays anymore and will be removed together with the command. + + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP + server like Apache. The protocol has not seen any updates recently and is + neither compatible with alternative hash functions nor with alternative ref + backends. It will thus be removed. + + - git-update-server-info(1) generates data required when serving data via the + dumb HTTP protocol. Given the removal of that protocol, it serves no purpose + anymore and will be removed together with the protocol. This includes the + "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the + `git repack -n` flag. + + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This + concept has long been replaced by remotes and will thus be removed. + + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an + HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed. + + - git-filter-branch(1) can be used to rewrite history of a repository. It is + very slow, hard to use and has many gotchas. It will thus be removed in favor + of [git-filter-repo](https://github.com/newren/git-filter-repo). + + - The "dashed form", i.e. support for calling `git-<command>` instead of + `git <command>` in scripts, has been deprecated for a long time and will be + removed. + + - The command to import patches from Quilt seems to be used rarely, if + ever, and will be removed. + + - Support for importing repositories from GNU Arch will be removed because + it would not appear to have any users. + + - Support for interacting with CVS repositories (via `cvsimport`, + `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by + the number of times these commands have been mentioned recently. The + code has been essentially unmaintained, too, and will be removed. + + - Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs as the mechanism can lead to + hard-to-diagnose problems when transferring objects between repositories. + They have been outdated since e650d0643b (docs: mark info/grafts as outdated, + 2014-03-05) and will be removed. + +## Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those superseded features. + + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As + the maintenance burden of carrying both of these commands is negligible, both + commands will stay. + + - git-restore(1) and git-switch(1) have been introduced as a replacement for + git-checkout(1). As git-checkout(1) is quite established, and as the benefit + of switching to git-restore(1) and git-switch(1) is contended, all three + commands will stay. + + - git-config(1) has learned to use subcommands that replace implicit actions + (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config + --unset-all`). The action flags will not be removed in the next major Git + release as there likely exist a lot of scripts out there that use the old + syntax. + + Cf. <ZjiL7vu5kCVwpsLd@tanuki>.
Over time, Git has grown quite a lot. With this evolution, many ideas that were sensible at the time they were introduced are not anymore and are thus considered to be deprecated. And while some deprecations may be noted in manpages, most of them are actually deprecated in the "hive mind" of the Git community, only. Introduce a new document that lists upcoming breaking changes, but also deprecations which we are not willing to go through with, to address this issue. This document serves multiple purposes: - It is a way to facilitate discussion around proposed deprecations. - It allows users to learn about deprecations and speak up in case they have good reasons why a certain feature should not be deprecated. - It states intent and documents where the Git project wants to go, both in the case where we want to deprecate, but also in the case where we don't want to deprecate a specific feature. The document is _not_ intended to cast every single discussion into stone. It is supposed to be a living document that may change over time when there are good reasons for it to change. Signed-off-by: Patrick Steinhardt <ps@pks.im> --- I have tried to accommodate for all feedback to v1. Most notably: - I have introduced a new section that documents concepts that are _not_ to be deprecated. The intent is to capture discussions around proposed deprecations where we ultimately decide that we do not (yet) want to deprecate it. - I have added some more proposed deprecations. As before, all of this is up for discussion and I do not want to force any of the proposed deprecations onto anybody. - I have dropped the "$GITDIR/hooks" deprecation item for now. It is premature to have it at this point in time given that the config-based approach isn't even close to landing. Patrick Range-diff against v1: 1: a78d68ecc2 ! 1: 2ef53ff98b docs: document upcoming breaking changes @@ Commit message noted in manpages, most of them are actually deprecated in the "hive mind" of the Git community, only. - Introduce a new document that lists upcoming breaking changes to address + Introduce a new document that lists upcoming breaking changes, but also + deprecations which we are not willing to go through with, to address this issue. This document serves multiple purposes: - It is a way to facilitate discussion around proposed deprecations. @@ Commit message they have good reasons why a certain feature should not be deprecated. - - It states intent and documents where the Git project wants to go. + - It states intent and documents where the Git project wants to go, + both in the case where we want to deprecate, but also in the case + where we don't want to deprecate a specific feature. The document is _not_ intended to cast every single discussion into stone. It is supposed to be a living document that may change over time @@ Documentation/UpcomingBreakingChanges.md (new) @@ +# Upcoming breaking changes + ++The Git project aims to ensure backwards compatibility to the best extent ++possible. Minor releases will not break backwards compatibility unless there is ++a very strong reason to do so, like for example a security vulnerability. ++ ++Regardless of that, due to the age of the Git project, it is only natural to ++accumulate a backlog of backwards-incompatible changes that will eventually be ++required to keep the project aligned with a changing world. These changes fall ++into several categories: ++ ++ - Changes to long established defaults. ++ ++ - Concepts that have been replaced with a superior design. ++ ++ - Concepts, commands, configuration or options that have been lacking in major ++ ways and that cannot be fixed. ++ ++The Git project will thus irregularly release major versions that deliberately ++break backwards compatibility with older versions. This is done to ensure that ++Git remains relevant, safe and maintainable going forward. The release cadence ++of major versions is typically measured in multiple years. ++ +The intent of this document is to track upcoming deprecations for the next major -+Git release. It is supposed to be a living document where proposed changes and ++Git release. Furthermore, this document also tracks what will _not_ be ++deprecated. This is done such that the outcome of discussions documente both ++when the discussion favors deprecation, but also when it rejects a deprecation. ++ ++It is supposed to be a living document where proposed changes and +deprecations are up for discussion. + +## Git 3.0 @@ Documentation/UpcomingBreakingChanges.md (new) + +### Removals + -+ - git-config(1) has learned to use subcommands that replace implicit actions -+ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config -+ --unset-all`). The actions will be removed in favor of subcommands. -+ Prerequisite for this change is that the new subcommands have been out for at -+ least for two years to give script authors time to migrate. -+ -+ Cf. <ZjiL7vu5kCVwpsLd@tanuki>. -+ + - git-http-push(1) can be used to push objects to a remote repository via + HTTP/DAV. Support for write support via WebDAV is not in widespread use + nowadays anymore and will be removed together with the command. @@ Documentation/UpcomingBreakingChanges.md (new) + shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This + concept has long been replaced by remotes and will thus be removed. + -+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will -+ be removed in favor of git-blame(1). -+ + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an + HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed. @@ Documentation/UpcomingBreakingChanges.md (new) + very slow, hard to use and has many gotchas. It will thus be removed in favor + of [git-filter-repo](https://github.com/newren/git-filter-repo). + -+ - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has -+ been a source of multiple remote code execution vulnerabilities. The feature -+ will be removed in favor of `core.hooksDirectory` and the new config-based -+ hooks. ++ - The "dashed form", i.e. support for calling `git-<command>` instead of ++ `git <command>` in scripts, has been deprecated for a long time and will be ++ removed. ++ ++ - The command to import patches from Quilt seems to be used rarely, if ++ ever, and will be removed. ++ ++ - Support for importing repositories from GNU Arch will be removed because ++ it would not appear to have any users. ++ ++ - Support for interacting with CVS repositories (via `cvsimport`, ++ `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by ++ the number of times these commands have been mentioned recently. The ++ code has been essentially unmaintained, too, and will be removed. ++ ++ - Support for grafting commits has long been superseded by git-replace(1). ++ Grafts are inferior to replacement refs as the mechanism can lead to ++ hard-to-diagnose problems when transferring objects between repositories. ++ They have been outdated since e650d0643b (docs: mark info/grafts as outdated, ++ 2014-03-05) and will be removed. ++ ++## Superseded features that will not be deprecated ++ ++Some features have gained newer replacements that aim to improve the design in ++certain ways. The fact that there is a replacement does not automatically mean ++that the old way of doing things will eventually be removed. This section tracks ++those superseded features. ++ ++ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As ++ the maintenance burden of carrying both of these commands is negligible, both ++ commands will stay. ++ ++ - git-restore(1) and git-switch(1) have been introduced as a replacement for ++ git-checkout(1). As git-checkout(1) is quite established, and as the benefit ++ of switching to git-restore(1) and git-switch(1) is contended, all three ++ commands will stay. ++ ++ - git-config(1) has learned to use subcommands that replace implicit actions ++ (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config ++ --unset-all`). The action flags will not be removed in the next major Git ++ release as there likely exist a lot of scripts out there that use the old ++ syntax. ++ ++ Cf. <ZjiL7vu5kCVwpsLd@tanuki>. Documentation/UpcomingBreakingChanges.md | 119 +++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.md