docs: document upcoming breaking changes
RFC PATCH 1/1 docs: document upcoming breaking changes
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 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.
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.
---
Please note that this is explicitly marked as a request for comments. The proposed list of changes is neither exhaustive, nor do I necessarily think that every single item on that list is a good idea. The intent is to spark discussions, so some of the ideas on the list are controversial by design.
Further note that this is not a "Git 3.0 is around the corner"-style document. I do not want to propose that a breaking Git 3.0 should be released soonish, and neither do I have the authority to decide that. I rather want us to document deprecations such that users, developers, hosters and distros are well aware of upcoming deprecations and can either speak up or prepare accordingly.
Also, while a minority of the proposed deprecations does have links to mailing list threads, the majority doesn't. If we have good discussions to link to I'd love to add those links. I hope that some of the items will spark discussions that I can link to in v2.
Patrick
Documentation/UpcomingBreakingChanges.md | 65 ++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.md
Documentation/UpcomingBreakingChanges.md new file +65 -0
@@ -0,0 +1,65 @@ +# Upcoming breaking changes + +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 +deprecations are up for discussion. + +## Git 3.0 + +### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. <[email protected]>, + <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-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. + + - 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. + + - 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. + + - 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). + + - 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.
Signature · 1 line
2.45.0
Hi Patrick,
Quoted 9 lines · Patrick Steinhardt
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 to address this issue. This document serves multiple purposes:
Quoted 7 lines
- 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.
I love it.
FWIW my first reaction was: These deprecations should be mentioned in the release notes of the current versions, as a heads-up. But then I saw the impressive list you accumulated and agree that it needs to have its own document.
Quoted 79 lines
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 <[email protected]>---
Please note that this is explicitly marked as a request for comments. The proposed list of changes is neither exhaustive, nor do I necessarily think that every single item on that list is a good idea. The intent is to spark discussions, so some of the ideas on the list are controversial by design.
Further note that this is not a "Git 3.0 is around the corner"-style document. I do not want to propose that a breaking Git 3.0 should be released soonish, and neither do I have the authority to decide that. I rather want us to document deprecations such that users, developers, hosters and distros are well aware of upcoming deprecations and can either speak up or prepare accordingly.
Also, while a minority of the proposed deprecations does have links to mailing list threads, the majority doesn't. If we have good discussions to link to I'd love to add those links. I hope that some of the items will spark discussions that I can link to in v2.
Patrick
Documentation/UpcomingBreakingChanges.md | 65 ++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.mdDocumentation/UpcomingBreakingChanges.md new file +42
-0@@ -0,0 +1,65 @@ +# Upcoming breaking changes + +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 +deprecations are up for discussion. + +## Git 3.0 + +### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. <[email protected]>, + <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-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. + + - 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
Documentation/UpcomingBreakingChanges.md line 52
Quoted 10 lines
Documentation/UpcomingBreakingChanges.md new file +10
-0+ 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. + + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will + be removed in favor of git-blame(1).
This is the only item I am not quite sure about. Its maintenance cost is negligible, I would think, and the cost of using a judging command name is less negligible.
Documentation/UpcomingBreakingChanges.md line 65
Quoted 13 lines
Documentation/UpcomingBreakingChanges.md new file +13
-0+ + - "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). + + - 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.
Since I already expressed interest in having this document, especially in the proposed form of being a _living_ document, i.e. subject to change, I would like to add:
- The "dashed form", i.e. support for calling git-<command> instead of git <command> in scripts, has been deprecated for a long time and the intention is still to remove it.
- 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.
Ciao,
Johannes
Quoted 19 lines · Johannes Schindelin
Hi Patrick,
Quoted 15 lines · Patrick Steinhardt
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 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.
Quoted 8 lines
Quoted 1 line
- It states intent and documents where the Git project wants to go.
I love it.
FWIW my first reaction was: These deprecations should be mentioned in the release notes of the current versions, as a heads-up. But then I saw the impressive list you accumulated and agree that it needs to have its own document.
Some of them are my own, some of them are Junio's.
[snip]
Quoted 6 lines
Quoted 2 lines
+ - git-annotate(1) is an alias for git-blame(1) with the
-cflag. It will
+ be removed in favor of git-blame(1).This is the only item I am not quite sure about. Its maintenance cost is negligible, I would think, and the cost of using a judging command name is less negligible.
There is of course still the problem of having multiple ways of doing the same thing, which does create mental overhead for users. But overall it's likely going to be negligible, both on our and on the user's side.
So overall I don't mind this item much, and neither do I mind which of both commands we use. I do see the argument that git-annotate(1) is less judgemental though.
Quoted 17 lines
Documentation/UpcomingBreakingChanges.md line 65
Quoted 12 lines
+ - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
Documentation/UpcomingBreakingChanges.md new file +11
-0+ 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). + + - 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.Since I already expressed interest in having this document, especially in the proposed form of being a _living_ document, i.e. subject to change, I would like to add:
Quoted 3 lines
- The "dashed form", i.e. support for calling
git-<command>instead ofgit <command>in scripts, has been deprecated for a long time and the intention is still to remove it.
Agreed!
Quoted 5 lines
- 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.
What even is GNU Arch...? Never heard of it before.
Quoted 4 lines
- Support for interacting with CVS repositories (via
cvsimport,cvsexportcommitandcvsserver) 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.
Fair.
I'd be happy to add these in v2 unless folks disagree.
Patrick
Quoted 5 lines · Patrick Steinhardt
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.
There may be a new way that we hope is more suitable for folks who are learning Git today that achieves the same goal as an old way. It rarely means that the old way goes away, even when the new way is more capable than the old way and the use case the new way covers is a strict superset of the old way.
Such an introduction of a new way is *not* a breaking change. Everything the first paragraph talks about is a "deprecation" that does not break anything. Documenting them is worthwhile, but it is worth pointing out that it not what the title of the topic "upcoming breaking changes" covers.
I think you should explicitly say that we deprecate but rarely remove and old ways are kept for backward compatibility in that introductory paragraph. Then propose "But we may want to remove old ways and deliberately break at a large version bump every 5 years". That will lead your readers more smoothly to the next paragraph.
Quoted 10 lines
Introduce a new document that lists upcoming breaking changes 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.
Another thing we may want to describe in such a document is what we do not want to drop and why, even when a new way that is a superset is available, which would give newbies with a natural "why don't we force everybody including the old timers to adopt new ways" question a reasonable answer.
Quoted 3 lines
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.
I'll stop here, as arguing how an individual bullet item is not appropriate (i.e., deprecating it is a bad idea) should be left for later stages of the discussion, after we accumulated more ideas.
Thanks.
Quoted 20 lines · Junio C Hamano
Quoted 5 lines · Patrick Steinhardt
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.
There may be a new way that we hope is more suitable for folks who are learning Git today that achieves the same goal as an old way. It rarely means that the old way goes away, even when the new way is more capable than the old way and the use case the new way covers is a strict superset of the old way.
Such an introduction of a new way is *not* a breaking change. Everything the first paragraph talks about is a "deprecation" that does not break anything. Documenting them is worthwhile, but it is worth pointing out that it not what the title of the topic "upcoming breaking changes" covers.
Quoted 5 lines
I think you should explicitly say that we deprecate but rarely remove and old ways are kept for backward compatibility in that introductory paragraph. Then propose "But we may want to remove old ways and deliberately break at a large version bump every 5 years". That will lead your readers more smoothly to the next paragraph.
Agreed, I'll something along these lines.
Quoted 9 lines
Quoted 9 lines
Introduce a new document that lists upcoming breaking changes 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.
Quoted 7 lines
Quoted 1 line
- It states intent and documents where the Git project wants to go.
Another thing we may want to describe in such a document is what we do not want to drop and why, even when a new way that is a superset is available, which would give newbies with a natural "why don't we force everybody including the old timers to adopt new ways" question a reasonable answer.
Okay, I see how that may make sense for some parts. I guess one of the motivations here is things like git-checkout(1) and git-switch(1) / git-restore(1)?
Do we want to give this class a separate name? Deprecated may feel a bit too strong in that context as it does imply eventual removal for many folks (including me, I guess). Is "superseded" better?
Patrick
Quoted 9 lines · Patrick Steinhardt
Quoted 5 lines
Another thing we may want to describe in such a document is what we do not want to drop and why, even when a new way that is a superset is available, which would give newbies with a natural "why don't we force everybody including the old timers to adopt new ways" question a reasonable answer.
Okay, I see how that may make sense for some parts. I guess one of the motivations here is things like git-checkout(1) and git-switch(1) / git-restore(1)?
Anything that we initially think it may make sense to remove but turns out that they are so ingrained in workflows that may lead some users to stick to pre-3.0 version. As this is a living document, instead of removing some ideas that are "voted down", recording the reason why we voted it down would make sense. Checkout and annotate are the ones that were named so far in the discussion, but I suspect there will be more.
Quoted 3 lines
Do we want to give this class a separate name? Deprecated may feel a bit too strong in that context as it does imply eventual removal for many folks (including me, I guess). Is "superseded" better?
Traditional/established ways that will not go away?
Hello Patrick,
Quoted 3 lines · Patrick Steinhardt
Okay, I see how that may make sense for some parts. I guess one of the motivations here is things like git-checkout(1) and git-switch(1) / git-restore(1)?
As I wrote already, [1] I really see no reasons why git-switch(1) or git-restore(1) should be deprecated. That would make zero sense to me.
Quoted 7 lines · Dragan Simic
Hello Patrick,
Quoted 3 lines · Patrick Steinhardt
Okay, I see how that may make sense for some parts. I guess one of the motivations here is things like git-checkout(1) and git-switch(1) / git-restore(1)?
Quoted 5 lines
As I wrote already, [1] I really see no reasons why git-switch(1) or git-restore(1) should be deprecated. That would make zero sense to me.
Note that the discussion here is the other way round: whether we want to eventually deprecate tools like git-checkout(1) that have newer replacements. Junio argues that there being a replacement is not by itself a good enough reason to eventually remove the old one, which I'm fine with.
Patrick
Hello Patrick,
Quoted 9 lines · Patrick Steinhardt
Quoted 8 lines · Dragan Simic
Quoted 3 lines · Patrick Steinhardt
Okay, I see how that may make sense for some parts. I guess one of the motivations here is things like git-checkout(1) and git-switch(1) / git-restore(1)?
As I wrote already, [1] I really see no reasons why git-switch(1) or git-restore(1) should be deprecated. That would make zero sense to me.
Quoted 7 lines
Quoted 1 line
Note that the discussion here is the other way round: whether we want to eventually deprecate tools like git-checkout(1) that have newer replacements. Junio argues that there being a replacement is not by itself a good enough reason to eventually remove the old one, which I'm fine with.
I agree that not deprecating git-checkout(1) and similar utilities is the way to go. It's rather safe to assume that many users still use them, despite the existence of the newer replacements. Also, not just users, but various scripts.
Hi Patrick
Thanks putting this together, I think it will be a useful way discussing deprecations and removals.
Quoted 9 lines · Patrick Steinhardt
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 to address this issue. This document serves multiple purposes:
Quoted 7 lines
- 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.
Is the plan to use this document to track the progress/status of proposed deprecations? For example the config based hooks implementation is stalled at the moment and would need some work before we can remove $GIT_DIR/hooks
Documentation/UpcomingBreakingChanges.md line 28
Quoted 7 lines
Documentation/UpcomingBreakingChanges.md new file +7
-0+### 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.
I agree we want to allow plenty of time for script authors to migrate their scripts here.
Quoted 2 lines
+ - githooks(5) can be installed by placing them into
$GIT_DIR/hooks/. This has
+ been a source of multiple remote code execution vulnerabilities.
I'm not sure about the reasoning here as a hook has to be enabled by the user before it is run. There are good reasons to prefer config based hooks such as the ability to run multiple scripts per hook event but I don't think they are inherently more secure.
Best Wishes
Phillip
Quoted 21 lines · Phillip Wood
Hi Patrick
Thanks putting this together, I think it will be a useful way discussing deprecations and removals.
Quoted 15 lines · Patrick Steinhardt
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 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.
Quoted 5 lines
Quoted 1 line
- It states intent and documents where the Git project wants to go.
Is the plan to use this document to track the progress/status of proposed deprecations? For example the config based hooks implementation is stalled at the moment and would need some work before we can remove $GIT_DIR/hooks
I also have it in my backlog to propose a file that may keep a record of long-running projects. The intent would be similar to this patch here, but it should also help newcomers to find projects to work on.
This would track:
- Large-scale efforts like the past SHA256 migration or removal of the_repository.
- Small projects or microprojects like we have in GSoC to help out newcomers when they want to work on stuff.
- Things we have already discussed, but simply didn't get landed yet like the hooks refactoring.
So agreed, the hook refactorings should not be part of the deprecations document when it hasn't even landed yet.
Quoted 11 lines
Documentation/UpcomingBreakingChanges.md line 28
Quoted 7 lines
Documentation/UpcomingBreakingChanges.md new file +7
-0+### 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.I agree we want to allow plenty of time for script authors to migrate their scripts here.
Quoted 7 lines
Quoted 2 lines
+ - githooks(5) can be installed by placing them into
$GIT_DIR/hooks/. This has
+ been a source of multiple remote code execution vulnerabilities.I'm not sure about the reasoning here as a hook has to be enabled by the user before it is run. There are good reasons to prefer config based hooks such as the ability to run multiple scripts per hook event but I don't think they are inherently more secure.
I'll remove this item for now. We can discuss it again when (if) the config based mechanisms land.
Patrick
On 24/05/07 10:27AM, Patrick Steinhardt wrote:
+### Removals
Quoted 33 lines
Documentation/UpcomingBreakingChanges.md new file +33
-0+ + - 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. + + - 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. + + - 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
Documentation/UpcomingBreakingChanges.md line 65
Quoted 10 lines
Documentation/UpcomingBreakingChanges.md new file +10
-0+ 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). + + - 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.
I would like to see the double dot and triple dot syntax (".." and "...") removed from git-diff(1) as I think they get easily confused with revision ranges.
-Justin
Quoted 3 lines · Justin Tobler
I would like to see the double dot and triple dot syntax (".." and "...") removed from
git-diff(1)as I think they get easily confused with revision ranges.
I tend to agree that the double-dot notation does not need to exist as it can be done with a pair of bog-standard revs. But triple-dot notation needs a replacement syntax that is just as easy to access the feature as the current syntax. After updating a tip of a topic branch,
$ git diff topic@{1}...topicis extremely useful (in addition to "git log -p" and the like, of course, with the same range). Also during a conflicted merge
$ git diff ...MERGE_BASE
and its reverse are very handy. Having to say "--merge-base" is probably a usability regression.
If somebody wants to pursue this further, my recommendation is to treat the two separately.
* Deprecate and eventually remove double-dot notation.
- First, notice the use of double-dot notation. builtin/diff.c:symdiff_prepare() is the place to do so. Issue a warning about deprecation and possibility of an eventual removal, and tell the users to use "diff A B" instead of "diff A..B".
- Gain consensus that the removal is a good idea. Finish these steps long before Git 3.0.
- Remove the support for A..B.
* Deprecate and eventually remove triple-dot notation.
- Introduce a new syntax to allow an access to the "symmetric diff" feature just as easily as the current syntax. Wait for a handful releases to gauge its acceptance by the end users.
- Then notice the use of triple-dot notation. The place to do sois the same builtin/diff.c:symdiff_prepare(). Give a warning about deprecation and possibility of an eventual removal, and tell the users to use that new syntax we introduced.
- Gain consensus that the removal is a good idea. Finish these steps long before Git 3.0.
- Remove the support for A...B.
Quoted 49 lines · Junio C Hamano
Quoted 3 lines · Justin Tobler
I would like to see the double dot and triple dot syntax (".." and "...") removed from
git-diff(1)as I think they get easily confused with revision ranges.I tend to agree that the double-dot notation does not need to exist as it can be done with a pair of bog-standard revs. But triple-dot notation needs a replacement syntax that is just as easy to access the feature as the current syntax. After updating a tip of a topic branch,
$ git diff topic@{1}...topicis extremely useful (in addition to "git log -p" and the like, of course, with the same range). Also during a conflicted merge
$ git diff ...MERGE_BASEand its reverse are very handy. Having to say "--merge-base" is probably a usability regression.
If somebody wants to pursue this further, my recommendation is to treat the two separately.
* Deprecate and eventually remove double-dot notation.
- First, notice the use of double-dot notation. builtin/diff.c:symdiff_prepare() is the place to do so. Issue a warning about deprecation and possibility of an eventual removal, and tell the users to use "diff A B" instead of "diff A..B".
- Gain consensus that the removal is a good idea. Finish these steps long before Git 3.0.
- Remove the support for A..B.
* Deprecate and eventually remove triple-dot notation.
- Introduce a new syntax to allow an access to the "symmetric diff" feature just as easily as the current syntax. Wait for a handful releases to gauge its acceptance by the end users.
- Then notice the use of triple-dot notation. The place to do sois the same builtin/diff.c:symdiff_prepare(). Give a warning about deprecation and possibility of an eventual removal, and tell the users to use that new syntax we introduced.
Quoted 4 lines
- Gain consensus that the removal is a good idea. Finish these steps long before Git 3.0.
- Remove the support for A...B.
I'll leave these for a future iteration for now given that there is more work that needs to be done in this context.
Patrick
RFC PATCH v2 1/1 docs: document upcoming breaking changes
In reply to Patrick SteinhardtOver 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.
---
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
Documentation/UpcomingBreakingChanges.md new file +119 -0
@@ -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. <[email protected]>, + <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>.
Signature · 1 line
2.45.GIT
Patrick Steinhardt <[email protected]> writes:
[snip]
Quoted 39 lines
Documentation/UpcomingBreakingChanges.md new file +39
-0+### 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. +
Documentation/UpcomingBreakingChanges.md line 95
Quoted 10 lines
Documentation/UpcomingBreakingChanges.md new file +10
-0+ - 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-packedprune-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.
Documentation/UpcomingBreakingChanges.md line 107
Quoted 12 lines
Documentation/UpcomingBreakingChanges.md new file +11
-0+## 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.
Quoted 10 lines
+ - git-restore(1) and git-switch(1) have been introduced as a replacement for
Documentation/UpcomingBreakingChanges.md new file +9
-0+ 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.
Quoted 1 line · Karthik Nayak
Patrick Steinhardt <[email protected]> writes:
[snip]
Quoted 6 lines
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,stageis 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?
Quoted 3 lines
* prune, prune-packed
prune-packedprunes objects from packed files, perhaps could be a sub-command on the existingprunecommand.
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.
Quoted 2 lines
* annotate, blame, pickaxe
You've mentionedannotatebelow, but we could also removepickaxe.
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.
Quoted 2 lines
* log, whatchanged, shortlog
Herelogalready 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.
Quoted 4 lines
* 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.
Quoted 2 lines
* 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.
Quoted 2 lines
* diff, diff-files, diff-index, diff-tree
Here,diffseems 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.
Quoted 8 lines
Quoted 8 lines
Documentation/UpcomingBreakingChanges.md new file +8
-0+## 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
Quoted 8 lines
Documentation/UpcomingBreakingChanges.md line 107
Quoted 4 lines
Documentation/UpcomingBreakingChanges.md new file +3
-0+ 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
Quoted 7 lines · Patrick Steinhardt
Quoted 2 lines
* annotate, blame, pickaxe
You've mentionedannotatebelow, but we could also removepickaxe.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/[email protected]/),
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.
Quoted 4 lines
Quoted 2 lines
* log, whatchanged, shortlog
Herelogalready 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.
Quoted 3 lines
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 ;-)
Quoted 8 lines
Quoted 2 lines
* 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.
Quoted 2 lines
* diff, diff-files, diff-index, diff-tree
Here,diffseems 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.
Hello Karthik,
Quoted 6 lines · Karthik Nayak
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
Herelogalready 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.
PATCH v3 1/1 docs: document upcoming breaking changes
In reply to Patrick SteinhardtOver 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.
---
I've dropped the RFC prefix of this series now. I think that the overall idea has been received well, and folks are supportive of documenting upcoming breaking changes.
There's only a single change compared to the second version. In any case, most of the proposed deprecations didn't get much pushback. I'm less sure whether this is because people didn't look, or because they silently agree with what I propose for deprecation.
I'm going to assume it's the latter. If you feel otherwise, my proposed way forward would be to drop most of the items, merge the document, and then add items via separate threads where we can discuss each deprecation on its own.
Please let me know your preference!
Patrick
Range-diff against v2:
1: 8e268a291b ! 1: 84c01f1b0a docs: document upcoming breaking changes
@@ Documentation/UpcomingBreakingChanges.md (new)
+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
+ 2014-03-05) and will be removed.
+
++ - git-pickaxe, an alias for git-blame(1), has been retired in acca687fa9
++ (git-pickaxe: retire pickaxe, 2006-11-08) and will be removed.
++
+## Superseded features that will not be deprecated
+
+Some features have gained newer replacements that aim to improve the design in
Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.md
Documentation/UpcomingBreakingChanges.md new file +122 -0
@@ -0,0 +1,122 @@ +# 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. <[email protected]>, + <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. + + - git-pickaxe, an alias for git-blame(1), has been retired in acca687fa9 + (git-pickaxe: retire pickaxe, 2006-11-08) 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>.
base-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f
Signature · 1 line
2.45.1.246.gb9cfe4845c.dirty
Quoted 3 lines · Patrick Steinhardt
case, most of the proposed deprecations didn't get much pushback. I'm less sure whether this is because people didn't look, or because they silently agree with what I propose for deprecation.
Or because I explicitly said that first we'll brainstorm, in order to encourage generation of more ideas, without shooting other people's ideas down?
Quoted 30 lines
Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Documentation/UpcomingBreakingChanges.mdDocumentation/UpcomingBreakingChanges.md new file +20
-0@@ -0,0 +1,122 @@ +# 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
Documentation/UpcomingBreakingChanges.md line 30
Quoted 10 lines
Documentation/UpcomingBreakingChanges.md new file +10
-0+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.
OK.
Documentation/UpcomingBreakingChanges.md line 32
Quoted 1 line
Documentation/UpcomingBreakingChanges.md new file +1
-0+## Git 3.0
Question.
Will we have "## Git 4.0" etc., to indicate the timelines (some stuff we might eventually replace/change, but we may not ready yet by the time 3.0 comes)? Or do we assme that an idea we agree enough on to add to this document would all be ready to be implemented by 3.0?
Documentation/UpcomingBreakingChanges.md line 39
Quoted 6 lines
Documentation/UpcomingBreakingChanges.md new file +6
-0+### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. <[email protected]>, + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
Forcing readers to read entire threads for these two discussions somehow feels brutal at least to me. And reading only these two individual messages does not give readers much insight.
Saying "this was discussed in the past in late 2020, and because major hosting sites give 'main' as the initial branch by default for new users unless configured these days, we will match to avoid end user confusion", if we want to explain why we are changing it, should be sufficient. But seeing that the other two items below do not have any such explanation, we may be better of not having it here, perhaps?
I take this iteration to illustrate the format of items (and what kinds of items) we want to have in the document. If the proposal made by the above item is:
Once we have a discussion thread that shows clear concensus (neither of the above two are not), we'd record the decision and have a reference to the thread.
then I 100% agree with the plan for this document.
Quoted 16 lines
Documentation/UpcomingBreakingChanges.md new file +16
-0+ - 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.
Documentation/UpcomingBreakingChanges.md line 66
Quoted 10 lines
Documentation/UpcomingBreakingChanges.md new file +10
-0+ + - 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.
"remotes" -> "the 'remotes.*.*' configuration variables", perhaps?
Documentation/UpcomingBreakingChanges.md line 70
Quoted 3 lines
Documentation/UpcomingBreakingChanges.md new file +3
-0+ - "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.
Do we want to give plausible alternatives (or merely hinting existence of alternatives might be sufficient)?
Documentation/UpcomingBreakingChanges.md line 78
Quoted 7 lines
Documentation/UpcomingBreakingChanges.md new file +7
-0+ - 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.
I find this questionable but as you said, we'll start from skeletal form of this document (without any items), have discussion thread on each of these items, and add back those we have concensus on, so I'll not further talk about this item in this message.
Documentation/UpcomingBreakingChanges.md line 81
Quoted 2 lines
Documentation/UpcomingBreakingChanges.md new file +2
-0+ - The command to import patches from Quilt seems to be used rarely, if + ever, and will be removed.
Not limited to this item, but do we want to mention in this document how we measured the actual usage, which we base our deprecation decision on? I do not think such a comment should be attached to each of these items (this one and the next one are proposed for the same reason),...
Documentation/UpcomingBreakingChanges.md line 84
Quoted 2 lines
Documentation/UpcomingBreakingChanges.md new file +2
-0+ - Support for importing repositories from GNU Arch will be removed because + it would not appear to have any users.
... but in a preamble of the document, e.g., "methodology and criteria we used to propose these removals". Random ideas that may or may not work:
- debian popcon?
- google trends, counting the appearance of queries?
- telemetry from commands that call home (we do not have any)?
Documentation/UpcomingBreakingChanges.md line 122
Quoted 7 lines
Documentation/UpcomingBreakingChanges.md new file +7
-0+ - 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>.
This is a good example of "we had a concensus back when this was discussed; see the thread this message is on". I think it would be beneficial to write down what these references _mean_ at the beginning of the document, e.g.
When this document refers to a message-ID, you can visit
https://lore.kernel.org/git/$message_id/
to see the message and its surrounding discussion. Such a reference is there to make it easier for you to find that the project reached concensus on the described item back then. As this is a living document, and the environment surrounding the project changes over time, an earlier decision to deprecate or change something may need to be revisited from time to time, so do not take these references to mean "it is settled, do not waste our time bringing it up again".
or something like that.
Thanks.
Quoted 9 lines · Junio C Hamano
Quoted 3 lines · Patrick Steinhardt
case, most of the proposed deprecations didn't get much pushback. I'm less sure whether this is because people didn't look, or because they silently agree with what I propose for deprecation.
Or because I explicitly said that first we'll brainstorm, in order to encourage generation of more ideas, without shooting other people's ideas down?
Fair, I guess.
[snip]
Quoted 9 lines
Quoted 1 line
+## Git 3.0
Question.
Will we have "## Git 4.0" etc., to indicate the timelines (some stuff we might eventually replace/change, but we may not ready yet by the time 3.0 comes)? Or do we assme that an idea we agree enough on to add to this document would all be ready to be implemented by 3.0?
Good question. For now I have added such items to the "Superseded features that will not be deprecated" section, with a hint that we may revisit the deprecation in the future. E.g. for the git-config(1) actions I say the following:
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.
I think that this is easiest to manage for other features where we are not yet ready to commit to a deprecation, as well, due to whatever reason. Those items can be added along with a condition that, once met, may prompt us to revisit a deprecation.
Quoted 23 lines
Documentation/UpcomingBreakingChanges.md line 39
Quoted 6 lines
Documentation/UpcomingBreakingChanges.md new file +6
-0+### Changes + + - The default initial branch name will be changed from "master" to "main". + + Cf. <[email protected]>, + <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.Forcing readers to read entire threads for these two discussions somehow feels brutal at least to me. And reading only these two individual messages does not give readers much insight.
Saying "this was discussed in the past in late 2020, and because major hosting sites give 'main' as the initial branch by default for new users unless configured these days, we will match to avoid end user confusion", if we want to explain why we are changing it, should be sufficient. But seeing that the other two items below do not have any such explanation, we may be better of not having it here, perhaps?
I take this iteration to illustrate the format of items (and what kinds of items) we want to have in the document. If the proposal made by the above item is:
Quoted 5 lines
Once we have a discussion thread that shows clear concensus (neither of the above two are not), we'd record the decision and have a reference to the thread.
then I 100% agree with the plan for this document.
Yes, that's my intent. The bullet item should be self-explaining, potentially with one or two sentences explaining why. The reference to the mailing list thread is supposed to give a pointer where, when and why this decision was made so that people can revisit the discussion.
So the two bullet points below are certainly quite lazy because they do not provide any context whatsoever.
Quoted 29 lines
Quoted 16 lines
Documentation/UpcomingBreakingChanges.md new file +16
-0+ - 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.Documentation/UpcomingBreakingChanges.md line 66
Quoted 10 lines
Documentation/UpcomingBreakingChanges.md new file +10
-0+ + - 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."remotes" -> "the 'remotes.*.*' configuration variables", perhaps?
Quoted 6 lines
Documentation/UpcomingBreakingChanges.md line 70
Quoted 3 lines
+ - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
Documentation/UpcomingBreakingChanges.md new file +2
-0+ HTTP server. These scripts have been unmaintained for a significant amount of + time and will be removed.Do we want to give plausible alternatives (or merely hinting existence of alternatives might be sufficient)?
I guess that would be solutions like cgit, right? While those recommendations may go stale over time, I still think it'd be worthwhile to help our users in case they do rely on any deprecated feature.
Quoted 8 lines
Documentation/UpcomingBreakingChanges.md line 78
Quoted 7 lines
+ - git-filter-branch(1) can be used to rewrite history of a repository. It is
Documentation/UpcomingBreakingChanges.md new file +6
-0+ 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.
Quoted 4 lines
I find this questionable but as you said, we'll start from skeletal form of this document (without any items), have discussion thread on each of these items, and add back those we have concensus on, so I'll not further talk about this item in this message.
I'd propose to have one (hopefully uncontroversial) item per section just to demonstrate how the format is supposed to look like. But other than that I'm happy to drop most of these items.
Quoted 12 lines
Quoted 2 lines
+ - The command to import patches from Quilt seems to be used rarely, if
+ ever, and will be removed.Not limited to this item, but do we want to mention in this document how we measured the actual usage, which we base our deprecation decision on? I do not think such a comment should be attached to each of these items (this one and the next one are proposed for the same reason),...
Quoted 2 lines
+ - Support for importing repositories from GNU Arch will be removed because
+ it would not appear to have any users.
Quoted 7 lines
... but in a preamble of the document, e.g., "methodology and criteria we used to propose these removals". Random ideas that may or may not work:
- debian popcon?
- google trends, counting the appearance of queries?
- telemetry from commands that call home (we do not have any)?
That would certainly be helpful to give us a better base to argue.
Quoted 26 lines
Documentation/UpcomingBreakingChanges.md line 122
Quoted 7 lines
+ - git-config(1) has learned to use subcommands that replace implicit actions
Documentation/UpcomingBreakingChanges.md new file +6
-0+ (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>.This is a good example of "we had a concensus back when this was discussed; see the thread this message is on". I think it would be beneficial to write down what these references _mean_ at the beginning of the document, e.g.
When this document refers to a message-ID, you can visit
https://lore.kernel.org/git/$message_id/
to see the message and its surrounding discussion. Such a reference is there to make it easier for you to find that the project reached concensus on the described item back then. As this is a living document, and the environment surrounding the project changes over time, an earlier decision to deprecate or change something may need to be revisited from time to time, so do not take these references to mean "it is settled, do not waste our time bringing it up again".
Quoted 1 line
or something like that.
Good idea, will do.
Patrick
v4 cover docs: document upcoming breaking changes
In reply to Patrick SteinhardtHi,
this is the fourth version of my patch series that documents upcoming breaking changes.
I have restructured this series now, booting out most of the proposed deprecations. This is not because I think that those deprecations shouldn't be done, but merely to bring this series into a format that can be merged.
The first patch introduces the document in a skeletal form. The next three patches then introduce one item each to the three sections that we have in this document. The intent of this is to start out with examples of how this should look like. I have tried to pick topics which may be the least controversial ones for each of those sections while still being interesting enough to demonstrate the proposed format. Let's see whether I succeeded with that goal :)
As said, I do not have the intent to shut down any of the other proposed deprecations. When this document lands, I'd encourage folks to propose their deprecations in standalone threads, ideally together with a patch to "BreakingChanges.md".
You may have noticed that I dropped the "Upcoming" prefix from "UpcomingBreakingChanges.md". This is supposed to reflect the fact that we also have a section that point out features that we are _not_ deprecating. Those aren't upcoming, so I thought a rename makes sense.
Thanks!
Patrick
Patrick Steinhardt (4):
docs: introduce document to announce breaking changes
BreakingChanges: document upcoming change from "sha1" to "sha256"
BreakingChanges: document removal of grafting
BreakingChanges: document that we do not plan to deprecate
git-checkout
Documentation/BreakingChanges.md | 113 +++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 Documentation/BreakingChanges.md
base-commit: 3e4a232f6e3bd3b7dd920bb07b21cf1c8b4e1a7f
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
PATCH v4 1/4 docs: introduce document to announce breaking changes
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 tracks such 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.
--- Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/BreakingChanges.md
Documentation/BreakingChanges.md new file +66 -0
@@ -0,0 +1,66 @@ +# 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. + +Items should have a self-sufficient explanation why we want or do not want to +deprecate a given feature. If there are alternatives to the deprecated feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. An earlier decision to deprecate or change something may need to be +revisited from time to time. So do not take items on this list to mean "it is +settled, do not waste our time bringing it up again". + +## Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this major version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +### Changes + +### Removals + +## 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.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes
Quoted 43 lines · Patrick Steinhardt
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 tracks such 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 <[email protected]>--- Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/BreakingChanges.mdDocumentation/BreakingChanges.md new file +7
-0@@ -0,0 +1,66 @@ +# 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
Documentation/BreakingChanges.md line 17
Quoted 10 lines
Documentation/BreakingChanges.md new file +10
-0+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 first two are easy to imagine. If we change the default, people may have to retrain their fingers or rewrite their scripts. If "log" that came later is so good that even those who were using "whatchanged" have long switched to it, there will come time when nobody even notices a removal of "whatchanged".
But the third one is puzzling. If something falls into the "cannot be fixed" category, is it still one of "These changes" that "will eventually be required to [be made]"?
Documentation/BreakingChanges.md line 22
Quoted 4 lines
Documentation/BreakingChanges.md new file +4
-0+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.
Releases vX.Y.Z (0 < Z) are "maintenance releases", and I have been calling vX.Y.0 "feature releases" instead of calling them "major versions", so the above use of the phrase "major version" can fit in, but a more descriptive name, e.g., "breaking versions", might convey the intention better, perhaps?
It may be more assuring to cite the last time such a breaking version happened. Was "Git 2.0" a breaking version? If so, when did it happen? Were there other breaking versions in the past?
Documentation/BreakingChanges.md line 27
Quoted 4 lines
Documentation/BreakingChanges.md new file +4
-0+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.
We seem to focus on removals and changes; will there be a case where an upcoming addition is equally disrupting as removing an established thing? If we wanted to avoid focusing on deprecation/removals too narrowly, we could tweak the wording below, with "deprecate a given feature" -> "make the described change", etc.
Documentation/BreakingChanges.md line 31
Quoted 4 lines
Documentation/BreakingChanges.md new file +3
-0+Items should have a self-sufficient explanation why we want or do not want to +deprecate a given feature. If there are alternatives to the deprecated feature, +those alternatives should be pointed out to our users.
OK.
Documentation/BreakingChanges.md line 51
Quoted 4 lines
Documentation/BreakingChanges.md new file +4
-0+## Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this major version yet.
"upcoming breaking changes for" -> "breaking changes we plan to make in"?
Documentation/BreakingChanges.md line 55
Quoted 3 lines
Documentation/BreakingChanges.md new file +3
-0+Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already.
OK.
Documentation/BreakingChanges.md line 66
Quoted 10 lines
Documentation/BreakingChanges.md new file +10
-0+### Changes + +### Removals + +## 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.
As the title says "superseded", to help non native speakers like me, let's use a different and easier phrase with the same meaning in the body text. "... tracks those features with newer alternatives", perhaps?
Thanks.
Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes
Quoted 1 line · Junio C Hamano
Patrick Steinhardt <[email protected]> writes:
[snip]
Quoted 18 lines
Documentation/BreakingChanges.md line 17
Quoted 11 lines
Documentation/BreakingChanges.md new file +11
-0+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 first two are easy to imagine. If we change the default, people may have to retrain their fingers or rewrite their scripts. If "log" that came later is so good that even those who were using "whatchanged" have long switched to it, there will come time when nobody even notices a removal of "whatchanged".
Quoted 3 lines
But the third one is puzzling. If something falls into the "cannot be fixed" category, is it still one of "These changes" that "will eventually be required to [be made]"?
Well, for a wider definition of "change", yes. In this case the change would be that the broken concept will be ripped out of Git without any replacement.
I'll clarify this a bit further.
Quoted 10 lines
Documentation/BreakingChanges.md line 22
Quoted 4 lines
Documentation/BreakingChanges.md new file +4
-0+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.Releases vX.Y.Z (0 < Z) are "maintenance releases", and I have been calling vX.Y.0 "feature releases" instead of calling them "major versions", so the above use of the phrase "major version" can fit in, but a more descriptive name, e.g., "breaking versions", might convey the intention better, perhaps?
I was trying to stick to the names that semantic versioning uses here, but I'm happy to adapt this accordingly.
Quoted 3 lines
It may be more assuring to cite the last time such a breaking version happened. Was "Git 2.0" a breaking version? If so, when did it happen? Were there other breaking versions in the past?
I would definitely call Git 2.0 a breaking release as the changes to git-push(1)'s defaults were quite significant.
Other than that I think lines are a bit blurry. We do minor breaking changes sometimes in case certain behaviour is deemed to be buggy, and fixing such buggy behaviour may at times result in user visible changes in behaviour. I wouldn't call that a breaking release though, because we certainly want to retain the ability to fix such bugs without bumping the major version every single time. Going down that path just means that the whole versioning schema becomes meaningless, like it has become for so many other projects nowadays.
I'll also include a sentence along this line.
Quoted 10 lines
Documentation/BreakingChanges.md line 27
Quoted 4 lines
Documentation/BreakingChanges.md new file +4
-0+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.We seem to focus on removals and changes; will there be a case where an upcoming addition is equally disrupting as removing an established thing? If we wanted to avoid focusing on deprecation/removals too narrowly, we could tweak the wording below, with "deprecate a given feature" -> "make the described change", etc.
Hard to predict, I guess. Let's just rephrase it to be a bit more generic.
[snip]
Quoted 7 lines
Quoted 7 lines
Documentation/BreakingChanges.md new file +7
-0+### Changes + +### Removals + +## Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in
Quoted 8 lines
Documentation/BreakingChanges.md line 66
Quoted 3 lines
Documentation/BreakingChanges.md new file +3
-0+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.As the title says "superseded", to help non native speakers like me, let's use a different and easier phrase with the same meaning in the body text. "... tracks those features with newer alternatives", perhaps?
Sure, makes sense.
Patrick
Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes
Quoted 2 lines · Patrick Steinhardt
I would definitely call Git 2.0 a breaking release as the changes to git-push(1)'s defaults were quite significant.
Git 1.6.0 was certainly a lot more controversial than the change in Git 2.0, as the end-users never expected Git will change even with ample pre-warning. We originally had all the "git-foo" in $PATH since 2005 when Git started, and we announced that we'll stop doing so in the release notes to Git 1.5.4 with instructions on how to adjust the scripts that use "git-foo" form. Even then end-users (back then they were a lot smaller population---we are talking about Aug 2008) complained quite loudly.
[Readings]
* https://git.github.io/htmldocs/RelNotes/1.5.4.txt
* https://git.github.io/htmldocs/RelNotes/1.6.0.txt
* https://lore.kernel.org/git/[email protected]/
Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes
Quoted 14 lines · Junio C Hamano
Quoted 2 lines · Patrick Steinhardt
I would definitely call Git 2.0 a breaking release as the changes to git-push(1)'s defaults were quite significant.
Git 1.6.0 was certainly a lot more controversial than the change in Git 2.0, as the end-users never expected Git will change even with ample pre-warning. We originally had all the "git-foo" in $PATH since 2005 when Git started, and we announced that we'll stop doing so in the release notes to Git 1.5.4 with instructions on how to adjust the scripts that use "git-foo" form. Even then end-users (back then they were a lot smaller population---we are talking about Aug 2008) complained quite loudly.
Quoted 5 lines
[Readings]
* https://git.github.io/htmldocs/RelNotes/1.5.4.txt
* https://git.github.io/htmldocs/RelNotes/1.6.0.txt
* https://lore.kernel.org/git/[email protected]/
I had it in my mind that Git 1.6 was controversial, but I didn't quite know why exactly as I haven't been around at that point in time yet. I did read through its release notes to double check, but it seems like I missed the important part even though it was up front.
Thanks for the history lesson, will add!
Patrick
PATCH v4 2/4 BreakingChanges: document upcoming change from "sha1" to "sha256"
In reply to Patrick SteinhardtStarting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely.
Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
--- Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)
Documentation/BreakingChanges.md +27 -0
@@ -56,6 +56,33 @@ be changed to or replaced in case the alternative was implemented already. ### Changes + - The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: + + - The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + + - SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + + - Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + + - Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. + + While we have protections in place against known attacks, it is expected + that more attacks against SHA-1 will be found by future research. Paired + with the ever-growing capability of hardware, it is only a matter of time + before SHA-1 will be considered broken completely. We want to be prepared + and will thus change the default hash algorithm to "sha256" for newly + initialized repositories. + + Cf. <[email protected]>, + <[email protected]>, + <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>. + ### Removals ## Superseded features that will not be deprecated
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v4 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"
Quoted 3 lines · Patrick Steinhardt
Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
"happened" -> "happen,"
Quoted 7 lines
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
;-) Nevertheless, we probably want some of that in the body text.
Quoted 29 lines
Signed-off-by Patrick Steinhardt <[email protected]>--- Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)Documentation/BreakingChanges.md +16
-0@@ -56,6 +56,33 @@ be changed to or replaced in case the alternative was implemented already. ### Changes + - The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: + + - The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + + - SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + + - Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + + - Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. +
Documentation/BreakingChanges.md be changed to or replaced in case the alternative was implemented already. · line 84
Quoted 10 lines
Documentation/BreakingChanges.md +10
-0+ While we have protections in place against known attacks, it is expected + that more attacks against SHA-1 will be found by future research. Paired + with the ever-growing capability of hardware, it is only a matter of time + before SHA-1 will be considered broken completely. We want to be prepared + and will thus change the default hash algorithm to "sha256" for newly + initialized repositories. + + Cf. <[email protected]>, + <[email protected]>, + <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
We probably need to at least briefly mention external constraints here. Even though in our ideal world, what we say here will force others like GitHub to follow, in the real world that is not always the case. As this particular commit is about establishing the pattern, expected form of each entry, how about adding convention to have a paragraph on "foreseen risks", in addition to the "what we plan to do", and "why we want to go there" we see above?
Documentation/BreakingChanges.md be changed to or replaced in case the alternative was implemented already. · line 88
Quoted 3 lines
Documentation/BreakingChanges.md +0
-0### Removals ## Superseded features that will not be deprecated
Thanks.
PATCH v4 3/4 BreakingChanges: document removal of grafting
In reply to Patrick SteinhardtThe grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.
Follow through with the deprecation and mark grafts for removal in Git 3.0.
--- Documentation/BreakingChanges.md | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/BreakingChanges.md +8 -0
@@ -85,6 +85,14 @@ be changed to or replaced in case the alternative was implemented already. ### Removals + - 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. + + Cf. <[email protected]>. + ## Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
PATCH v4 4/4 BreakingChanges: document that we do not plan to deprecate git-checkout
In reply to Patrick SteinhardtThe git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions.
This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon.
Document that neither of these commands will not go away anytime soon. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands.
--- Documentation/BreakingChanges.md | 12 ++++++++++++ 1 file changed, 12 insertions(+)
Documentation/BreakingChanges.md +12 -0
@@ -99,3 +99,15 @@ 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-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. + + This decision may get revisited in case we ever figure out that there are + almost no users of any of the commands anymore. + + Cf. <[email protected]>, + <[email protected]>, + <[email protected]>.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout
Quoted 6 lines · Patrick Steinhardt
The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions.
Quoted 6 lines
This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon.
Document that neither of these commands will not go away anytime soon.
"neither" -> "none"? It is accepted to use neither to pick among three things these days, but the latter is clearer.
Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout
Quoted 13 lines · Junio C Hamano
Quoted 11 lines · Patrick Steinhardt
The git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions.
This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon.
Quoted 4 lines
Quoted 1 line
Document that neither of these commands will not go away anytime soon.
"neither" -> "none"? It is accepted to use neither to pick among three things these days, but the latter is clearer.
I think 'will not' should lose the 'not' as well:
Document that neither|none of these commands will go away anytime soon.
Alternately, the neither/none question could be resolved by dropping it entirely:
Document that these commands will not go away anytime soon.
I'm not sure that's better; it leaves ambiguity about what "these commands" includes.
Maybe:
Document that all three commands will remain for the foreseeable future.
But after writing all that, I only just noticed this is in the commit message. And while that's important, the more important content of the change itself uses clear language to say all three commands will stay. :)
Signature · 1 line
Todd
Quoted 4 lines · Patrick Steinhardt
You may have noticed that I dropped the "Upcoming" prefix from "UpcomingBreakingChanges.md". This is supposed to reflect the fact that we also have a section that point out features that we are _not_ deprecating. Those aren't upcoming, so I thought a rename makes sense.
I do not mind missing upcoming, but why markdown? The mark-up we as the project chose is AsciiDoc and unless there is a compelling reason to use something else, we should stick to it.
Yes, README.md is not AsciiDoc but that is primarily because what GitHub does on the project page.
Quoted 7 lines · Junio C Hamano
Quoted 4 lines · Patrick Steinhardt
You may have noticed that I dropped the "Upcoming" prefix from "UpcomingBreakingChanges.md". This is supposed to reflect the fact that we also have a section that point out features that we are _not_ deprecating. Those aren't upcoming, so I thought a rename makes sense.
Quoted 6 lines
I do not mind missing upcoming, but why markdown? The mark-up we as the project chose is AsciiDoc and unless there is a compelling reason to use something else, we should stick to it.
Yes, README.md is not AsciiDoc but that is primarily because what GitHub does on the project page.
Oh well, fair enough. I'll convert it to AsciiDoc in the next version, but will wait a bit longer for feedback.
Thanks!
Patrick
v5 cover docs: document upcoming breaking changes
In reply to Patrick SteinhardtHi,
this is another iteration of my patch series that intends to start tracking upcoming breaking changes in Git.
Changes compared to v4:
- Converted the document to use AsciiDoc instead of MarkDown.
- Reword "major release" to "breaking release".
- Note Git 2.0, which is the last major breaking release.
- Note that minor bug fixes that lead to user visible changes in behavior do not require a breaking release.
- Clarify that misdesigned features may be removed without replacement, if necessary.
- Fix double negation in commit message of the last commit.
Thanks!
Patrick
Patrick Steinhardt (4):
docs: introduce document to announce breaking changes
BreakingChanges: document upcoming change from "sha1" to "sha256"
BreakingChanges: document removal of grafting
BreakingChanges: document that we do not plan to deprecate
git-checkout
Documentation/BreakingChanges.txt | 115 ++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 Documentation/BreakingChanges.txt
Range-diff against v4:
1: 993b936348 ! 1: 67cb4de5cb docs: introduce document to announce breaking changes
@@ Commit message
- ## Documentation/BreakingChanges.md (new) ##
+ ## Documentation/BreakingChanges.txt (new) ##
@@
-+# Upcoming breaking changes
++= 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
@@ Documentation/BreakingChanges.md (new)
+required to keep the project aligned with a changing world. These changes fall +into several categories:
+
-+ - Changes to long established defaults.
++* Changes to long established defaults.
++* Concepts that have been replaced with a superior design.
++* Concepts, commands, configuration or options that have been lacking in major ++ ways and that cannot be fixed and which will thus be removed without any ++ replacement.
+
-+ - Concepts that have been replaced with a superior design.
++Explicitly not included in this list are fixes to minor bugs that may cause a ++change in user-visible behavior.
+
-+ - Concepts, commands, configuration or options that have been lacking in major
-+ ways and that cannot be fixed.
++The Git project irregularly releases breaking versions that deliberately break ++backwards compatibility with older versions. This is done to ensure that Git ++remains relevant, safe and maintainable going forward. The release cadence of ++breaking versions is typically measured in multiple years. The last breaking ++releases were:
+
-+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.
++* Git 2.0, released in May 2014.
+
+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
@@ Documentation/BreakingChanges.md (new)
+when the discussion favors deprecation, but also when it rejects a deprecation. +
+Items should have a self-sufficient explanation why we want or do not want to
-+deprecate a given feature. If there are alternatives to the deprecated feature, ++make the described change. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
@@ Documentation/BreakingChanges.md (new)
+revisited from time to time. So do not take items on this list to mean "it is +settled, do not waste our time bringing it up again".
+
-+## Git 3.0
++== Git 3.0
+
+The following subsections document upcoming breaking changes for Git 3.0. There
-+is no planned release date for this major version yet.
++is no planned release date for this breaking version yet.
+
+Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. +
-+### Changes
++=== Changes
+
-+### Removals
++=== Removals
+
-+## Superseded features that will not be deprecated
++== 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.
++those features with newer alternatives.
2: 7c84b2f957 ! 2: b36ffcbaa6 BreakingChanges: document upcoming change from "sha1" to "sha256"
@@ Commit message
- ## Documentation/BreakingChanges.md ##
-@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already.
+ ## Documentation/BreakingChanges.txt ##
+@@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alternative was implemented already.
- ### Changes
+ === Changes
-+ - The default hash function for new repositories will be changed from "sha1"
-+ to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
-+ recommended against in FIPS 140-2 and similar certifications. Furthermore,
-+ there are practical attacks on SHA-1 that weaken its cryptographic properties:
++* The default hash function for new repositories will be changed from "sha1" ++ to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays ++ recommended against in FIPS 140-2 and similar certifications. Furthermore, ++ there are practical attacks on SHA-1 that weaken its cryptographic properties:
+++
++ ** The SHAppening (2015). The first demonstration of a practical attack
++ against SHA-1 with 2^57 operations.
++ ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. ++ ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
++ attacks with 2^68 operations.
++ ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
++ operations.
+++
++While we have protections in place against known attacks, it is expected ++that more attacks against SHA-1 will be found by future research. Paired ++with the ever-growing capability of hardware, it is only a matter of time ++before SHA-1 will be considered broken completely. We want to be prepared ++and will thus change the default hash algorithm to "sha256" for newly ++initialized repositories.
+++
++Cf. <[email protected]>, ++<[email protected]>, ++<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
-+ - The SHAppening (2015). The first demonstration of a practical attack
-+ against SHA-1 with 2^57 operations.
-+
-+ - SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
-+
-+ - Birthday-Near-Collision (2019). This attack allows for chosen prefix
-+ attacks with 2^68 operations.
-+
-+ - Shambles (2020). This attack allows for chosen prefix attacks with 2^63
-+ operations.
-+
-+ While we have protections in place against known attacks, it is expected
-+ that more attacks against SHA-1 will be found by future research. Paired
-+ with the ever-growing capability of hardware, it is only a matter of time
-+ before SHA-1 will be considered broken completely. We want to be prepared
-+ and will thus change the default hash algorithm to "sha256" for newly
-+ initialized repositories.
-+
-+ Cf. <[email protected]>,
-+ <[email protected]>,
-+ <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
-+
- ### Removals
+ === Removals
- ## Superseded features that will not be deprecated
+ == Superseded features that will not be deprecated
3: 91d78490c2 ! 3: 4142e472ac BreakingChanges: document removal of grafting
@@ Commit message
- ## Documentation/BreakingChanges.md ##
-@@ Documentation/BreakingChanges.md: be changed to or replaced in case the alternative was implemented already.
+ ## Documentation/BreakingChanges.txt ##
+@@ Documentation/BreakingChanges.txt: Cf. <[email protected]>,
- ### Removals
+ === Removals
-+ - 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.
++* 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.
+++
++Cf. <[email protected]>.
+
-+ Cf. <[email protected]>.
-+
- ## Superseded features that will not be deprecated
+ == Superseded features that will not be deprecated
Some features have gained newer replacements that aim to improve the design in
4: 40594bda5c ! 4: 9ff94b6f32 BreakingChanges: document that we do not plan to deprecate git-checkout
@@ Commit message
not the case though: the use of that command is still widespread, and it
is not expected that this will change anytime soon.
- Document that neither of these commands will not go away anytime soon.
+ Document that all three commands will remain for the foreseeable future.
This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands.
- ## Documentation/BreakingChanges.md ##
-@@ Documentation/BreakingChanges.md: Some features have gained newer replacements that aim to improve the design in
+ ## Documentation/BreakingChanges.txt ##
+@@ Documentation/BreakingChanges.txt: 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.
+ those features with newer alternatives.
+
-+ - 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.
-+
-+ This decision may get revisited in case we ever figure out that there are
-+ almost no users of any of the commands anymore.
-+
-+ Cf. <[email protected]>,
-+ <[email protected]>,
-+ <[email protected]>.
++* 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.
+++
++This decision may get revisited in case we ever figure out that there are
++almost no users of any of the commands anymore.
+++
++Cf. <[email protected]>,
++<[email protected]>,
++<[email protected]>.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
PATCH v5 1/4 docs: introduce document to announce breaking changes
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 tracks such 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.
--- Documentation/BreakingChanges.txt | 71 +++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 Documentation/BreakingChanges.txt
Documentation/BreakingChanges.txt new file +71 -0
@@ -0,0 +1,71 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of +breaking versions is typically measured in multiple years. The last breaking +releases were: + +* Git 2.0, released in May 2014. + +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. + +Items should have a self-sufficient explanation why we want or do not want to +make the described change. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. An earlier decision to deprecate or change something may need to be +revisited from time to time. So do not take items on this list to mean "it is +settled, do not waste our time bringing it up again". + +== Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +=== Removals + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes
Hi Patrick
Thanks for working on this, I've left a couple of small comments below but I'm not sure they're worth a re-roll on their own. All of the patches look sensible to me.
Documentation/BreakingChanges.txt
Quoted 7 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +7
-0+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. + +Items should have a self-sufficient explanation why we want or do not want to +make the described change.
"self-sufficient explanation" strikes me as a slightly add turn of phrase, maybe something like
Items should have a clear summary of the reasons why we do or do not want to make the described change that can be easily understood without having to read the mailing list discussions.
Quoted 7 lines
If there are alternatives to the changed feature,
Documentation/BreakingChanges.txt new file +6
-0+those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via +
Documentation/BreakingChanges.txt line 51
Quoted 10 lines
Documentation/BreakingChanges.txt new file +10
-0+ https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. An earlier decision to deprecate or change something may need to be +revisited from time to time. So do not take items on this list to mean "it is +settled, do not waste our time bringing it up again".
We could possibly add "If circumstances change" to the start of the second sentence to discourage repeated discussions of the same issue when someone has a bee in their bonnet about a particular change but I think we can probably handle that on the mailing list without any changes here.
Best Wishes
Phillip
Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes
In reply to Patrick SteinhardtDocumentation/BreakingChanges.txt line 32
Quoted 4 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +4
-0+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.
"next major Git release" -> "future breaking release(s)". I do not know offhand if we want to plan for longer timespans that may cover multiple breaking releases, hence (s) in parentheses.
"documente" -> "document".
Documentation/BreakingChanges.txt line 51
Quoted 4 lines
Documentation/BreakingChanges.txt new file +4
-0+This is a living document as the environment surrounding the project changes +over time. An earlier decision to deprecate or change something may need to be +revisited from time to time. So do not take items on this list to mean "it is +settled, do not waste our time bringing it up again".
But you are expected to be aware of past discussion, and if you are not bringing anything new to the table, you are wasting our time. Note that pointing out an old rationale no longer applies to today's world still counts as a new datapoint in a renewed discussion.
Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes
Quoted 10 lines · Junio C Hamano
Documentation/BreakingChanges.txt line 51
Quoted 4 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +4
-0+This is a living document as the environment surrounding the project changes +over time. An earlier decision to deprecate or change something may need to be +revisited from time to time. So do not take items on this list to mean "it is +settled, do not waste our time bringing it up again".But you are expected to be aware of past discussion, and if you are not bringing anything new to the table, you are wasting our time. Note that pointing out an old rationale no longer applies to today's world still counts as a new datapoint in a renewed discussion.
Yeah. I like Phillip's proposal here, which adds "If circumstances change" to the second sentence to clarify that we do not want to rehash the same arguments.
Patrick
PATCH v5 2/4 BreakingChanges: document upcoming change from "sha1" to "sha256"
In reply to Patrick SteinhardtStarting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely.
Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
--- Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)
Documentation/BreakingChanges.txt +24 -0
@@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>. + === Removals == Superseded features that will not be deprecated
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"
Quoted 47 lines · Patrick Steinhardt
Starting with
8e42eb0e9a(doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely.Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
Signed-off-by Patrick Steinhardt <[email protected]>--- Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)Documentation/BreakingChanges.txt +13
-0@@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++
Documentation/BreakingChanges.txt be changed to or replaced in case the alternative was implemented already. · line 86
Quoted 10 lines
Documentation/BreakingChanges.txt +10
-0+While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
A few things we should probably list are:
- Even if you can locally use SHA-256 in your project and push/fetch the history around, public forges may not be ready.
- The strategy to migrate existing SHA-1 project to SHA-256 without going through a flag day change has been designed but not implemented or deployed.
- This is only about the change of the default; we currently have no plan to drop support for SHA-1 repositories.
IMHO, we would want each and every item in this document to mention the risk factors that may prevent us from going forward even if we wanted to, and the first item above is an example.
Thanks.
Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"
Quoted 69 lines · Junio C Hamano
Quoted 47 lines · Patrick Steinhardt
Starting with
8e42eb0e9a(doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely.Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
Signed-off-by Patrick Steinhardt <[email protected]>--- Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)Documentation/BreakingChanges.txt +13
-0@@ -61,6 +61,30 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++Documentation/BreakingChanges.txt be changed to or replaced in case the alternative was implemented already. · line 86
Quoted 10 lines
Documentation/BreakingChanges.txt +10
-0+While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.A few things we should probably list are:
- Even if you can locally use SHA-256 in your project and push/fetch the history around, public forges may not be ready.
- The strategy to migrate existing SHA-1 project to SHA-256 without going through a flag day change has been designed but not implemented or deployed.
Quoted 8 lines
- This is only about the change of the default; we currently have no plan to drop support for SHA-1 repositories.
IMHO, we would want each and every item in this document to mention the risk factors that may prevent us from going forward even if we wanted to, and the first item above is an example.
Thanks.
I agree that explicitly mentioning (1) and (3) is sensible. Is the second one important though given that this is about the default when creating _new_ repositories? I don't think interop code is a requirement to make "sha256" the default, is it?
Patrick
Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"
Quoted 4 lines · Patrick Steinhardt
I agree that explicitly mentioning (1) and (3) is sensible. Is the second one important though given that this is about the default when creating _new_ repositories? I don't think interop code is a requirement to make "sha256" the default, is it?
Let's drop (2) from the list, as I do not think there ever was a concensus on it, and also for the sake of brevity.
Thanks.
PATCH v5 3/4 BreakingChanges: document removal of grafting
In reply to Patrick SteinhardtThe grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.
Follow through with the deprecation and mark grafts for removal in Git 3.0.
--- Documentation/BreakingChanges.txt | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/BreakingChanges.txt +8 -0
@@ -87,6 +87,14 @@ Cf. <[email protected]>, === Removals +* 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. ++ +Cf. <[email protected]>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v5 3/4] BreakingChanges: document removal of grafting
Quoted 18 lines · Patrick Steinhardt
The grafting mechanism for objects has been deprecated in
e650d0643b(docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.Follow through with the deprecation and mark grafts for removal in Git 3.0.
Signed-off-by Patrick Steinhardt <[email protected]>--- Documentation/BreakingChanges.txt | 8 ++++++++ 1 file changed, 8 insertions(+)Documentation/BreakingChanges.txt +0
-0
Documentation/BreakingChanges.txt Cf. <[email protected]>, · line 92
Quoted 6 lines
Documentation/BreakingChanges.txt +3
-0@@ -87,6 +87,14 @@ Cf. <[email protected]>, === Removals +* 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.
The replace refs will be transferred, but the graft is a purely local mechanism and there is no way (other than by human intervention) to communicate the graft entries across repositories.
That is the primary thing we should list as the reason why the replace mechanism is a better alternative over the graft mechanism.
Quoted 8 lines
Documentation/BreakingChanges.txt +5
-0+ They have been outdated since e650d0643b (docs: mark info/grafts as outdated, + 2014-03-05) and will be removed. ++ +Cf. <[email protected]>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in
PATCH v5 4/4 BreakingChanges: document that we do not plan to deprecate git-checkout
In reply to Patrick SteinhardtThe git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions.
This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon.
Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands.
--- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+)
Documentation/BreakingChanges.txt +12 -0
@@ -101,3 +101,15 @@ Some features have gained newer replacements that aim to improve the design in certain ways. The fact that there is a replacement does not automatically mean that the old way of doing things will eventually be removed. This section tracks those features with newer alternatives. + +* 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. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. <[email protected]>, +<[email protected]>, +<[email protected]>.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout
Documentation/BreakingChanges.txt Some features have gained newer replacements that aim to improve the design in · line 108
Quoted 5 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt +5
-0+ +* 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.
"As a replacement" is probably a bit different from the truth [*], but I suspect that the reason why they were introduced no longer has much relevance. How about
The features git-checkout(1) offers are covered by the pair of commands git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still widespread, and it is not expected that this will change anytime soon.
or something (borrowing from your proposed log message)?
[Footnote]
* If we were to mention the history behind the introduction, we'd end up saying: as an experiment, we introduced the pair of commands that do different half of the original command to see if they can replace the original.
The decision to keep the original would lead to implication that this was a failed experiment, which makes people (unnecessarily) wonder if the failed experiment should be removed. I am trying to avoid such unnecessary implication here.
Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout
Quoted 12 lines · Junio C Hamano
Documentation/BreakingChanges.txt Some features have gained newer replacements that aim to improve the design in · line 108
Quoted 5 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt +5
-0+ +* 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."As a replacement" is probably a bit different from the truth [*], but I suspect that the reason why they were introduced no longer has much relevance. How about
Quoted 6 lines
The features git-checkout(1) offers are covered by the pair of commands git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still widespread, and it is not expected that this will change anytime soon.
or something (borrowing from your proposed log message)?
Fair enough, let's add it like this. Thanks!
Patrick
v6 cover docs: document upcoming breaking changes
In reply to Patrick SteinhardtHi,
another day, another version of this patch series that aims to give a framework for documenting upcoming breaking changes in Git.
Changes compared to v5:
- Note that Git 1.6 was a breaking release, despite the fact that its major version wasn't bumped.
- Several smallish rewordings.
- Note that items on the lists should only be discussed anew when circumstances have changed.
- Add some conditions to the move to "sha256". Also, note that we do not plan to deprecate "sha1".
- Note that replacement refs are also superior over grafts because they can be carried across repos.
Thanks!
Patrick
Patrick Steinhardt (4):
docs: introduce document to announce breaking changes
BreakingChanges: document upcoming change from "sha1" to "sha256"
BreakingChanges: document removal of grafting
BreakingChanges: document that we do not plan to deprecate
git-checkout
Documentation/BreakingChanges.txt | 128 ++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 Documentation/BreakingChanges.txt
Range-diff against v5:
1: 67cb4de5cb ! 1: a260bbf281 docs: introduce document to announce breaking changes
@@ Documentation/BreakingChanges.txt (new)
+breaking versions is typically measured in multiple years. The last breaking +releases were:
+
++* Git 1.6, released in August 2008. In retrospect, this release should likely ++ have bumped the major version.
+* Git 2.0, released in May 2014.
+
-+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 ++The intent of this document is to track upcoming deprecations for future ++breaking releases. Furthermore, this document also tracks what will _not_ be ++deprecated. This is done such that the outcome of discussions document both
+when the discussion favors deprecation, but also when it rejects a deprecation. +
-+Items should have a self-sufficient explanation why we want or do not want to -+make the described change. If there are alternatives to the changed feature, ++Items should have a clear summary of the reasons why we do or do not want to ++make the described change that can be easily understood without having to read ++the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
@@ Documentation/BreakingChanges.txt (new)
+described item back then.
+
+This is a living document as the environment surrounding the project changes
-+over time. An earlier decision to deprecate or change something may need to be -+revisited from time to time. So do not take items on this list to mean "it is -+settled, do not waste our time bringing it up again".
++over time. If circumstances change, an earlier decision to deprecate or change ++something may need to be revisited from time to time. So do not take items on ++this list to mean "it is settled, do not waste our time bringing it up again".
+
+== Git 3.0
+
2: b36ffcbaa6 ! 2: f7c6a66f71 BreakingChanges: document upcoming change from "sha1" to "sha256"
@@ Documentation/BreakingChanges.txt: be changed to or replaced in case the alterna
+and will thus change the default hash algorithm to "sha256" for newly +initialized repositories.
++
++An important requirement for this change is that the ecosystem is ready to ++support the "sha256" object format. This includes popular Git libraries, ++applications and forges.
+++
++There is no plan to deprecate the "sha1" object format at this point in time.
+++
+Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
3: 4142e472ac ! 3: b25b91a5e7 BreakingChanges: document removal of grafting
@@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom
=== Removals
+* 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.
++ Grafts are inferior to replacement refs:
+++
++ ** Grafts are a local-only mechanism and cannot be shared across reositories. ++ ** Grafts can lead to hard-to-diagnose problems when transferring objects
++ between repositories.
+++
++The grafting mechanism has been marked as outdated since e650d0643b (docs: mark ++info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <[email protected]>.
+
4: 9ff94b6f32 ! 4: 4fafccc3b9 BreakingChanges: document that we do not plan to deprecate git-checkout
@@ Documentation/BreakingChanges.txt: Some features have gained newer replacements
that the old way of doing things will eventually be removed. This section tracks those features with newer alternatives.
+
-+* 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.
++* The features git-checkout(1) offers are covered by the pair of commands
++ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still ++ widespread, and it is not expected that this will change anytime soon, all
++ three commands will stay.
++
+This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
PATCH v6 1/4 docs: introduce document to announce breaking changes
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 tracks such 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.
--- Documentation/BreakingChanges.txt | 74 +++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 Documentation/BreakingChanges.txt
Documentation/BreakingChanges.txt new file +74 -0
@@ -0,0 +1,74 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of +breaking versions is typically measured in multiple years. The last breaking +releases were: + +* Git 1.6, released in August 2008. In retrospect, this release should likely + have bumped the major version. +* Git 2.0, released in May 2014. + +The intent of this document is to track upcoming deprecations for future +breaking releases. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions document both +when the discussion favors deprecation, but also when it rejects a deprecation. + +Items should have a clear summary of the reasons why we do or do not want to +make the described change that can be easily understood without having to read +the mailing list discussions. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. If circumstances change, an earlier decision to deprecate or change +something may need to be revisited from time to time. So do not take items on +this list to mean "it is settled, do not waste our time bringing it up again". + +== Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +=== Removals + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes
Documentation/BreakingChanges.txt line 28
Quoted 2 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +2
-0+* Git 1.6, released in August 2008. In retrospect, this release should likely + have bumped the major version.
No need to reroll just for this alone, but back then, a non-zero third component did not mean they are maintenance releases (e.g., v1.5.3.3 was the third maintenance update for the v1.5.3 series) and v1.6.0 _was_ a departure, a breaking change from the v1.5.x series.
It is more recent tradition that we only use three numbers. I'd strike the whole "In retrospect" comment if I were writing this.
Documentation/BreakingChanges.txt line 48
Quoted 2 lines
Documentation/BreakingChanges.txt new file +2
-0+to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the
"concensus" -> "consensus".
Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes
Quoted 5 lines · Junio C Hamano
Documentation/BreakingChanges.txt line 28
Quoted 2 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +2
-0+* Git 1.6, released in August 2008. In retrospect, this release should likely + have bumped the major version.
Quoted 7 lines
No need to reroll just for this alone, but back then, a non-zero third component did not mean they are maintenance releases (e.g., v1.5.3.3 was the third maintenance update for the v1.5.3 series) and v1.6.0 _was_ a departure, a breaking change from the v1.5.x series.
It is more recent tradition that we only use three numbers. I'd strike the whole "In retrospect" comment if I were writing this.
The reason why I included it is that I didn't want to create the impression that breaking releases may also happen when bumping the second version component. It did happen with v1.6.0, but in the future I think we'd want to always bump the first component on such releases, do we?
Patrick
Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes
Quoted 11 lines · Patrick Steinhardt
Quoted 10 lines · Junio C Hamano
Documentation/BreakingChanges.txt line 28
Quoted 2 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +2
-0+* Git 1.6, released in August 2008. In retrospect, this release should likely + have bumped the major version.No need to reroll just for this alone, but back then, a non-zero third component did not mean they are maintenance releases (e.g., v1.5.3.3 was the third maintenance update for the v1.5.3 series) and v1.6.0 _was_ a departure, a breaking change from the v1.5.x series.
Quoted 8 lines
Quoted 2 lines
It is more recent tradition that we only use three numbers. I'd strike the whole "In retrospect" comment if I were writing this.
The reason why I included it is that I didn't want to create the impression that breaking releases may also happen when bumping the second version component. It did happen with v1.6.0, but in the future I think we'd want to always bump the first component on such releases, do we?
But "in retrospect we should have called it 2.0" is patently false; switching from 3-tuple version numbers to 2-tuple version numbers has nothing to do with introducing breaking changes.
It needs to be rewritten in such a way that the readers would understand the following:
Git 1.6.0, released in August 2008.
These days, we use two-tuple numbers for feature releases (e.g. Git 2.45 and Git 2.45.0 with 0 as the third number are the same things) and maintenance releases have non-zero third number, so instead of going from Git 2.56 to Git 2.57, we would jump to Git 3.0 if we decide to make Git 2.56 the last feature release of the Git 2.0 series.
With the versioning scheme used back then, going from Git 1.5.6 to Git 1.5.7 would have been equivalent move to Git 2.56 to Git 2.57, i.e. incremental and non-breaking feature release progression. Deciding to go from Git 1.5.6 to Git 1.6.0, instead of going to Git 1.5.7, was akin to moving to Git 3.0, signalling a breaking change, in today's versioning scheme. We were reserving the increment to the first digit for even larger breaking changes until Git 2.0 happened.
Between Git 1.6.6 and Git 1.7.0, there were breaking changes. The same is true for the transtions between Git 1.7.12 and Git 1.8.0, between Git 1.4.4 and Git 1.5.0, and so on. They weren't as huge and controversial as the jump to Git 1.6.0, though.
Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes
Quoted 3 lines · Junio C Hamano
But "in retrospect we should have called it 2.0" is patently false; switching from 3-tuple version numbers to 2-tuple version numbers has nothing to do with introducing breaking changes.
I tried to make it concise, and came up with the following on top of tweaked [v6 1/4] on 'seen'.
Documentation/BreakingChanges.txt | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-)
Documentation/BreakingChanges.txt +10 -3
@@ -21,12 +21,19 @@ change in user-visible behavior. The Git project irregularly releases breaking versions that deliberately break backwards compatibility with older versions. This is done to ensure that Git remains relevant, safe and maintainable going forward. The release cadence of -breaking versions is typically measured in multiple years. The last breaking -releases were: +breaking versions is typically measured in multiple years. We had major +breaking releases like these in the past: -* Git 1.6, released in August 2008. +* Git 1.6.0, released in August 2008. * Git 2.0, released in May 2014. +We use <major>.<minor> release numbers these days, starting from Git +2.0, for feature releases, our plan is to increment <major> in the +release number when we make the next breaking release (before Git 2.0, +the release numbers were 1.<major>.<minor> with the intention to increment +<major> for "usual" breaking releases, reserving the jump to Git 2.0 for +really large backward-compatibility breaking changes). + The intent of this document is to track upcoming deprecations for future breaking releases. Furthermore, this document also tracks what will _not_ be deprecated. This is done such that the outcome of discussions document both
Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes
Quoted 8 lines · Junio C Hamano
Quoted 3 lines · Junio C Hamano
But "in retrospect we should have called it 2.0" is patently false; switching from 3-tuple version numbers to 2-tuple version numbers has nothing to do with introducing breaking changes.
I tried to make it concise, and came up with the following on top of tweaked [v6 1/4] on 'seen'.
That is a good addition indeed and nicely explains what was going on back then, and how we handle it today. Thanks!
Patrick
PATCH v6 2/4 BreakingChanges: document upcoming change from "sha1" to "sha256"
In reply to Patrick SteinhardtStarting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely.
Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
--- Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)
Documentation/BreakingChanges.txt +30 -0
@@ -64,6 +64,36 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +An important requirement for this change is that the ecosystem is ready to +support the "sha256" object format. This includes popular Git libraries, +applications and forges. ++ +There is no plan to deprecate the "sha1" object format at this point in time. ++ +Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>. + === Removals == Superseded features that will not be deprecated
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
PATCH v6 3/4 BreakingChanges: document removal of grafting
In reply to Patrick SteinhardtThe grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.
Follow through with the deprecation and mark grafts for removal in Git 3.0.
--- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+)
Documentation/BreakingChanges.txt +12 -0
@@ -96,6 +96,18 @@ Cf. <[email protected]>, === Removals +* Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs: ++ + ** Grafts are a local-only mechanism and cannot be shared across reositories. + ** Grafts can lead to hard-to-diagnose problems when transferring objects + between repositories. ++ +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark +info/grafts as outdated, 2014-03-05) and will be removed. ++ +Cf. <[email protected]>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Re: [PATCH v6 3/4] BreakingChanges: document removal of grafting
Quoted 18 lines · Patrick Steinhardt
The grafting mechanism for objects has been deprecated in
e650d0643b(docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.Follow through with the deprecation and mark grafts for removal in Git 3.0.
Signed-off-by Patrick Steinhardt <[email protected]>--- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+)Documentation/BreakingChanges.txt +0
-0
Documentation/BreakingChanges.txt Cf. <[email protected]>, · line 102
Quoted 7 lines
Documentation/BreakingChanges.txt +4
-0@@ -96,6 +96,18 @@ Cf. <[email protected]>, === Removals +* Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs: ++ + ** Grafts are a local-only mechanism and cannot be shared across reositories.
"reositories" -> "repositories".
Quoted 11 lines
Documentation/BreakingChanges.txt +8
-0+ ** Grafts can lead to hard-to-diagnose problems when transferring objects + between repositories. ++ +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark +info/grafts as outdated, 2014-03-05) and will be removed. ++ +Cf. <[email protected]>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in
PATCH v6 4/4 BreakingChanges: document that we do not plan to deprecate git-checkout
In reply to Patrick SteinhardtThe git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions.
This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon.
Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands.
--- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+)
Documentation/BreakingChanges.txt +12 -0
@@ -114,3 +114,15 @@ Some features have gained newer replacements that aim to improve the design in certain ways. The fact that there is a replacement does not automatically mean that the old way of doing things will eventually be removed. This section tracks those features with newer alternatives. + +* The features git-checkout(1) offers are covered by the pair of commands + git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still + widespread, and it is not expected that this will change anytime soon, all + three commands will stay. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. <[email protected]>, +<[email protected]>, +<[email protected]>.
Signature · 1 line
2.45.1.410.g58bac47f8e.dirty
Hi Patrick
Quoted 12 lines · Patrick Steinhardt
Hi,
another day, another version of this patch series that aims to give a framework for documenting upcoming breaking changes in Git.
Changes compared to v5:
- Note that Git 1.6 was a breaking release, despite the fact that its major version wasn't bumped.
- Several smallish rewordings.
Quoted 8 lines
- Note that items on the lists should only be discussed anew when circumstances have changed.
- Add some conditions to the move to "sha256". Also, note that we do not plan to deprecate "sha1".
- Note that replacement refs are also superior over grafts because they can be carried across repos.
This version looks good to me
Thanks for writing this document
Phillip
Quoted 104 lines
Thanks!
Patrick
Patrick Steinhardt (4):
docs: introduce document to announce breaking changes
BreakingChanges: document upcoming change from "sha1" to "sha256"
BreakingChanges: document removal of grafting
BreakingChanges: document that we do not plan to deprecate
git-checkoutDocumentation/BreakingChanges.txt | 128 ++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+)create mode 100644
Documentation/BreakingChanges.txtRange-diff against v5:
1:67cb4de5cb! 1:a260bbf281docs: introduce document to announce breaking changes
@@Documentation/BreakingChanges.txt(new)
+breaking versions is typically measured in multiple years. The last breaking +releases were:
+
++* Git 1.6, released in August 2008. In retrospect, this release should likely ++ have bumped the major version.
+* Git 2.0, released in May 2014.
+
-+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 ++The intent of this document is to track upcoming deprecations for future ++breaking releases. Furthermore, this document also tracks what will _not_ be ++deprecated. This is done such that the outcome of discussions document both
+when the discussion favors deprecation, but also when it rejects a deprecation. +
-+Items should have a self-sufficient explanation why we want or do not want to -+make the described change. If there are alternatives to the changed feature, ++Items should have a clear summary of the reasons why we do or do not want to ++make the described change that can be easily understood without having to read ++the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
@@Documentation/BreakingChanges.txt(new)
+described item back then.
+
+This is a living document as the environment surrounding the project changes
-+over time. An earlier decision to deprecate or change something may need to be -+revisited from time to time. So do not take items on this list to mean "it is -+settled, do not waste our time bringing it up again".
++over time. If circumstances change, an earlier decision to deprecate or change ++something may need to be revisited from time to time. So do not take items on ++this list to mean "it is settled, do not waste our time bringing it up again".
+
+== Git 3.0
+
2:b36ffcbaa6! 2:f7c6a66f71BreakingChanges: document upcoming change from "sha1" to "sha256"
@@Documentation/BreakingChanges.txt: be changed to or replaced in case the alterna
+and will thus change the default hash algorithm to "sha256" for newly +initialized repositories.
++
++An important requirement for this change is that the ecosystem is ready to ++support the "sha256" object format. This includes popular Git libraries, ++applications and forges.
+++
++There is no plan to deprecate the "sha1" object format at this point in time.
+++
+Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
3:4142e472ac! 3:b25b91a5e7BreakingChanges: document removal of grafting
@@Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom
=== Removals+* 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 sincee650d0643b(docs: mark info/grafts as outdated, -+ 2014-03-05) and will be removed.
++ Grafts are inferior to replacement refs:
+++
++ ** Grafts are a local-only mechanism and cannot be shared across reositories. ++ ** Grafts can lead to hard-to-diagnose problems when transferring objects
++ between repositories.
+++
++The grafting mechanism has been marked as outdated sincee650d0643b(docs: mark ++info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <[email protected]>.
+
4:9ff94b6f32! 4:4fafccc3b9BreakingChanges: document that we do not plan to deprecate git-checkout
@@Documentation/BreakingChanges.txt: Some features have gained newer replacements
that the old way of doing things will eventually be removed. This section tracks those features with newer alternatives.
+
-+* 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.
++* The features git-checkout(1) offers are covered by the pair of commands
++ git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still ++ widespread, and it is not expected that this will change anytime soon, all
++ three commands will stay.
++
+This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore.
Quoted 21 lines · Phillip Wood
Hi Patrick
Quoted 9 lines · Patrick Steinhardt
Hi,
another day, another version of this patch series that aims to give a
framework for documenting upcoming breaking changes in Git. Changes compared to v5:
- Note that Git 1.6 was a breaking release, despite the fact that
its
major version wasn't bumped.
- Several smallish rewordings.Quoted 8 lines
- Note that items on the lists should only be discussed anew when circumstances have changed.
- Add some conditions to the move to "sha256". Also, note that we
do
not plan to deprecate "sha1".
- Note that replacement refs are also superior over grafts
because
they can be carried across repos.
Quoted 3 lines
This version looks good to me
Thanks for writing this document
Yup, aside from two typos and a misstatement I did not spot anything that need correction. Will queue.
Thanks.
Quoted 23 lines · Junio C Hamano
Quoted 21 lines · Phillip Wood
Hi Patrick
Quoted 17 lines · Patrick Steinhardt
Hi,
another day, another version of this patch series that aims to give a
framework for documenting upcoming breaking changes in Git. Changes compared to v5:
- Note that Git 1.6 was a breaking release, despite the fact that
its
major version wasn't bumped.
- Several smallish rewordings.
- Note that items on the lists should only be discussed anew when circumstances have changed.
- Add some conditions to the move to "sha256". Also, note that we
do
not plan to deprecate "sha1".
- Note that replacement refs are also superior over grafts
because
they can be carried across repos.
Quoted 8 lines
Quoted 3 lines
This version looks good to me
Thanks for writing this document
Yup, aside from two typos and a misstatement I did not spot anything that need correction. Will queue.
Thanks.
Thanks to both of you!
Patrick
v7 cover docs: document upcoming breaking changes
In reply to Patrick SteinhardtHi,
this is another and hopefully the last version of this patch series that starts to document upcoming breaking changes in Git.
Changes compared to v6:
- Fix a typo in the third commit.
- Document the version number schema and when we bump which part of our version, including historical 1.x days.
- Drop the wrong remark that Git 1.6 should've been 2.0.
Thanks!
Patrick
Patrick Steinhardt (4):
docs: introduce document to announce breaking changes
BreakingChanges: document upcoming change from "sha1" to "sha256"
BreakingChanges: document removal of grafting
BreakingChanges: document that we do not plan to deprecate
git-checkout
Documentation/BreakingChanges.txt | 135 ++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 Documentation/BreakingChanges.txt
Range-diff against v6:
1: a260bbf281 ! 1: 6348f27b59 docs: introduce document to announce breaking changes
@@ Documentation/BreakingChanges.txt (new)
+The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of
-+breaking versions is typically measured in multiple years. The last breaking -+releases were:
++breaking versions is typically measured in multiple years. We had the following ++major breaking releases in the past:
+
-+* Git 1.6, released in August 2008. In retrospect, this release should likely -+ have bumped the major version.
++* Git 1.6.0, released in August 2008.
+* Git 2.0, released in May 2014.
+
++We use <major>.<minor> release numbers these days, starting from Git 2.0. For ++future releases, our plan is to increment <major> in the release number when we ++make the next breaking release. Before Git 2.0, the release numbers were ++1.<major>.<minor> with the intention to increment <major> for "usual" breaking ++releases, reserving the jump to Git 2.0 for really large backward-compatibility ++breaking changes.
++
+The intent of this document is to track upcoming deprecations for future +breaking releases. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions document both
2: f7c6a66f71 = 2: d0ec38a25a BreakingChanges: document upcoming change from "sha1" to "sha256" 3: b25b91a5e7 ! 3: deee0bbf66 BreakingChanges: document removal of grafting
@@ Documentation/BreakingChanges.txt: Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zom
+* Support for grafting commits has long been superseded by git-replace(1).
+ Grafts are inferior to replacement refs:
++
-+ ** Grafts are a local-only mechanism and cannot be shared across reositories. ++ ** Grafts are a local-only mechanism and cannot be shared across
++ repositories.
+ ** Grafts can lead to hard-to-diagnose problems when transferring objects
+ between repositories.
++
4: 4fafccc3b9 = 4: 25b20bb0ca BreakingChanges: document that we do not plan to deprecate git-checkout
Signature · 1 line
2.45.2.457.g8d94cfb545.dirty
PATCH v7 1/4 docs: introduce document to announce breaking changes
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 tracks such 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.
--- Documentation/BreakingChanges.txt | 80 +++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 Documentation/BreakingChanges.txt
Documentation/BreakingChanges.txt new file +80 -0
@@ -0,0 +1,80 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of +breaking versions is typically measured in multiple years. We had the following +major breaking releases in the past: + +* Git 1.6.0, released in August 2008. +* Git 2.0, released in May 2014. + +We use <major>.<minor> release numbers these days, starting from Git 2.0. For +future releases, our plan is to increment <major> in the release number when we +make the next breaking release. Before Git 2.0, the release numbers were +1.<major>.<minor> with the intention to increment <major> for "usual" breaking +releases, reserving the jump to Git 2.0 for really large backward-compatibility +breaking changes. + +The intent of this document is to track upcoming deprecations for future +breaking releases. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions document both +when the discussion favors deprecation, but also when it rejects a deprecation. + +Items should have a clear summary of the reasons why we do or do not want to +make the described change that can be easily understood without having to read +the mailing list discussions. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. If circumstances change, an earlier decision to deprecate or change +something may need to be revisited from time to time. So do not take items on +this list to mean "it is settled, do not waste our time bringing it up again". + +== Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +=== Removals + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives.
Signature · 1 line
2.45.2.457.g8d94cfb545.dirty
Re: [PATCH v7 1/4] docs: introduce document to announce breaking changes
Documentation/BreakingChanges.txt line 55
Quoted 3 lines · Patrick Steinhardt
Documentation/BreakingChanges.txt new file +3
-0+to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached concensus on the +described item back then.
Sorry if I typofixed silently and locally without mentioning in my reviews for the earlier cycles, but I noticed that the fix "concensus" -> "consensus" I had in 'seen' is gone from this version.
I'll locally amend.
Thanks.
PATCH v7 2/4 BreakingChanges: document upcoming change from "sha1" to "sha256"
In reply to Patrick SteinhardtStarting with 8e42eb0e9a (doc: sha256 is no longer experimental, 2023-07-31), the "sha256" object format is no longer considered to be experimental. Furthermore, the SHA-1 hash function is actively recommended against by for example NIST and FIPS 140-2, and attacks against it are becoming more practical both due to new weaknesses (SHAppening, SHAttered, Shambles) and due to the ever-increasing computing power. It is only a matter of time before it can be considered to be broken completely.
Let's plan for this event by being active instead of waiting for it to happend and announce that the default object format is going to change from "sha1" to "sha256" with Git 3.0.
All major Git implementations (libgit2, JGit, go-git) support the "sha256" object format and are thus prepared for this change. The most important missing piece in the puzzle is support in forges. But while GitLab recently gained experimental support for the "sha256" object format though, to the best of my knowledge GitHub doesn't support it yet. Ideally, announcing this upcoming change will encourage forges to start building that support.
--- Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)
Documentation/BreakingChanges.txt +30 -0
@@ -70,6 +70,36 @@ be changed to or replaced in case the alternative was implemented already. === Changes +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +An important requirement for this change is that the ecosystem is ready to +support the "sha256" object format. This includes popular Git libraries, +applications and forges. ++ +There is no plan to deprecate the "sha1" object format at this point in time. ++ +Cf. <[email protected]>, +<[email protected]>, +<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>. + === Removals == Superseded features that will not be deprecated
Signature · 1 line
2.45.2.457.g8d94cfb545.dirty
PATCH v7 3/4 BreakingChanges: document removal of grafting
In reply to Patrick SteinhardtThe grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.
Follow through with the deprecation and mark grafts for removal in Git 3.0.
--- Documentation/BreakingChanges.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+)
Documentation/BreakingChanges.txt +13 -0
@@ -102,6 +102,19 @@ Cf. <[email protected]>, === Removals +* Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs: ++ + ** Grafts are a local-only mechanism and cannot be shared across + repositories. + ** Grafts can lead to hard-to-diagnose problems when transferring objects + between repositories. ++ +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark +info/grafts as outdated, 2014-03-05) and will be removed. ++ +Cf. <[email protected]>. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in
Signature · 1 line
2.45.2.457.g8d94cfb545.dirty
PATCH v7 4/4 BreakingChanges: document that we do not plan to deprecate git-checkout
In reply to Patrick SteinhardtThe git-checkout(1) command is seen by many as hard to understand because it connects two somewhat unrelated features: switching between branches and restoring worktree files from arbitrary revisions. In 2019, we thus implemented two new commands git-switch(1) and git-restore(1) to split out these separate concerns into standalone functions.
This "replacement" of git-checkout(1) has repeatedly triggered concerns for our userbase that git-checkout(1) will eventually go away. This is not the case though: the use of that command is still widespread, and it is not expected that this will change anytime soon.
Document that all three commands will remain for the foreseeable future. This decision may be revisited in case we ever figure out that most everyone has given up on any of the commands.
--- Documentation/BreakingChanges.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+)
Documentation/BreakingChanges.txt +12 -0
@@ -121,3 +121,15 @@ Some features have gained newer replacements that aim to improve the design in certain ways. The fact that there is a replacement does not automatically mean that the old way of doing things will eventually be removed. This section tracks those features with newer alternatives. + +* The features git-checkout(1) offers are covered by the pair of commands + git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still + widespread, and it is not expected that this will change anytime soon, all + three commands will stay. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. <[email protected]>, +<[email protected]>, +<[email protected]>.
Signature · 1 line
2.45.2.457.g8d94cfb545.dirty
Commands using -h as an option don't work consistently
Because of a bug in parse-options.c, any command that has a '-h' option will sometimes display the usage page instead of executing. For example, ls-remote has two options:
-t, --[no-]tags limit to tags
-h, --[no-]heads limit to heads
git ls-remote --heads #works
git ls-remote --tags #works
git ls-remote -t #works
git ls-remote -t -h #works
git ls-remote -h #shows the help page
This is because of these lines in parse-options.c:
/* lone -h asks for help */
if (internal_help && ctx->total == 1 && !strcmp(arg + 1, "h")) goto show_usage;
This is being executed before it looks to see if there actually is a -h option. So if a program has a -h option, and that's the ONLY parameter you pass, the usage page gets displayed incorrectly. This appears to affect ls-remote, show-ref (it's not documented, but show-ref accepts -h as an alias for --heads) and grep.
I fixed this by moving the lone -h check lower down, which fixed everything. Except now lots and lots of tests are failing because many of them assume you can always pass -h to get the usage page, and now you can't for some commands. I don't think this actually breaks grep because you need to pass at least one more option other than -h to use it, but tests for it are still failing after fixing this bug because it's now showing the man page instead of the expected short usage page because it's erroring out at a different place.
The specific tests that are failing are t1502-rev-parse-parseopt.sh, t0012-help.sh and t0450-txt-doc-vs-help.sh all of which are trying to use -h on commands that have repurposed it.
The options I see:
1) Fix -h handling and add ignores and fixes where possible to the failing tests and try to not use -h as an option for anything new.
2) Change -h to -H or something, but this breaks backwards compatibility
3) Fix it so that -h works if a command uses it, and additionally make a new global option -? or --usage or something that always shows the usage page and change tests to use that, while leaving -h sometimes showing usage and sometimes executing the option to preserve as much backward compatibility as possible.
I'm happy to do the work and submit it, but this is looking more like a policy decision than just a bug now.
-- Kevin
Re: Commands using -h as an option don't work consistently
Quoted 11 lines · Kevin Day
Because of a bug in
parse-options.c, any command that has a '-h' option will sometimes display the usage page instead of executing. For example, ls-remote has two options:-t, --[no-]tags limit to tags
-h, --[no-]heads limit to headsgit ls-remote --heads #works
git ls-remote --tags #works
git ls-remote -t #works
git ls-remote -t -h #works
git ls-remote -h #shows the help page
Quoted 7 lines
This is because of these lines in
parse-options.c:/* lone -h asks for help */
if (internal_help&&ctx->total== 1 && !strcmp(arg + 1, "h")) gotoshow_usage;This is being executed before it looks to see if there actually is a -h option.
This is very much deliberate design. I think in these cases we make an unambiguous longhand (e.g. "--heads" we see above) available, or you can explicitly say the remote, i.e. "git ls-remote -h origin", and that has been the officially accepted "solution".
Let's see what improvements you bring to the table.
Quoted 4 lines
The options I see:
1) Fix -h handling and add ignores and fixes where possible to the failing tests and try to not use -h as an option for anything new.
I do not quite understand the former half, but "try not to use -h for new things" is a very good idea and it is pretty much what we have been doing.
Note: There however is a scenario where we cannot avoid it---if we were trying to match/mimick some established external command, we may have to use the same "-h" as they use (e.g., "git grep -h -e ..." tries to mimick "grep -h -e ..."). Even in that case, because "git grep -h" alone would not make any sense without any pattern, the command behaves very sensibly, by the way.
Quoted 1 line
2) Change -h to -H or something, but this breaks backwards compatibility
As you said it yourself, this is a non starter.
Quoted 5 lines
3) Fix it so that -h works if a command uses it, and additionally make a new global option -? or --usage or something that always shows the usage page and change tests to use that, while leaving -h sometimes showing usage and sometimes executing the option to preserve as much backward compatibility as possible.
Reading this and then going back to the ls-remote examples you gave earlier, I do not think the current behaviour is all that bad, relative to what is being proposed, except for an explicit support for "-?".
We can certainly add support for "-?", but the behaviour when "-?" is not used (and when "-h" is used) would not have to change from the current behaviour, and that would still be serviceable, I presume?
We actually do not have to *add* support for "-?", as it comes with parse-options for free ;-)
$ git ls-remote -\?
error: unknown switch '?'
usage: git ls-remote ...
... the same "ls-remote -h" output given here ...So, I dunno.
Re: Commands using -h as an option don't work consistently
Quoted 8 lines · Junio C Hamano
This is very much deliberate design. I think in these cases we make an unambiguous longhand (e.g. "--heads" we see above) available, or you can explicitly say the remote, i.e. "git ls-remote -h origin", and that has been the officially accepted "solution".
Yeah, and that totally makes sense. This bit me because I was programmatically generating git commands that would sometimes call ls-remote with no options, sometimes asking only for heads, sometimes only for tags.... and was baffled for longer than I want to admit why it wasn't working consistently. I thought the usage was being shown because I was doing something wrong. My first thought was it was showing me the help message because if you ask for heads you must also use some other option along with it. It didn't occur to me that -h and --heads would behave differently.
Quoted 10 lines
Let's see what improvements you bring to the table.
Quoted 4 lines
The options I see:
1) Fix -h handling and add ignores and fixes where possible to the failing tests and try to not use -h as an option for anything new.
I do not quite understand the former half, but "try not to use -h for new things" is a very good idea and it is pretty much what we have been doing.
Sorry, let me rephrase that. 1) Apply the fix I was proposing to make it so that the command's -h usage has precedence over showing the usage. Any tests that break because of that which don't have a plausible fix mark as "# TODO known breakage" like several other commands have because they aren't generating usage output correctly for one reason or another.
Quoted 5 lines
We can certainly add support for "-?", but the behaviour when "-?" is not used (and when "-h" is used) would not have to change from the current behaviour, and that would still be serviceable, I presume?
That was proposing making -? unconditionally show usage, if a command uses -h give that priority over showing usage even if it's the only option, but leaving -h to still show usage everywhere else, and changing all the tests to use -? Instead of -h so the tests can unambiguously request the usage.
I think that covers every case then. If a command advertises -h it always works, it falls back to showing usage if there is no -h, and tests can use -? which will always show usage and we can even make parse-options reject anyone's attempt to use -? as an option in the future so this doesn't come up again in 10 years.
Quoted 7 lines
We actually do not have to *add* support for "-?", as it comes with parse-options for free ;-)
$ git ls-remote -\? error: unknown switch '?' usage: git ls-remote ... ... the same "ls-remote -h" output given here ...
That *almost* works, except some tests would have to be modified because they don't like that error line in there, but that is super clever! It would be pretty trivial to make parse-options deliberately spit the usage out without an error though in the -? case.
Re: Commands using -h as an option don't work consistently
Quoted 7 lines · Kevin Day
Quoted 6 lines
Quoted 2 lines
1) Fix -h handling and add ignores and fixes where possible to the failing tests and try to not use -h as an option for anything new.
I do not quite understand the former half, but "try not to use -h for new things" is a very good idea and it is pretty much what we have been doing.
Quoted 6 lines
Sorry, let me rephrase that. 1) Apply the fix I was proposing to make it so that the command's -h usage has precedence over showing the usage. Any tests that break because of that which don't have a plausible fix mark as "# TODO known breakage" like several other commands have because they aren't generating usage output correctly for one reason or another.
Ah, then no.
I am afraid that it is a non starter. "git ls-remote -h" would then stop breaking existing users' long established expectation, i.e., "for any git subcommand 'cmd', you can say 'git cmd -h' to get the short help". We need to design a good transition plan to wean existing users off of that expectation.
For example, we _could_ introduce "-?" to parse-options _now_, and mark the use of "-h" as deprecated. When the special casing of "-h" parse-options has triggers, the user will be reminded that the "-h" support will have a limited shelf life, and they are urged to retrain their fingers and update their scripts to use "-?", possibly with "advice.shorthelpdeprecationnotice" configuration knob that helps ease the transition. We would update the t/ scripts to use "-?" at the same time, but would probably need to keep tests that use "-h" to ensure that the warning triggers.
We will keep things that way for a while, and once we get the users' expectation updated so that they think 'git cmd -?' (not 'git cmd -h') is _the_ way to get the short help for any git subcommand.
At a major version boundary, e.g., Git 3.0, we could remove the special casing of '-h' from parse-options, and "git ls-remote -h" will start working the same way as "git ls-remote -h origin" all of a sudden, but nobody remembers "git ls-remote -h" used to be the way to get short help for the command any more by that time, so nobody will get hurt by such a flipping of the behaviour.
Re: Commands using -h as an option don't work consistently
Quoted 7 lines · Junio C Hamano
Ah, then no.
I am afraid that it is a non starter. "git ls-remote -h" would then start breaking existing users' long established expectation, i.e., "for any git subcommand 'cmd', you can say 'git cmd -h' to get the short help". We need to design a good transition plan to wean existing users off of that expectation.
Another thing I forgot to mention. For "ls-remote" and "show-ref", there is a much nicer transition path we can take. Back in Linus's days, we called branches "heads" (and we used $GIT_DIR/refs/heads/ to store them as individual files), but if we were starting Git from scratch today, there is no reason to. Call branches branches, not heads, which means we do not need to use "-h" to mean "I want to see only the branches and no other refs" at all. You say "--branches" instead.
Which leads to an obvious transition path, which is
* Introduce "--branches" that sits next to "--tags" to "ls-remote" and "show-ref". If the command has "-t" as a short-hand for "--tags", then add "-b" as a short-hand for "--branches". Announce that "--heads" (and "-h" if supported) is deprecated for these commands, and when "--heads" (and "-h" if supported) is used, give a warning to train finger/muscle memory early.
* We will keep things that way for a while, and then remove the "--heads" (and "-h" if supported) from these two commands.
The approach cannot be used to transition "git grep -h" for obvious reasons, but then it makes no sense to give "-h" alone to tell the command "I do not want to see filenames", so that is not a problem.
I checked output from
$ git grep -A2 '^-h' Documentation/
and it seems that ls-remote is the only one that matters, so we do not even have to do the "-?" transition at all.
Thanks.
cover Branches are branches and not heads
Back when Git started, we used the word "head" to mean the tip of possibly multiple histories, and that is where the name of the hierarchy .git/refs/heads/ came from. But these days we call these entities "branches" in human terms, and "head" is still used to refer to the tip of the history each of these branches represent.
When asking "git ls-remote" or "git show-ref" to limit their output to branches (as opposed to showing any ref), we use "--heads" for historical reasons, but give the option a more human friendly name "--branches", and demote "--heads" to the status of a deprecated synonym. This would eventually allow us to remove them at the breaking version boundary.
Junio C Hamano (3):
refs: call branches branches
ls-remote: introduce --branches and deprecate --heads
show-ref: introduce --branches and deprecate --heads
Documentation/git-ls-remote.txt | 12 +++++++----- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/ls-remote.c | 25 ++++++++++++++++++++++--- builtin/show-ref.c | 33 ++++++++++++++++++++++++++------- connect.c | 4 ++-- remote.h | 2 +- t/t1403-show-ref.sh | 22 ++++++++++++++-------- t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++----- 8 files changed, 107 insertions(+), 39 deletions(-)
Signature · 1 line
2.45.2-404-g9eaef5822c
PATCH 1/3 refs: call branches branches
These things in refs/heads/ hierarchy are called "branches" in human parlance. Replace REF_HEADS with REF_BRANCHES to make it clearer.
No end-user visible change intended at this step.
--- builtin/ls-remote.c | 6 +++--- connect.c | 4 ++-- remote.h | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-)
builtin/ls-remote.c +3 -3
@@ -9,7 +9,7 @@#include "wildmatch.h" static const char *const ls_remote_usage[] = { -N_ ("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n" +N_ ("git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]\n" " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n" " [--symref] [<repository> [<patterns>...]]" ),NULL
@@ -68,7 +68,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)N_ ("path of git-upload-pack on the remote host" ), PARSE_OPT_HIDDEN },OPT_BIT ('t' ,"tags" , &flags,N_ ("limit to tags" ),REF_TAGS ), -OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_HEADS ), +OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_BRANCHES ),OPT_BIT (0 ,"refs" , &flags,N_ ("do not show peeled tags" ),REF_NORMAL ),OPT_BOOL (0 ,"get-url" , &get_url, N_("take url.<base>.insteadOf into account")),
@@ -100,7 +100,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)if (flags &REF_TAGS )strvec_push (&transport_options.ref_prefixes,"refs/tags/" ); -if (flags &REF_HEADS ) +if (flags &REF_BRANCHES )strvec_push (&transport_options.ref_prefixes,"refs/heads/" ); remote =remote_get (dest);
connect.c +2 -2
@@ -38,8 +38,8 @@ static int check_ref(const char *name, unsigned int flags) REFNAME_ALLOW_ONELEVEL))return 0 ; -/* REF_HEADS means that we want regular branch heads */ -if ((flags &REF_HEADS ) &&starts_with (name,"heads/" )) +/* REF_BRANCHES means that we want regular branch heads */ +if ((flags &REF_BRANCHES ) &&starts_with (name,"heads/" ))return 1 ;/* REF_TAGS means that we want tags */
remote.h +1 -1
@@ -200,7 +200,7 @@ struct ref { };#define REF_NORMAL (1u << 0) -#define REF_HEADS (1u << 1) +#define REF_BRANCHES (1u << 1)#define REF_TAGS (1u << 2)struct ref *find_ref_by_name (const struct ref *list,const char *name);
Signature · 1 line
2.45.2-404-g9eaef5822c
Re: [PATCH 1/3] refs: call branches branches
Quoted 9 lines · Junio C Hamano
These things in refs/heads/ hierarchy are called "branches" in human parlance. Replace
REF_HEADSwithREF_BRANCHESto make it clearer.No end-user visible change intended at this step.
Signed-off-by Junio C Hamano <[email protected]>---
builtin/ls-remote.c line 13
Quoted 6 lines
builtin/ls-remote.c +1
-1@@ -9,7 +9,7 @@static const char *const ls_remote_usage[] = { -N_ ("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n" +N_ ("git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]\n" " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n" " [--symref] [<repository> [<patterns>...]]" ),NULL
This change belongs in patch [2/3], doesn't it, not [1/3]?
PATCH 2/3 ls-remote: introduce --branches and deprecate --heads
In reply to Junio C HamanoWe call the tips of branches "heads", but this command calls the option to show only branches "--heads", which confuses the branches themselves and the tips of branches.
Straighten the terminology by introducing "--branches" option that limits the output to branches, and deprecate "--heads" option used that way.
--- Documentation/git-ls-remote.txt | 12 +++++++----- builtin/ls-remote.c | 21 ++++++++++++++++++++- t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++----- 3 files changed, 52 insertions(+), 11 deletions(-)
Documentation/git-ls-remote.txt +7 -5
@@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>] +'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=<exec>] [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>] [--symref] [<repository> [<patterns>...]]
@@ -21,14 +21,16 @@ commit IDs. OPTIONS ------- --h:: ---heads:: +-b:: +--branches:: -t:: --tags:: - Limit to only refs/heads and refs/tags, respectively. + Limit to only local branches and local tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. Note that `git ls-remote -h` used without + displayed. Note that `--heads` and `-h` are deprecated + synonyms for `--branches` and `-b` and may be removed in + the future. Also note that `git ls-remote -h` used without anything else on the command line gives help, consistent with other git subcommands.
builtin/ls-remote.c +20 -1
@@ -38,6 +38,20 @@ static int tail_match(const char **pattern, const char *path)return 0 ; } +static int heads_callback (const struct option *opt,const char *arg,int unset) +{ +unsigned *flags = opt->value; + +if (unset) { +warning (_ ("'--no-heads' is deprecated; use '--no-branches' instead" )); + *flags &= ~REF_BRANCHES ; + }else { +warning (_ ("'--heads' is deprecated; use '--branches' instead" )); + *flags |=REF_BRANCHES ; + } +return 0 ; +} +int cmd_ls_remote (int argc,const char **argv,const char *prefix) {const char *dest =NULL ;
@@ -68,7 +82,12 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)N_ ("path of git-upload-pack on the remote host" ), PARSE_OPT_HIDDEN },OPT_BIT ('t' ,"tags" , &flags,N_ ("limit to tags" ),REF_TAGS ), -OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_BRANCHES ), +OPT_BIT ('b' ,"branches" , &flags,N_ ("limit to branches" ),REF_BRANCHES ), +OPT_CALLBACK_F ('h' ,"heads" , &flags, +NULL , +N_ ("deprecated synonym for --branches" ), +PARSE_OPT_NOARG |PARSE_OPT_HIDDEN , + &heads_callback),OPT_BIT (0 ,"refs" , &flags,N_ ("do not show peeled tags" ),REF_NORMAL ),OPT_BOOL (0 ,"get-url" , &get_url, N_("take url.<base>.insteadOf into account")),
t/t5512-ls-remote.sh +25 -5
@@ -47,6 +47,7 @@ test_expect_success setup ' git show-ref -d >refs && sed -e "s/ / /" refs >>expected.all && + grep refs/heads/ expected.all >expected.branches && git remote add self "$(pwd)/.git" && git remote add self2 "." '
@@ -71,6 +72,25 @@ test_expect_success 'ls-remote self' ' test_cmp expected.all actual ' +test_expect_success 'ls-remote --branches self' ' + git ls-remote --branches self >actual && + test_cmp expected.branches actual && + git ls-remote -b self >actual && + test_cmp expected.branches actual +' + +test_expect_success 'ls-remote -h is deprecated' ' + git ls-remote -h self >actual 2>warning && + test_cmp expected.branches actual && + test_grep deprecated warning +' + +test_expect_success 'ls-remote --heads is deprecated' ' + git ls-remote --heads self >actual 2>warning && + test_cmp expected.branches actual && + test_grep deprecated warning +' + test_expect_success 'ls-remote --sort="version:refname" --tags self' ' generate_references \ refs/tags/mark \
@@ -275,7 +295,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' ' test_cmp expect actual ' -test_expect_success 'ls-remote with filtered symref (--heads)' ' +test_expect_success 'ls-remote with filtered symref (--branches)' ' git symbolic-ref refs/heads/foo refs/tags/mark && cat >expect.v2 <<-EOF && ref: refs/tags/mark refs/heads/foo
@@ -283,9 +303,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' ' $rev refs/heads/main EOF grep -v "^ref: refs/tags/" <expect.v2 >expect.v0 && - git -c protocol.version=0 ls-remote --symref --heads . >actual.v0 && + git -c protocol.version=0 ls-remote --symref --branches . >actual.v0 && test_cmp expect.v0 actual.v0 && - git -c protocol.version=2 ls-remote --symref --heads . >actual.v2 && + git -c protocol.version=2 ls-remote --symref --branches . >actual.v2 && test_cmp expect.v2 actual.v2 '
@@ -335,9 +355,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' ' test_expect_success 'ls-remote prefixes work with all protocol versions' ' git for-each-ref --format="%(objectname) %(refname)" \ refs/heads/ refs/tags/ >expect && - git -c protocol.version=0 ls-remote --heads --tags . >actual.v0 && + git -c protocol.version=0 ls-remote --branches --tags . >actual.v0 && test_cmp expect actual.v0 && - git -c protocol.version=2 ls-remote --heads --tags . >actual.v2 && + git -c protocol.version=2 ls-remote --branches --tags . >actual.v2 && test_cmp expect actual.v2 '
Signature · 1 line
2.45.2-404-g9eaef5822c
Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads
Quoted 29 lines · Junio C Hamano
We call the tips of branches "heads", but this command calls the option to show only branches "--heads", which confuses the branches themselves and the tips of branches.
Straighten the terminology by introducing "--branches" option that limits the output to branches, and deprecate "--heads" option used that way.
Signed-off-by Junio C Hamano <[email protected]>--- Documentation/git-ls-remote.txt | 12 +++++++----- builtin/ls-remote.c | 21 ++++++++++++++++++++- t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++----- 3 files changed, 52 insertions(+), 11 deletions(-)Documentation/git-ls-remote.txt +1
-1@@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>] +'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=<exec>] [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>] [--symref] [<repository> [<patterns>...]]
Documentation/git-ls-remote.txt commit IDs. · line 24
Quoted 6 lines
Documentation/git-ls-remote.txt +1
-2@@ -21,14 +21,16 @@ commit IDs. OPTIONS ------- --h:: ---heads:: +-b::
Perhaps we can avoid this 'single-letter' option, due to we're no giving the same abbreviation for '--branches' in other places.
Quoted 19 lines
Documentation/git-ls-remote.txt +5
-2+--branches:: -t:: --tags:: - Limit to only refs/heads and refs/tags, respectively. + Limit to only local branches and local tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. Note that `git ls-remote -h` used without + displayed. Note that `--heads` and `-h` are deprecated + synonyms for `--branches` and `-b` and may be removed in + the future. Also note that `git ls-remote -h` used without anything else on the command line gives help, consistent with other git subcommands.builtin/ls-remote.c +0
-0
builtin/ls-remote.c static int tail_match(const char **pattern, const char *path) · line 46
Quoted 9 lines
builtin/ls-remote.c +6
-0@@ -38,6 +38,20 @@ static int tail_match(const char **pattern, const char *path)return 0 ; } +static int heads_callback (const struct option *opt,const char *arg,int unset) +{ +unsigned *flags = opt->value; + +if (unset) { +warning (_ ("'--no-heads' is deprecated; use '--no-branches' instead" ));
I wonder if this would be better:
warning(_("'%s' is deprecated; use '%s' instead"), '--no-heads', '--no-branches');Quoted 99 lines
builtin/ls-remote.c +14
-1+ *flags &= ~REF_BRANCHES ; + }else { +warning (_ ("'--heads' is deprecated; use '--branches' instead" )); + *flags |=REF_BRANCHES ; + } +return 0 ; +} +int cmd_ls_remote (int argc,const char **argv,const char *prefix) {const char *dest =NULL ;@@ -68,7 +82,12 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)N_ ("path of git-upload-pack on the remote host" ), PARSE_OPT_HIDDEN },OPT_BIT ('t' ,"tags" , &flags,N_ ("limit to tags" ),REF_TAGS ), -OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_BRANCHES ), +OPT_BIT ('b' ,"branches" , &flags,N_ ("limit to branches" ),REF_BRANCHES ), +OPT_CALLBACK_F ('h' ,"heads" , &flags, +NULL , +N_ ("deprecated synonym for --branches" ), +PARSE_OPT_NOARG |PARSE_OPT_HIDDEN , + &heads_callback),OPT_BIT (0 ,"refs" , &flags,N_ ("do not show peeled tags" ),REF_NORMAL ),OPT_BOOL (0 ,"get-url" , &get_url, N_("take url.<base>.insteadOf into account")),t/t5512-ls-remote.sh +25
-5@@ -47,6 +47,7 @@ test_expect_success setup ' git show-ref -d >refs && sed -e "s/ / /" refs >>expected.all && + grep refs/heads/ expected.all >expected.branches && git remote add self "$(pwd)/.git" && git remote add self2 "." '@@ -71,6 +72,25 @@ test_expect_success 'ls-remote self' ' test_cmp expected.all actual ' +test_expect_success 'ls-remote --branches self' ' + git ls-remote --branches self >actual && + test_cmp expected.branches actual && + git ls-remote -b self >actual && + test_cmp expected.branches actual +' + +test_expect_success 'ls-remote -h is deprecated' ' + git ls-remote -h self >actual 2>warning && + test_cmp expected.branches actual && + test_grep deprecated warning +' + +test_expect_success 'ls-remote --heads is deprecated' ' + git ls-remote --heads self >actual 2>warning && + test_cmp expected.branches actual && + test_grep deprecated warning +' + test_expect_success 'ls-remote --sort="version:refname" --tags self' ' generate_references \ refs/tags/mark \@@ -275,7 +295,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' ' test_cmp expect actual ' -test_expect_success 'ls-remote with filtered symref (--heads)' ' +test_expect_success 'ls-remote with filtered symref (--branches)' ' git symbolic-ref refs/heads/foo refs/tags/mark && cat >expect.v2 <<-EOF && ref: refs/tags/mark refs/heads/foo@@ -283,9 +303,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' ' $rev refs/heads/main EOF grep -v "^ref: refs/tags/" <expect.v2 >expect.v0 && - git -c protocol.version=0 ls-remote --symref --heads . >actual.v0 && + git -c protocol.version=0 ls-remote --symref --branches . >actual.v0 && test_cmp expect.v0 actual.v0 && - git -c protocol.version=2 ls-remote --symref --heads . >actual.v2 && + git -c protocol.version=2 ls-remote --symref --branches . >actual.v2 && test_cmp expect.v2 actual.v2 '@@ -335,9 +355,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' ' test_expect_success 'ls-remote prefixes work with all protocol versions' ' git for-each-ref --format="%(objectname) %(refname)" \ refs/heads/ refs/tags/ >expect && - git -c protocol.version=0 ls-remote --heads --tags . >actual.v0 && + git -c protocol.version=0 ls-remote --branches --tags . >actual.v0 && test_cmp expect actual.v0 && - git -c protocol.version=2 ls-remote --heads --tags . >actual.v2 && + git -c protocol.version=2 ls-remote --branches --tags . >actual.v2 && test_cmp expect actual.v2 'Signature · 1 line
2.45.2-404-g9eaef5822c
Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads
Quoted 7 lines · Rubén Justo
builtin/ls-remote.c static int tail_match(const char **pattern, const char *path) · line 46
Quoted 2 lines · Junio C Hamano
builtin/ls-remote.c +2
-0+if (unset) { +warning (_ ("'--no-heads' is deprecated; use '--no-branches' instead" ));I wonder if this would be better:
warning(_("'%s' is deprecated; use '%s' instead"), '--no-heads', '--no-branches');
Unless there is a concrete plan to free up --heads to mean something else in the future, I wonder why we need to warn about this at all, especially since retaining the deprecated --heads alias in perpetuity is effectively zero-cost for the Git maintainers, whereas adding this warning potentially punishes users by making them do extra work for no obvious reason.
Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads
Quoted 2 lines · Eric Sunshine
Unless there is a concrete plan to free up --heads to mean something else in the future, I wonder why we need to warn about this at all,
There is no plan to repurpose "--heads", but this is primarily to make sure "-h" cannot mean anything but "please give me a short help".
PATCH 3/3 show-ref: introduce --branches and deprecate --heads
In reply to Junio C HamanoWe call the tips of branches "heads", but this command calls the option to show only branches "--heads", which confuses the branches themselves and the tips of branches.
Straighten the terminology by introducing "--branches" option that limits the output to branches, and deprecate "--heads" option used that way.
--- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/show-ref.c | 33 ++++++++++++++++++++++++++------- t/t1403-show-ref.sh | 22 ++++++++++++++-------- 3 files changed, 50 insertions(+), 23 deletions(-)
Documentation/git-show-ref.txt +10 -8
@@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git show-ref' [--head] [-d | --dereference] - [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] - [--heads] [--] [<pattern>...] + [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags] + [--] [<pattern>...] 'git show-ref' --verify [-q | --quiet] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--] [<ref>...]
@@ -45,12 +45,14 @@ OPTIONS Show the HEAD reference, even if it would normally be filtered out. ---heads:: +--branches:: --tags:: - Limit to "refs/heads" and "refs/tags", respectively. These options + Limit to local branches and local tags, respectively. These options are not mutually exclusive; when given both, references stored in - "refs/heads" and "refs/tags" are displayed. + "refs/heads" and "refs/tags" are displayed. Note that `--heads` + is a deprecated synonym for `--branches` and may be removed + in the future. -d:: --dereference::
@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format: For example, ----------------------------------------------------------------------------- -$ git show-ref --heads --hash +$ git show-ref --branches --hash 2e3ba0114a1f52b47df29743d6915d056be13278 185008ae97960c8d551adcd9e23565194651b5d1 03adf42c988195b50e1a1935ba5fcbc39b2b029b
@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use `--tags` and/or `--heads` -respectively (using both means that it shows tags and heads, but not other +To show only tags, or only proper branch heads, use `--tags` and/or `--branches` +respectively (using both means that it shows tags and branches, but not other random references under the refs/ subdirectory). To do automatic tag object dereferencing, use the `-d` or `--dereference`
builtin/show-ref.c +26 -7
@@ -11,8 +11,8 @@static const char *const show_ref_usage[] = {N_ ("git show-ref [--head] [-d | --dereference]\n" -" [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n" -" [--heads] [--] [<pattern>...]" ), +" [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]\n" +" [--] [<pattern>...]" ),N_ ("git show-ref --verify [-q | --quiet] [-d | --dereference]\n" " [-s | --hash[=<n>]] [--abbrev[=<n>]]\n" " [--] [<ref>...]" ),
@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,struct patterns_options {int show_head; -int heads_only; +int branches_only;int tags_only; };
@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,if (opts->show_head)head_ref (show_ref, &show_ref_data); -if (opts->heads_only || opts->tags_only) { -if (opts->heads_only) +if (opts->branches_only || opts->tags_only) { +if (opts->branches_only)for_each_fullref_in ("refs/heads/" , show_ref, &show_ref_data);if (opts->tags_only)for_each_fullref_in ("refs/tags/" , show_ref, &show_ref_data);
@@ -279,6 +279,20 @@ static int exclude_existing_callback(const struct option *opt, const char *arg,return 0 ; } +static int heads_callback (const struct option *opt,const char *arg,int unset) +{ +int *branches_only = opt->value; + +if (unset) { +warning (_ ("'--no-heads' is deprecated; use '--no-branches' instead" )); + *branches_only =0 ; + }else { +warning (_ ("'--heads' is deprecated; use '--branches' instead" )); + *branches_only =1 ; + } +return 0 ; +} +int cmd_show_ref (int argc,const char **argv,const char *prefix) {struct exclude_existing_options exclude_existing_opts = {0 };
@@ -286,8 +300,13 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)struct show_one_options show_one_opts = {0 };int verify =0 , exists =0 ;const struct option show_ref_options[] = { -OPT_BOOL (0 ,"tags" , &patterns_opts.tags_only,N_ ("only show tags (can be combined with heads)" )), -OPT_BOOL (0 ,"heads" , &patterns_opts.heads_only,N_ ("only show heads (can be combined with tags)" )), +OPT_BOOL (0 ,"tags" , &patterns_opts.tags_only,N_ ("only show tags (can be combined with branches)" )), +OPT_BOOL (0 ,"branches" , &patterns_opts.branches_only,N_ ("only show branches (can be combined with tags)" )), +OPT_CALLBACK_F (0 ,"heads" , &patterns_opts.branches_only, +NULL , +N_ ("deprecated synonym for --branches)" ), +PARSE_OPT_NOARG |PARSE_OPT_HIDDEN , + &heads_callback),OPT_BOOL (0 ,"exists" , &exists,N_ ("check for reference existence without resolving" )),OPT_BOOL (0 ,"verify" , &verify,N_ ("stricter reference checking, " "requires exact ref path" )),
t/t1403-show-ref.sh +14 -8
@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' ' ' -test_expect_success 'show-ref --heads, --tags, --head, pattern' ' +test_expect_success 'show-ref --branches, --tags, --head, pattern' ' for branch in B main side do echo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1 - done >expect.heads && - git show-ref --heads >actual && - test_cmp expect.heads actual && + done >expect.branches && + git show-ref --branches >actual && + test_cmp expect.branches actual && for tag in A B C do
@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' ' git show-ref --tags >actual && test_cmp expect.tags actual && - cat expect.heads expect.tags >expect && - git show-ref --heads --tags >actual && + cat expect.branches expect.tags >expect && + git show-ref --branches --tags >actual && test_cmp expect actual && { echo $(git rev-parse HEAD) HEAD && - cat expect.heads expect.tags + cat expect.branches expect.tags } >expect && - git show-ref --heads --tags --head >actual && + git show-ref --branches --tags --head >actual && test_cmp expect actual && {
@@ -165,6 +165,12 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' ' test_cmp expect actual ' +test_expect_success 'show-ref --heads is deprecated' ' + git show-ref --heads >actual 2>warning && + test_grep deprecated warning && + test_cmp expect.branches actual +' + test_expect_success 'show-ref --verify HEAD' ' echo $(git rev-parse HEAD) HEAD >expect && git show-ref --verify HEAD >actual &&
Signature · 1 line
2.45.2-404-g9eaef5822c
Re: [PATCH 0/3] Branches are branches and not heads
In reply to Junio C HamanoQuoted 6 lines · Junio C Hamano
Back when Git started, we used the word "head" to mean the tip of possibly multiple histories, and that is where the name of the hierarchy .git/refs/heads/ came from. But these days we call these entities "branches" in human terms, and "head" is still used to refer to the tip of the history each of these branches represent.
Quoted 6 lines
When asking "git ls-remote" or "git show-ref" to limit their output to branches (as opposed to showing any ref), we use "--heads" for historical reasons, but give the option a more human friendly name "--branches", and demote "--heads" to the status of a deprecated synonym. This would eventually allow us to remove them at the breaking version boundary.
All of this sounds like a very sensible step, to me.
I've left a couple of nits; none important.
Thanks.
Quoted 19 lines
Junio C Hamano (3):
refs: call branches branches
ls-remote: introduce --branches and deprecate --heads
show-ref: introduce --branches and deprecate --headsDocumentation/git-ls-remote.txt | 12 +++++++----- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/ls-remote.c | 25 ++++++++++++++++++++++--- builtin/show-ref.c | 33 ++++++++++++++++++++++++++------- connect.c | 4 ++-- remote.h | 2 +- t/t1403-show-ref.sh | 22 ++++++++++++++-------- t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++----- 8 files changed, 107 insertions(+), 39 deletions(-)Signature · 1 line
2.45.2-404-g9eaef5822c
Re: [PATCH 0/3] Branches are branches and not heads
Quoted 14 lines · Rubén Justo
Quoted 6 lines · Junio C Hamano
Back when Git started, we used the word "head" to mean the tip of possibly multiple histories, and that is where the name of the hierarchy .git/refs/heads/ came from. But these days we call these entities "branches" in human terms, and "head" is still used to refer to the tip of the history each of these branches represent.
Quoted 6 lines
When asking "git ls-remote" or "git show-ref" to limit their output to branches (as opposed to showing any ref), we use "--heads" for historical reasons, but give the option a more human friendly name "--branches", and demote "--heads" to the status of a deprecated synonym. This would eventually allow us to remove them at the breaking version boundary.
Quoted 3 lines
All of this sounds like a very sensible step, to me.
I've left a couple of nits; none important.
Agreed, I like the direction of this patch series very much. I've got nothing to add on top of what has already been said.
Thanks!
Patrick
v2 cover Branches are branches and not heads
In reply to Junio C Hamanotl;dr for those who did read v1: v2 does not warn when deprecated variants are used.
----------------------
Back when Git started, we used the word "head" to mean the tip of possibly multiple histories, and that is where the name of the hierarchy .git/refs/heads/ came from. But these days we call these entities "branches" in human terms, and "head" is still used to refer to the tip of the history each of these branches represent.
When asking "git ls-remote" or "git show-ref" to limit their output to branches (as opposed to showing any ref), we use "--heads" for historical reasons, but give the option a more human friendly name "--branches", and demote "--heads" to the status of a deprecated synonym.
We do not plan to remove "--heads" or "-h" yet, but we may want to do so at the Git 3.0 boundary, in which case we will need to start advertising upcoming removal with an extra warning when they are used. But let's not start annoying users for now.
Junio C Hamano (3):
refs: call branches branches
ls-remote: introduce --branches and deprecate --heads
show-ref: introduce --branches and deprecate --heads
Documentation/git-ls-remote.txt | 12 +++++++----- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/ls-remote.c | 9 ++++++--- builtin/show-ref.c | 16 +++++++++------- connect.c | 4 ++-- remote.h | 2 +- t/t1403-show-ref.sh | 24 ++++++++++++++++-------- t/t5512-ls-remote.sh | 32 +++++++++++++++++++++++++++----- 8 files changed, 78 insertions(+), 39 deletions(-)
Range-diff against v1:
1: 2c551ed37b = 1: 2c551ed37b refs: call branches branches
2: f88fe89ff7 ! 2: 5549e98042 ls-remote: introduce --branches and deprecate --heads
@@ Commit message
limits the output to branches, and deprecate "--heads" option used
that way.
+ We do not plan to remove "--heads" or "-h" yet; we may want to do so
+ at Git 3.0, in which case, we may need to start advertising upcoming
+ removal with an extra warning when they are used.
+
Signed-off-by: Junio C Hamano <[email protected]>
## Documentation/git-ls-remote.txt ##
@@ builtin/ls-remote.c
" [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
" [--symref] [<repository> [<patterns>...]]"),
NULL
-@@ builtin/ls-remote.c: static int tail_match(const char **pattern, const char *path)
- return 0;
- }
-
-+static int heads_callback(const struct option *opt, const char *arg, int unset)
-+{
-+ unsigned *flags = opt->value;
-+
-+ if (unset) {
-+ warning(_("'--no-heads' is deprecated; use '--no-branches' instead"));
-+ *flags &= ~REF_BRANCHES;
-+ } else {
-+ warning(_("'--heads' is deprecated; use '--branches' instead"));
-+ *flags |= REF_BRANCHES;
-+ }
-+ return 0;
-+}
-+
- int cmd_ls_remote(int argc, const char **argv, const char *prefix)
- {
- const char *dest = NULL;
@@ builtin/ls-remote.c: int cmd_ls_remote(int argc, const char **argv, const char *prefix)
N_("path of git-upload-pack on the remote host"),
PARSE_OPT_HIDDEN },
OPT_BIT('t', "tags", &flags, N_("limit to tags"), REF_TAGS),
- OPT_BIT('h', "heads", &flags, N_("limit to heads"), REF_BRANCHES),
+ OPT_BIT('b', "branches", &flags, N_("limit to branches"), REF_BRANCHES),
-+ OPT_CALLBACK_F('h', "heads", &flags,
-+ NULL,
-+ N_("deprecated synonym for --branches"),
-+ PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,
-+ &heads_callback),
++ OPT_BIT_F('h', "heads", &flags,
++ N_("deprecated synonym for --branches"), REF_BRANCHES,
++ PARSE_OPT_HIDDEN),
OPT_BIT(0, "refs", &flags, N_("do not show peeled tags"), REF_NORMAL),
OPT_BOOL(0, "get-url", &get_url,
N_("take url.<base>.insteadOf into account")),
@@ t/t5512-ls-remote.sh: test_expect_success 'ls-remote self' '
+ test_cmp expected.branches actual
+'
+
-+test_expect_success 'ls-remote -h is deprecated' '
++test_expect_success 'ls-remote -h is deprecated w/o warning' '
+ git ls-remote -h self >actual 2>warning &&
+ test_cmp expected.branches actual &&
-+ test_grep deprecated warning
++ test_grep ! deprecated warning
+'
+
-+test_expect_success 'ls-remote --heads is deprecated' '
++test_expect_success 'ls-remote --heads is deprecated and hidden w/o warning' '
++ test_expect_code 129 git ls-remote -h >short-help &&
++ test_grep ! -e --head short-help &&
+ git ls-remote --heads self >actual 2>warning &&
+ test_cmp expected.branches actual &&
-+ test_grep deprecated warning
++ test_grep ! deprecated warning
+'
+
test_expect_success 'ls-remote --sort="version:refname" --tags self' '
3: 295554edfc ! 3: 9022743a32 show-ref: introduce --branches and deprecate --heads
@@ Commit message
limits the output to branches, and deprecate "--heads" option used
that way.
+ We do not plan to remove "--heads" or "-h" yet; we may want to do so
+ at Git 3.0, in which case, we may need to start advertising upcoming
+ removal with an extra warning when they are used.
+
Signed-off-by: Junio C Hamano <[email protected]>
## Documentation/git-show-ref.txt ##
@@ builtin/show-ref.c: static int cmd_show_ref__patterns(const struct patterns_opti
for_each_fullref_in("refs/heads/", show_ref, &show_ref_data);
if (opts->tags_only)
for_each_fullref_in("refs/tags/", show_ref, &show_ref_data);
-@@ builtin/show-ref.c: static int exclude_existing_callback(const struct option *opt, const char *arg,
- return 0;
- }
-
-+static int heads_callback(const struct option *opt, const char *arg, int unset)
-+{
-+ int *branches_only = opt->value;
-+
-+ if (unset) {
-+ warning(_("'--no-heads' is deprecated; use '--no-branches' instead"));
-+ *branches_only = 0;
-+ } else {
-+ warning(_("'--heads' is deprecated; use '--branches' instead"));
-+ *branches_only = 1;
-+ }
-+ return 0;
-+}
-+
- int cmd_show_ref(int argc, const char **argv, const char *prefix)
- {
- struct exclude_existing_options exclude_existing_opts = {0};
@@ builtin/show-ref.c: int cmd_show_ref(int argc, const char **argv, const char *prefix)
struct show_one_options show_one_opts = {0};
int verify = 0, exists = 0;
@@ builtin/show-ref.c: int cmd_show_ref(int argc, const char **argv, const char *pr
- OPT_BOOL(0, "heads", &patterns_opts.heads_only, N_("only show heads (can be combined with tags)")),
+ OPT_BOOL(0, "tags", &patterns_opts.tags_only, N_("only show tags (can be combined with branches)")),
+ OPT_BOOL(0, "branches", &patterns_opts.branches_only, N_("only show branches (can be combined with tags)")),
-+ OPT_CALLBACK_F(0, "heads", &patterns_opts.branches_only,
-+ NULL,
-+ N_("deprecated synonym for --branches)"),
-+ PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,
-+ &heads_callback),
++ OPT_HIDDEN_BOOL(0, "heads", &patterns_opts.branches_only,
++ N_("deprecated synonym for --branches")),
OPT_BOOL(0, "exists", &exists, N_("check for reference existence without resolving")),
OPT_BOOL(0, "verify", &verify, N_("stricter reference checking, "
"requires exact ref path")),
@@ t/t1403-show-ref.sh: test_expect_success 'show-ref --heads, --tags, --head, patt
test_cmp expect actual
'
-+test_expect_success 'show-ref --heads is deprecated' '
++test_expect_success 'show-ref --heads is deprecated and hidden' '
++ test_expect_code 129 git show-ref -h >short-help &&
++ test_grep ! -e --heads short-help &&
+ git show-ref --heads >actual 2>warning &&
-+ test_grep deprecated warning &&
++ test_grep ! deprecated warning &&
+ test_cmp expect.branches actual
+'
+Signature · 1 line
2.45.2-409-g7b0defb391
PATCH v2 1/3 refs: call branches branches
These things in refs/heads/ hierarchy are called "branches" in human parlance. Replace REF_HEADS with REF_BRANCHES to make it clearer.
No end-user visible change intended at this step.
--- builtin/ls-remote.c | 4 ++-- connect.c | 4 ++-- remote.h | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-)
builtin/ls-remote.c +2 -2
@@ -68,7 +68,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)N_ ("path of git-upload-pack on the remote host" ), PARSE_OPT_HIDDEN },OPT_BIT ('t' ,"tags" , &flags,N_ ("limit to tags" ),REF_TAGS ), -OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_HEADS ), +OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_BRANCHES ),OPT_BIT (0 ,"refs" , &flags,N_ ("do not show peeled tags" ),REF_NORMAL ),OPT_BOOL (0 ,"get-url" , &get_url, N_("take url.<base>.insteadOf into account")),
@@ -100,7 +100,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)if (flags &REF_TAGS )strvec_push (&transport_options.ref_prefixes,"refs/tags/" ); -if (flags &REF_HEADS ) +if (flags &REF_BRANCHES )strvec_push (&transport_options.ref_prefixes,"refs/heads/" ); remote =remote_get (dest);
connect.c +2 -2
@@ -38,8 +38,8 @@ static int check_ref(const char *name, unsigned int flags) REFNAME_ALLOW_ONELEVEL))return 0 ; -/* REF_HEADS means that we want regular branch heads */ -if ((flags &REF_HEADS ) &&starts_with (name,"heads/" )) +/* REF_BRANCHES means that we want regular branch heads */ +if ((flags &REF_BRANCHES ) &&starts_with (name,"heads/" ))return 1 ;/* REF_TAGS means that we want tags */
remote.h +1 -1
@@ -200,7 +200,7 @@ struct ref { };#define REF_NORMAL (1u << 0) -#define REF_HEADS (1u << 1) +#define REF_BRANCHES (1u << 1)#define REF_TAGS (1u << 2)struct ref *find_ref_by_name (const struct ref *list,const char *name);
Signature · 1 line
2.45.2-409-g7b0defb391
PATCH v2 2/3 ls-remote: introduce --branches and deprecate --heads
In reply to Junio C HamanoWe call the tips of branches "heads", but this command calls the option to show only branches "--heads", which confuses the branches themselves and the tips of branches.
Straighten the terminology by introducing "--branches" option that limits the output to branches, and deprecate "--heads" option used that way.
We do not plan to remove "--heads" or "-h" yet; we may want to do so at Git 3.0, in which case, we may need to start advertising upcoming removal with an extra warning when they are used.
--- Documentation/git-ls-remote.txt | 12 +++++++----- builtin/ls-remote.c | 7 +++++-- t/t5512-ls-remote.sh | 32 +++++++++++++++++++++++++++----- 3 files changed, 39 insertions(+), 12 deletions(-)
Documentation/git-ls-remote.txt +7 -5
@@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>] +'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=<exec>] [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>] [--symref] [<repository> [<patterns>...]]
@@ -21,14 +21,16 @@ commit IDs. OPTIONS ------- --h:: ---heads:: +-b:: +--branches:: -t:: --tags:: - Limit to only refs/heads and refs/tags, respectively. + Limit to only local branches and local tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. Note that `git ls-remote -h` used without + displayed. Note that `--heads` and `-h` are deprecated + synonyms for `--branches` and `-b` and may be removed in + the future. Also note that `git ls-remote -h` used without anything else on the command line gives help, consistent with other git subcommands.
builtin/ls-remote.c +5 -2
@@ -9,7 +9,7 @@#include "wildmatch.h" static const char *const ls_remote_usage[] = { -N_ ("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n" +N_ ("git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]\n" " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n" " [--symref] [<repository> [<patterns>...]]" ),NULL
@@ -68,7 +68,10 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)N_ ("path of git-upload-pack on the remote host" ), PARSE_OPT_HIDDEN },OPT_BIT ('t' ,"tags" , &flags,N_ ("limit to tags" ),REF_TAGS ), -OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_BRANCHES ), +OPT_BIT ('b' ,"branches" , &flags,N_ ("limit to branches" ),REF_BRANCHES ), +OPT_BIT_F ('h' ,"heads" , &flags, +N_ ("deprecated synonym for --branches" ),REF_BRANCHES , +PARSE_OPT_HIDDEN ),OPT_BIT (0 ,"refs" , &flags,N_ ("do not show peeled tags" ),REF_NORMAL ),OPT_BOOL (0 ,"get-url" , &get_url, N_("take url.<base>.insteadOf into account")),
t/t5512-ls-remote.sh +27 -5
@@ -47,6 +47,7 @@ test_expect_success setup ' git show-ref -d >refs && sed -e "s/ / /" refs >>expected.all && + grep refs/heads/ expected.all >expected.branches && git remote add self "$(pwd)/.git" && git remote add self2 "." '
@@ -71,6 +72,27 @@ test_expect_success 'ls-remote self' ' test_cmp expected.all actual ' +test_expect_success 'ls-remote --branches self' ' + git ls-remote --branches self >actual && + test_cmp expected.branches actual && + git ls-remote -b self >actual && + test_cmp expected.branches actual +' + +test_expect_success 'ls-remote -h is deprecated w/o warning' ' + git ls-remote -h self >actual 2>warning && + test_cmp expected.branches actual && + test_grep ! deprecated warning +' + +test_expect_success 'ls-remote --heads is deprecated and hidden w/o warning' ' + test_expect_code 129 git ls-remote -h >short-help && + test_grep ! -e --head short-help && + git ls-remote --heads self >actual 2>warning && + test_cmp expected.branches actual && + test_grep ! deprecated warning +' + test_expect_success 'ls-remote --sort="version:refname" --tags self' ' generate_references \ refs/tags/mark \
@@ -275,7 +297,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' ' test_cmp expect actual ' -test_expect_success 'ls-remote with filtered symref (--heads)' ' +test_expect_success 'ls-remote with filtered symref (--branches)' ' git symbolic-ref refs/heads/foo refs/tags/mark && cat >expect.v2 <<-EOF && ref: refs/tags/mark refs/heads/foo
@@ -283,9 +305,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' ' $rev refs/heads/main EOF grep -v "^ref: refs/tags/" <expect.v2 >expect.v0 && - git -c protocol.version=0 ls-remote --symref --heads . >actual.v0 && + git -c protocol.version=0 ls-remote --symref --branches . >actual.v0 && test_cmp expect.v0 actual.v0 && - git -c protocol.version=2 ls-remote --symref --heads . >actual.v2 && + git -c protocol.version=2 ls-remote --symref --branches . >actual.v2 && test_cmp expect.v2 actual.v2 '
@@ -335,9 +357,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' ' test_expect_success 'ls-remote prefixes work with all protocol versions' ' git for-each-ref --format="%(objectname) %(refname)" \ refs/heads/ refs/tags/ >expect && - git -c protocol.version=0 ls-remote --heads --tags . >actual.v0 && + git -c protocol.version=0 ls-remote --branches --tags . >actual.v0 && test_cmp expect actual.v0 && - git -c protocol.version=2 ls-remote --heads --tags . >actual.v2 && + git -c protocol.version=2 ls-remote --branches --tags . >actual.v2 && test_cmp expect actual.v2 '
Signature · 1 line
2.45.2-409-g7b0defb391
Re: [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads
Quoted 43 lines · Junio C Hamano
builtin/ls-remote.c +5
-2@@ -9,7 +9,7 @@#include "wildmatch.h" static const char *const ls_remote_usage[] = { -N_ ("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n" +N_ ("git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]\n" " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n" " [--symref] [<repository> [<patterns>...]]" ),NULL @@ -68,7 +68,10 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)N_ ("path of git-upload-pack on the remote host" ), PARSE_OPT_HIDDEN },OPT_BIT ('t' ,"tags" , &flags,N_ ("limit to tags" ),REF_TAGS ), -OPT_BIT ('h' ,"heads" , &flags,N_ ("limit to heads" ),REF_BRANCHES ), +OPT_BIT ('b' ,"branches" , &flags,N_ ("limit to branches" ),REF_BRANCHES ), +OPT_BIT_F ('h' ,"heads" , &flags, +N_ ("deprecated synonym for --branches" ),REF_BRANCHES , +PARSE_OPT_HIDDEN ),OPT_BIT (0 ,"refs" , &flags,N_ ("do not show peeled tags" ),REF_NORMAL ),OPT_BOOL (0 ,"get-url" , &get_url, N_("take url.<base>.insteadOf into account")),t/t5512-ls-remote.sh +3
-0@@ -47,6 +47,7 @@ test_expect_success setup ' git show-ref -d >refs && sed -e "s/ / /" refs >>expected.all && + grep refs/heads/ expected.all >expected.branches && git remote add self "$(pwd)/.git" && git remote add self2 "." '@@ -71,6 +72,27 @@ test_expect_success 'ls-remote self' ' test_cmp expected.all actual ' +test_expect_success 'ls-remote --branches self' ' + git ls-remote --branches self >actual &&
t/t5512-ls-remote.sh test_expect_success 'ls-remote self' ' · line 86
Quoted 10 lines
t/t5512-ls-remote.sh +10
-0+ test_cmp expected.branches actual && + git ls-remote -b self >actual && + test_cmp expected.branches actual +' + +test_expect_success 'ls-remote -h is deprecated w/o warning' ' + git ls-remote -h self >actual 2>warning && + test_cmp expected.branches actual && + test_grep ! deprecated warning +'
It is a bit funny to grep for something that wasn't ever there. But I don't mind it much as we may eventually want to introduce such a deprecation warning if we ever decide to go through with the deprecation.
Patrick
Re: [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads
Quoted 10 lines · Patrick Steinhardt
t/t5512-ls-remote.sh test_expect_success 'ls-remote self' ' · line 86
Quoted 5 lines
t/t5512-ls-remote.sh +5
-0+test_expect_success 'ls-remote -h is deprecated w/o warning' ' + git ls-remote -h self >actual 2>warning && + test_cmp expected.branches actual && + test_grep ! deprecated warning +'It is a bit funny to grep for something that wasn't ever there. But I don't mind it much as we may eventually want to introduce such a deprecation warning if we ever decide to go through with the deprecation.
It is indeed funny. We thought about adding and then made a conscious decision not to add a deprecation warning, so this testpiece serves as a documentation of the status quo, and a back-pointer for readers to blame back to the message of the commit that introduced this one, which clearly says the lack of warning is something we may want to reconsider later.
So, this should be fine (the same for 3/3).
Thanks.
PATCH v2 3/3 show-ref: introduce --branches and deprecate --heads
In reply to Junio C HamanoWe call the tips of branches "heads", but this command calls the option to show only branches "--heads", which confuses the branches themselves and the tips of branches.
Straighten the terminology by introducing "--branches" option that limits the output to branches, and deprecate "--heads" option used that way.
We do not plan to remove "--heads" or "-h" yet; we may want to do so at Git 3.0, in which case, we may need to start advertising upcoming removal with an extra warning when they are used.
--- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/show-ref.c | 16 +++++++++------- t/t1403-show-ref.sh | 24 ++++++++++++++++-------- 3 files changed, 35 insertions(+), 23 deletions(-)
Documentation/git-show-ref.txt +10 -8
@@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git show-ref' [--head] [-d | --dereference] - [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] - [--heads] [--] [<pattern>...] + [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags] + [--] [<pattern>...] 'git show-ref' --verify [-q | --quiet] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--] [<ref>...]
@@ -45,12 +45,14 @@ OPTIONS Show the HEAD reference, even if it would normally be filtered out. ---heads:: +--branches:: --tags:: - Limit to "refs/heads" and "refs/tags", respectively. These options + Limit to local branches and local tags, respectively. These options are not mutually exclusive; when given both, references stored in - "refs/heads" and "refs/tags" are displayed. + "refs/heads" and "refs/tags" are displayed. Note that `--heads` + is a deprecated synonym for `--branches` and may be removed + in the future. -d:: --dereference::
@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format: For example, ----------------------------------------------------------------------------- -$ git show-ref --heads --hash +$ git show-ref --branches --hash 2e3ba0114a1f52b47df29743d6915d056be13278 185008ae97960c8d551adcd9e23565194651b5d1 03adf42c988195b50e1a1935ba5fcbc39b2b029b
@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use `--tags` and/or `--heads` -respectively (using both means that it shows tags and heads, but not other +To show only tags, or only proper branch heads, use `--tags` and/or `--branches` +respectively (using both means that it shows tags and branches, but not other random references under the refs/ subdirectory). To do automatic tag object dereferencing, use the `-d` or `--dereference`
builtin/show-ref.c +9 -7
@@ -11,8 +11,8 @@static const char *const show_ref_usage[] = {N_ ("git show-ref [--head] [-d | --dereference]\n" -" [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n" -" [--heads] [--] [<pattern>...]" ), +" [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]\n" +" [--] [<pattern>...]" ),N_ ("git show-ref --verify [-q | --quiet] [-d | --dereference]\n" " [-s | --hash[=<n>]] [--abbrev[=<n>]]\n" " [--] [<ref>...]" ),
@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,struct patterns_options {int show_head; -int heads_only; +int branches_only;int tags_only; };
@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,if (opts->show_head)head_ref (show_ref, &show_ref_data); -if (opts->heads_only || opts->tags_only) { -if (opts->heads_only) +if (opts->branches_only || opts->tags_only) { +if (opts->branches_only)for_each_fullref_in ("refs/heads/" , show_ref, &show_ref_data);if (opts->tags_only)for_each_fullref_in ("refs/tags/" , show_ref, &show_ref_data);
@@ -286,8 +286,10 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)struct show_one_options show_one_opts = {0 };int verify =0 , exists =0 ;const struct option show_ref_options[] = { -OPT_BOOL (0 ,"tags" , &patterns_opts.tags_only,N_ ("only show tags (can be combined with heads)" )), -OPT_BOOL (0 ,"heads" , &patterns_opts.heads_only,N_ ("only show heads (can be combined with tags)" )), +OPT_BOOL (0 ,"tags" , &patterns_opts.tags_only,N_ ("only show tags (can be combined with branches)" )), +OPT_BOOL (0 ,"branches" , &patterns_opts.branches_only,N_ ("only show branches (can be combined with tags)" )), +OPT_HIDDEN_BOOL (0 ,"heads" , &patterns_opts.branches_only, +N_ ("deprecated synonym for --branches" )),OPT_BOOL (0 ,"exists" , &exists,N_ ("check for reference existence without resolving" )),OPT_BOOL (0 ,"verify" , &verify,N_ ("stricter reference checking, " "requires exact ref path" )),
t/t1403-show-ref.sh +16 -8
@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' ' ' -test_expect_success 'show-ref --heads, --tags, --head, pattern' ' +test_expect_success 'show-ref --branches, --tags, --head, pattern' ' for branch in B main side do echo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1 - done >expect.heads && - git show-ref --heads >actual && - test_cmp expect.heads actual && + done >expect.branches && + git show-ref --branches >actual && + test_cmp expect.branches actual && for tag in A B C do
@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' ' git show-ref --tags >actual && test_cmp expect.tags actual && - cat expect.heads expect.tags >expect && - git show-ref --heads --tags >actual && + cat expect.branches expect.tags >expect && + git show-ref --branches --tags >actual && test_cmp expect actual && { echo $(git rev-parse HEAD) HEAD && - cat expect.heads expect.tags + cat expect.branches expect.tags } >expect && - git show-ref --heads --tags --head >actual && + git show-ref --branches --tags --head >actual && test_cmp expect actual && {
@@ -165,6 +165,14 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' ' test_cmp expect actual ' +test_expect_success 'show-ref --heads is deprecated and hidden' ' + test_expect_code 129 git show-ref -h >short-help && + test_grep ! -e --heads short-help && + git show-ref --heads >actual 2>warning && + test_grep ! deprecated warning && + test_cmp expect.branches actual +' + test_expect_success 'show-ref --verify HEAD' ' echo $(git rev-parse HEAD) HEAD >expect && git show-ref --verify HEAD >actual &&
Signature · 1 line
2.45.2-409-g7b0defb391
Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads
Quoted 179 lines · Junio C Hamano
We call the tips of branches "heads", but this command calls the option to show only branches "--heads", which confuses the branches themselves and the tips of branches.
Straighten the terminology by introducing "--branches" option that limits the output to branches, and deprecate "--heads" option used that way.
We do not plan to remove "--heads" or "-h" yet; we may want to do so at Git 3.0, in which case, we may need to start advertising upcoming removal with an extra warning when they are used.
Signed-off-by Junio C Hamano <[email protected]>--- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/show-ref.c | 16 +++++++++------- t/t1403-show-ref.sh | 24 ++++++++++++++++-------- 3 files changed, 35 insertions(+), 23 deletions(-)Documentation/git-show-ref.txt +10
-8@@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git show-ref' [--head] [-d | --dereference] - [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] - [--heads] [--] [<pattern>...] + [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags] + [--] [<pattern>...] 'git show-ref' --verify [-q | --quiet] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--] [<ref>...]@@ -45,12 +45,14 @@ OPTIONS Show the HEAD reference, even if it would normally be filtered out. ---heads:: +--branches:: --tags:: - Limit to "refs/heads" and "refs/tags", respectively. These options + Limit to local branches and local tags, respectively. These options are not mutually exclusive; when given both, references stored in - "refs/heads" and "refs/tags" are displayed. + "refs/heads" and "refs/tags" are displayed. Note that `--heads` + is a deprecated synonym for `--branches` and may be removed + in the future. -d:: --dereference::@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format: For example, ----------------------------------------------------------------------------- -$ git show-ref --heads --hash +$ git show-ref --branches --hash 2e3ba0114a1f52b47df29743d6915d056be13278 185008ae97960c8d551adcd9e23565194651b5d1 03adf42c988195b50e1a1935ba5fcbc39b2b029b@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use `--tags` and/or `--heads` -respectively (using both means that it shows tags and heads, but not other +To show only tags, or only proper branch heads, use `--tags` and/or `--branches` +respectively (using both means that it shows tags and branches, but not other random references under the refs/ subdirectory). To do automatic tag object dereferencing, use the `-d` or `--dereference`builtin/show-ref.c +9
-7@@ -11,8 +11,8 @@static const char *const show_ref_usage[] = {N_ ("git show-ref [--head] [-d | --dereference]\n" -" [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n" -" [--heads] [--] [<pattern>...]" ), +" [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]\n" +" [--] [<pattern>...]" ),N_ ("git show-ref --verify [-q | --quiet] [-d | --dereference]\n" " [-s | --hash[=<n>]] [--abbrev[=<n>]]\n" " [--] [<ref>...]" ),@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,struct patterns_options {int show_head; -int heads_only; +int branches_only;int tags_only; };@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,if (opts->show_head)head_ref (show_ref, &show_ref_data); -if (opts->heads_only || opts->tags_only) { -if (opts->heads_only) +if (opts->branches_only || opts->tags_only) { +if (opts->branches_only)for_each_fullref_in ("refs/heads/" , show_ref, &show_ref_data);if (opts->tags_only)for_each_fullref_in ("refs/tags/" , show_ref, &show_ref_data);@@ -286,8 +286,10 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)struct show_one_options show_one_opts = {0 };int verify =0 , exists =0 ;const struct option show_ref_options[] = { -OPT_BOOL (0 ,"tags" , &patterns_opts.tags_only,N_ ("only show tags (can be combined with heads)" )), -OPT_BOOL (0 ,"heads" , &patterns_opts.heads_only,N_ ("only show heads (can be combined with tags)" )), +OPT_BOOL (0 ,"tags" , &patterns_opts.tags_only,N_ ("only show tags (can be combined with branches)" )), +OPT_BOOL (0 ,"branches" , &patterns_opts.branches_only,N_ ("only show branches (can be combined with tags)" )), +OPT_HIDDEN_BOOL (0 ,"heads" , &patterns_opts.branches_only, +N_ ("deprecated synonym for --branches" )),OPT_BOOL (0 ,"exists" , &exists,N_ ("check for reference existence without resolving" )),OPT_BOOL (0 ,"verify" , &verify,N_ ("stricter reference checking, " "requires exact ref path" )),t/t1403-show-ref.sh +16
-9@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' ' ' -test_expect_success 'show-ref --heads, --tags, --head, pattern' ' +test_expect_success 'show-ref --branches, --tags, --head, pattern' ' for branch in B main side do echo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1 - done >expect.heads && - git show-ref --heads >actual && - test_cmp expect.heads actual && + done >expect.branches && + git show-ref --branches >actual && + test_cmp expect.branches actual && for tag in A B C do@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' ' git show-ref --tags >actual && test_cmp expect.tags actual && - cat expect.heads expect.tags >expect && - git show-ref --heads --tags >actual && + cat expect.branches expect.tags >expect && + git show-ref --branches --tags >actual && test_cmp expect actual && { echo $(git rev-parse HEAD) HEAD && - cat expect.heads expect.tags + cat expect.branches expect.tags } >expect && - git show-ref --heads --tags --head >actual && + git show-ref --branches --tags --head >actual && test_cmp expect actual && {@@ -165,6 +165,14 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' ' test_cmp expect actual ' +test_expect_success 'show-ref --heads is deprecated and hidden' ' + test_expect_code 129 git show-ref -h >short-help && + test_grep ! -e --heads short-help && + git show-ref --heads >actual 2>warning && + test_grep ! deprecated warning && + test_cmp expect.branches actual +' + test_expect_success 'show-ref --verify HEAD' ' echo $(git rev-parse HEAD) HEAD >expect && git show-ref --verify HEAD >actual && --
Quoted 1 line
2.45.2-409-g7b0defb391
If we are renaming --heads to --branches, should --head also be renamed?
Other than that question, this patch and series looks good to me.
Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads
Quoted 1 line · Elijah Newren
If we are renaming --heads to --branches, should --head also be renamed?
I do not think so. It is specifically about HEAD (the thing that lives above refs/ hierarchy, historically implemented as a file whose name is "HEAD" that is directly inside $GIT_DIR).
Thanks.
Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads
Quoted 10 lines · Junio C Hamano
Quoted 1 line · Elijah Newren
If we are renaming --heads to --branches, should --head also be renamed?
I do not think so. It is specifically about HEAD (the thing that lives above refs/ hierarchy, historically implemented as a file whose name is "HEAD" that is directly inside $GIT_DIR).
Thanks.
I'm fine if we don't want to rename it, but I don't quite follow this particular rationale. The logic you use here seems to be about internal details ("it's the file named HEAD") and ignores what users might refer to it as ("current branch"), whereas --branches ignored the internal details ("the files under refs/heads/") and instead concentrates on what users might refer to them as ("branches") and used that as the rationale for renaming.
That said, I've almost never seen users use --head (and haven't used it myself), whereas asking for heads/branches is much more common, and I'm very happy with the change from --heads to --branches. Also, even if we do agree --head should be renamed, I'd be fine with punting it to later in order to get this improvement in now...it just seemed like a small inconsistency that I thought was worth pointing out.
Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads
Quoted 21 lines · Elijah Newren
Quoted 10 lines · Junio C Hamano
Quoted 1 line · Elijah Newren
If we are renaming --heads to --branches, should --head also be renamed?
I do not think so. It is specifically about HEAD (the thing that lives above refs/ hierarchy, historically implemented as a file whose name is "HEAD" that is directly inside $GIT_DIR).
Thanks.
I'm fine if we don't want to rename it, but I don't quite follow this particular rationale. The logic you use here seems to be about internal details ("it's the file named HEAD") and ignores what users might refer to it as ("current branch"), whereas --branches ignored the internal details ("the files under refs/heads/") and instead concentrates on what users might refer to them as ("branches") and used that as the rationale for renaming.
Quoted 6 lines
That said, I've almost never seen users use --head (and haven't used it myself), whereas asking for heads/branches is much more common, and I'm very happy with the change from --heads to --branches. Also, even if we do agree --head should be renamed, I'd be fine with punting it to later in order to get this improvement in now...it just seemed like a small inconsistency that I thought was worth pointing out.
...or maybe my argument breaks down because HEAD is more prominent and tends to be used by users more (git reset --hard HEAD, git checkout HEAD~1), and thus there's an argument it already is somewhat aligned with user terminology?
Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads
Quoted 4 lines · Elijah Newren
...or maybe my argument breaks down because
HEADis more prominent and tends to be used by users more (git reset --hard HEAD,git checkout HEAD~1), and thus there's an argument it already is somewhat aligned with user terminology?
Yeah, you are correct to say that HEAD is a lot more prominent than "refs/heads/". "git branch --list" does not expose the "refs/heads/" part (but "git for-each-ref" does), but you'd see HEAD in many places (e.g. "git show -s <RETURN>" gives the --decorate output that says "HEAD -> master" etc.).
Of course we _could_ plan to rename "HEAD" to something else, like "CURRENT" and deal with the fallout, and then rename "refs/heads/" to "refs/branches/", but for what cost to achieve what benefit? The tradeoff does not look all that good to me.
So I'd say renaming --heads to --branches would probably be a good place to stop, at least for now.
Re: [PATCH v2 0/3] Branches are branches and not heads
In reply to Junio C HamanoQuoted 16 lines · Junio C Hamano
tl;dr for those who did read v1: v2 does not warn when deprecated variants are used.
----------------------Back when Git started, we used the word "head" to mean the tip of possibly multiple histories, and that is where the name of the hierarchy .git/refs/heads/ came from. But these days we call these entities "branches" in human terms, and "head" is still used to refer to the tip of the history each of these branches represent.
When asking "git ls-remote" or "git show-ref" to limit their output to branches (as opposed to showing any ref), we use "--heads" for historical reasons, but give the option a more human friendly name "--branches", and demote "--heads" to the status of a deprecated synonym.
Quoted 4 lines
We do not plan to remove "--heads" or "-h" yet, but we may want to do so at the Git 3.0 boundary, in which case we will need to start advertising upcoming removal with an extra warning when they are used. But let's not start annoying users for now.
This version looks good to me, thanks!
Patrick