Commands using -h as an option don't work consistently

Commands using -h as an option don't work consistently

[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 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

[Junio C Hamano]

Kevin Day <toasty@dragondata.com> writes:

> 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.

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.

> 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.

> 2) Change -h to -H or something, but this breaks backwards compatibility

As you said it yourself, this is a non starter.

> 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

[Kevin Day]

> On May 29, 2024, at 5:22 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> 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.

> Let's see what improvements you bring to the table.
> 
>> 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.


> 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.

> 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.

[RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 5441 bytes --]

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---

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

diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md
new file mode 100644
index 0000000000..94d77a8af1
--- /dev/null
+++ b/Documentation/UpcomingBreakingChanges.md
@@ -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. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
+    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
+
+  - The default hash function for new repositories will be changed from "sha1"
+    to "sha256".
+
+  - The default ref backend for new repositories will be changed from "files" to
+    "reftable".
+
+### Removals
+
+ - git-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.
-- 
2.45.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Johannes Schindelin]

Hi Patrick,

On Tue, 7 May 2024, Patrick Steinhardt wrote:

> 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.

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.

> The document is _not_ intended to cast every single discussion into
> stone. It is supposed to be a living document that may change over time
> when there are good reasons for it to change.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>
> 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
>
> diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md
> new file mode 100644
> index 0000000000..94d77a8af1
> --- /dev/null
> +++ b/Documentation/UpcomingBreakingChanges.md
> @@ -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. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
> +    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
> +
> +  - The default hash function for new repositories will be changed from "sha1"
> +    to "sha256".
> +
> +  - The default ref backend for new repositories will be changed from "files" to
> +    "reftable".
> +
> +### Removals
> +
> + - git-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).

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.

> +
> + - "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

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3762 bytes --]

On Tue, May 07, 2024 at 12:38:31PM +0200, Johannes Schindelin wrote:
> Hi Patrick,
> 
> On Tue, 7 May 2024, Patrick Steinhardt wrote:
> 
> > 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.
> 
> 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]
> > + - 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.

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.

> > + - "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.

Agreed!

> - 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.

> - 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.

Fair.

I'd be happy to add these in v2 unless folks disagree.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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.

> 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.

> 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.

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2635 bytes --]

On Tue, May 07, 2024 at 03:02:09PM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > 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.

Agreed, I'll something along these 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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> 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.

> 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?

Re: [RFC PATCH] docs: document upcoming breaking changes

[Dragan Simic]

Hello Patrick,

On 2024-05-08 15:54, Patrick Steinhardt wrote:
> 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.

[1] 
https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 850 bytes --]

On Wed, May 08, 2024 at 05:59:01PM +0200, Dragan Simic wrote:
> Hello Patrick,
> 
> On 2024-05-08 15:54, Patrick Steinhardt wrote:
> > 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.
> 
> [1]
> https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Dragan Simic]

Hello Patrick,

On 2024-05-10 13:36, Patrick Steinhardt wrote:
> On Wed, May 08, 2024 at 05:59:01PM +0200, Dragan Simic wrote:
>> On 2024-05-08 15:54, Patrick Steinhardt wrote:
>> > 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.
>> 
>> [1] 
>> https://lore.kernel.org/git/3d84f2eac9b03eda814332d73b5d5ba6@manjaro.org/
> 
> 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.

Re: [RFC PATCH] docs: document upcoming breaking changes

[Phillip Wood]

Hi Patrick

Thanks putting this together, I think it will be a useful way discussing 
deprecations and removals.

On 07/05/2024 09:27, Patrick Steinhardt wrote:
> 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.

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

> +### 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.

> + - 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

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3055 bytes --]

On Wed, May 08, 2024 at 02:15:11PM +0100, Phillip Wood wrote:
> Hi Patrick
> 
> Thanks putting this together, I think it will be a useful way discussing
> deprecations and removals.
> 
> On 07/05/2024 09:27, Patrick Steinhardt wrote:
> > 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.
> 
> 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.

> > +### 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.
> 
> > + - 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] docs: document upcoming breaking changes

[Justin Tobler]

On 24/05/07 10:27AM, Patrick Steinhardt wrote:

+### 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.

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

Re: [RFC PATCH] docs: document upcoming breaking changes

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> writes:

> 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}...topic

is 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.

Re: [RFC PATCH] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2339 bytes --]

On Thu, May 09, 2024 at 09:47:49PM -0700, Junio C Hamano wrote:
> Justin Tobler <jltobler@gmail.com> writes:
> 
> > 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}...topic
> 
> is 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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[RFC PATCH v2] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 15437 bytes --]

Over time, Git has grown quite a lot. With this evolution, many ideas
that were sensible at the time they were introduced are not anymore and
are thus considered to be deprecated. And while some deprecations may be
noted in manpages, most of them are actually deprecated in the "hive
mind" of the Git community, only.

Introduce a new document that lists upcoming breaking changes, but also
deprecations which we are not willing to go through with, to address
this issue. This document serves multiple purposes:

  - It is a way to facilitate discussion around proposed deprecations.

  - It allows users to learn about deprecations and speak up in case
    they have good reasons why a certain feature should not be
    deprecated.

  - It states intent and documents where the Git project wants to go,
    both in the case where we want to deprecate, but also in the case
    where we don't want to deprecate a specific feature.

The document is _not_ intended to cast every single discussion into
stone. It is supposed to be a living document that may change over time
when there are good reasons for it to change.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---

I have tried to accommodate for all feedback to v1. Most notably:

  - I have introduced a new section that documents concepts that are
    _not_ to be deprecated. The intent is to capture discussions around
    proposed deprecations where we ultimately decide that we do not
    (yet) want to deprecate it.

  - I have added some more proposed deprecations. As before, all of this
    is up for discussion and I do not want to force any of the proposed
    deprecations onto anybody.

  - I have dropped the "$GITDIR/hooks" deprecation item for now. It is
    premature to have it at this point in time given that the
    config-based approach isn't even close to landing.

Patrick

Range-diff against v1:
1:  a78d68ecc2 ! 1:  2ef53ff98b docs: document upcoming breaking changes
    @@ Commit message
         noted in manpages, most of them are actually deprecated in the "hive
         mind" of the Git community, only.
     
    -    Introduce a new document that lists upcoming breaking changes to address
    +    Introduce a new document that lists upcoming breaking changes, but also
    +    deprecations which we are not willing to go through with, to address
         this issue. This document serves multiple purposes:
     
           - It is a way to facilitate discussion around proposed deprecations.
    @@ Commit message
             they have good reasons why a certain feature should not be
             deprecated.
     
    -      - It states intent and documents where the Git project wants to go.
    +      - It states intent and documents where the Git project wants to go,
    +        both in the case where we want to deprecate, but also in the case
    +        where we don't want to deprecate a specific feature.
     
         The document is _not_ intended to cast every single discussion into
         stone. It is supposed to be a living document that may change over time
    @@ Documentation/UpcomingBreakingChanges.md (new)
     @@
     +# Upcoming breaking changes
     +
    ++The Git project aims to ensure backwards compatibility to the best extent
    ++possible. Minor releases will not break backwards compatibility unless there is
    ++a very strong reason to do so, like for example a security vulnerability.
    ++
    ++Regardless of that, due to the age of the Git project, it is only natural to
    ++accumulate a backlog of backwards-incompatible changes that will eventually be
    ++required to keep the project aligned with a changing world. These changes fall
    ++into several categories:
    ++
    ++  - Changes to long established defaults.
    ++
    ++  - Concepts that have been replaced with a superior design.
    ++
    ++  - Concepts, commands, configuration or options that have been lacking in major
    ++    ways and that cannot be fixed.
    ++
    ++The Git project will thus irregularly release major versions that deliberately
    ++break backwards compatibility with older versions. This is done to ensure that
    ++Git remains relevant, safe and maintainable going forward. The release cadence
    ++of major versions is typically measured in multiple years.
    ++
     +The intent of this document is to track upcoming deprecations for the next major
    -+Git release. It is supposed to be a living document where proposed changes and
    ++Git release. Furthermore, this document also tracks what will _not_ be
    ++deprecated. This is done such that the outcome of discussions documente both
    ++when the discussion favors deprecation, but also when it rejects a deprecation.
    ++
    ++It is supposed to be a living document where proposed changes and
     +deprecations are up for discussion.
     +
     +## Git 3.0
    @@ Documentation/UpcomingBreakingChanges.md (new)
     +
     +### Removals
     +
    -+ - git-config(1) has learned to use subcommands that replace implicit actions
    -+   (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config
    -+   --unset-all`). The actions will be removed in favor of subcommands.
    -+   Prerequisite for this change is that the new subcommands have been out for at
    -+   least for two years to give script authors time to migrate.
    -+
    -+   Cf. <ZjiL7vu5kCVwpsLd@tanuki>.
    -+
     + - git-http-push(1) can be used to push objects to a remote repository via
     +   HTTP/DAV. Support for write support via WebDAV is not in widespread use
     +   nowadays anymore and will be removed together with the command.
    @@ Documentation/UpcomingBreakingChanges.md (new)
     +   shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This
     +   concept has long been replaced by remotes and will thus be removed.
     +
    -+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. It will
    -+   be removed in favor of git-blame(1).
    -+
     + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
     +   HTTP server. These scripts have been unmaintained for a significant amount of
     +   time and will be removed.
    @@ Documentation/UpcomingBreakingChanges.md (new)
     +   very slow, hard to use and has many gotchas. It will thus be removed in favor
     +   of [git-filter-repo](https://github.com/newren/git-filter-repo).
     +
    -+ - githooks(5) can be installed by placing them into `$GIT_DIR/hooks/`. This has
    -+   been a source of multiple remote code execution vulnerabilities. The feature
    -+   will be removed in favor of `core.hooksDirectory` and the new config-based
    -+   hooks.
    ++ - The "dashed form", i.e. support for calling `git-<command>` instead of
    ++   `git <command>` in scripts, has been deprecated for a long time and will be
    ++   removed.
    ++
    ++ - The command to import patches from Quilt seems to be used rarely, if
    ++   ever, and will be removed.
    ++
    ++ - Support for importing repositories from GNU Arch will be removed because
    ++   it would not appear to have any users.
    ++
    ++ - Support for interacting with CVS repositories (via `cvsimport`,
    ++   `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by
    ++   the number of times these commands have been mentioned recently. The
    ++   code has been essentially unmaintained, too, and will be removed.
    ++
    ++ - Support for grafting commits has long been superseded by git-replace(1).
    ++   Grafts are inferior to replacement refs as the mechanism can lead to
    ++   hard-to-diagnose problems when transferring objects between repositories.
    ++   They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
    ++   2014-03-05) and will be removed.
    ++
    ++## Superseded features that will not be deprecated
    ++
    ++Some features have gained newer replacements that aim to improve the design in
    ++certain ways. The fact that there is a replacement does not automatically mean
    ++that the old way of doing things will eventually be removed. This section tracks
    ++those superseded features.
    ++
    ++ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As
    ++   the maintenance burden of carrying both of these commands is negligible, both
    ++   commands will stay.
    ++
    ++ - git-restore(1) and git-switch(1) have been introduced as a replacement for
    ++   git-checkout(1). As git-checkout(1) is quite established, and as the benefit
    ++   of switching to git-restore(1) and git-switch(1) is contended, all three
    ++   commands will stay.
    ++
    ++ - git-config(1) has learned to use subcommands that replace implicit actions
    ++   (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config
    ++   --unset-all`). The action flags will not be removed in the next major Git
    ++   release as there likely exist a lot of scripts out there that use the old
    ++   syntax.
    ++
    ++   Cf. <ZjiL7vu5kCVwpsLd@tanuki>.

 Documentation/UpcomingBreakingChanges.md | 119 +++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 Documentation/UpcomingBreakingChanges.md

diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md
new file mode 100644
index 0000000000..8c7a5f2f38
--- /dev/null
+++ b/Documentation/UpcomingBreakingChanges.md
@@ -0,0 +1,119 @@
+# Upcoming breaking changes
+
+The Git project aims to ensure backwards compatibility to the best extent
+possible. Minor releases will not break backwards compatibility unless there is
+a very strong reason to do so, like for example a security vulnerability.
+
+Regardless of that, due to the age of the Git project, it is only natural to
+accumulate a backlog of backwards-incompatible changes that will eventually be
+required to keep the project aligned with a changing world. These changes fall
+into several categories:
+
+  - Changes to long established defaults.
+
+  - Concepts that have been replaced with a superior design.
+
+  - Concepts, commands, configuration or options that have been lacking in major
+    ways and that cannot be fixed.
+
+The Git project will thus irregularly release major versions that deliberately
+break backwards compatibility with older versions. This is done to ensure that
+Git remains relevant, safe and maintainable going forward. The release cadence
+of major versions is typically measured in multiple years.
+
+The intent of this document is to track upcoming deprecations for the next major
+Git release. Furthermore, this document also tracks what will _not_ be
+deprecated. This is done such that the outcome of discussions documente both
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+It is supposed to be a living document where proposed changes and
+deprecations are up for discussion.
+
+## Git 3.0
+
+### Changes
+
+  - The default initial branch name will be changed from "master" to "main".
+
+    Cf. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
+    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
+
+  - The default hash function for new repositories will be changed from "sha1"
+    to "sha256".
+
+  - The default ref backend for new repositories will be changed from "files" to
+    "reftable".
+
+### Removals
+
+ - git-http-push(1) can be used to push objects to a remote repository via
+   HTTP/DAV. Support for write support via WebDAV is not in widespread use
+   nowadays anymore and will be removed together with the command.
+
+ - The dumb HTTP protocol can be used to serve repositories via a plain HTTP
+   server like Apache. The protocol has not seen any updates recently and is
+   neither compatible with alternative hash functions nor with alternative ref
+   backends. It will thus be removed.
+
+ - git-update-server-info(1) generates data required when serving data via the
+   dumb HTTP protocol. Given the removal of that protocol, it serves no purpose
+   anymore and will be removed together with the protocol. This includes the
+   "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the
+   `git repack -n` flag.
+
+ - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify
+   shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This
+   concept has long been replaced by remotes and will thus be removed.
+
+ - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
+   HTTP server. These scripts have been unmaintained for a significant amount of
+   time and will be removed.
+
+ - git-filter-branch(1) can be used to rewrite history of a repository. It is
+   very slow, hard to use and has many gotchas. It will thus be removed in favor
+   of [git-filter-repo](https://github.com/newren/git-filter-repo).
+
+ - The "dashed form", i.e. support for calling `git-<command>` instead of
+   `git <command>` in scripts, has been deprecated for a long time and will be
+   removed.
+
+ - The command to import patches from Quilt seems to be used rarely, if
+   ever, and will be removed.
+
+ - Support for importing repositories from GNU Arch will be removed because
+   it would not appear to have any users.
+
+ - Support for interacting with CVS repositories (via `cvsimport`,
+   `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by
+   the number of times these commands have been mentioned recently. The
+   code has been essentially unmaintained, too, and will be removed.
+
+ - Support for grafting commits has long been superseded by git-replace(1).
+   Grafts are inferior to replacement refs as the mechanism can lead to
+   hard-to-diagnose problems when transferring objects between repositories.
+   They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
+   2014-03-05) and will be removed.
+
+## Superseded features that will not be deprecated
+
+Some features have gained newer replacements that aim to improve the design in
+certain ways. The fact that there is a replacement does not automatically mean
+that the old way of doing things will eventually be removed. This section tracks
+those superseded features.
+
+ - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As
+   the maintenance burden of carrying both of these commands is negligible, both
+   commands will stay.
+
+ - git-restore(1) and git-switch(1) have been introduced as a replacement for
+   git-checkout(1). As git-checkout(1) is quite established, and as the benefit
+   of switching to git-restore(1) and git-switch(1) is contended, all three
+   commands will stay.
+
+ - git-config(1) has learned to use subcommands that replace implicit actions
+   (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config
+   --unset-all`). The action flags will not be removed in the next major Git
+   release as there likely exist a lot of scripts out there that use the old
+   syntax.
+
+   Cf. <ZjiL7vu5kCVwpsLd@tanuki>.
-- 
2.45.GIT


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 4948 bytes --]

Patrick Steinhardt <ps@pks.im> writes:

[snip]

> +### Removals
> +
> + - git-http-push(1) can be used to push objects to a remote repository via
> +   HTTP/DAV. Support for write support via WebDAV is not in widespread use
 > +   nowadays anymore and will be removed together with the command.
> +
> + - The dumb HTTP protocol can be used to serve repositories via a plain HTTP
> +   server like Apache. The protocol has not seen any updates recently and is
> +   neither compatible with alternative hash functions nor with alternative ref
> +   backends. It will thus be removed.
> +
> + - git-update-server-info(1) generates data required when serving data via the
> +   dumb HTTP protocol. Given the removal of that protocol, it serves no purpose
> +   anymore and will be removed together with the protocol. This includes the
> +   "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the
> +   `git repack -n` flag.
> +
> + - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify
> +   shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This
> +   concept has long been replaced by remotes and will thus be removed.
> +
> + - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
> +   HTTP server. These scripts have been unmaintained for a significant amount of
> +   time and will be removed.
> +
> + - git-filter-branch(1) can be used to rewrite history of a repository. It is
> +   very slow, hard to use and has many gotchas. It will thus be removed in favor
> +   of [git-filter-repo](https://github.com/newren/git-filter-repo).
> +
> + - The "dashed form", i.e. support for calling `git-<command>` instead of
> +   `git <command>` in scripts, has been deprecated for a long time and will be
> +   removed.
> +
> + - The command to import patches from Quilt seems to be used rarely, if
> +   ever, and will be removed.
> +
> + - Support for importing repositories from GNU Arch will be removed because
> +   it would not appear to have any users.
> +
> + - Support for interacting with CVS repositories (via `cvsimport`,
> +   `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by
> +   the number of times these commands have been mentioned recently. The
> +   code has been essentially unmaintained, too, and will be removed.
> +
> + - Support for grafting commits has long been superseded by git-replace(1).
> +   Grafts are inferior to replacement refs as the mechanism can lead to
> +   hard-to-diagnose problems when transferring objects between repositories.
> +   They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
> +   2014-03-05) and will be removed.

I think it is worthwhile also looking at the number of commands we have
and see that some of these could possibly be marked deprecated, maybe
removal could follow too:

* add, stage
Here, `stage` is synonym and can be just dropped.

* prune, prune-packed
`prune-packed` prunes objects from packed files, perhaps could be a
sub-command on the existing `prune` command.

* annotate, blame, pickaxe
You've mentioned `annotate` below, but we could also remove `pickaxe`.

* log, whatchanged, shortlog
Here `log` already handles what the other two commands do.

* for-each-ref, show-ref
These two commands do very similar things, i.e. list references. Both
diverge in the features they provided, but its not clear why we have the
two.

* verify-commit, verify-pack, verify-tag
These could probably be subcommands under the verify command.

* diff, diff-files, diff-index, diff-tree
Here, `diff` seems to handle everything that the others do.

> +## Superseded features that will not be deprecated
> +
> +Some features have gained newer replacements that aim to improve the design in
> +certain ways. The fact that there is a replacement does not automatically mean
> +that the old way of doing things will eventually be removed. This section tracks
> +those superseded features.
> +
> + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As
> +   the maintenance burden of carrying both of these commands is negligible, both
> +   commands will stay.
> +
>

While maintenance burden is an issue for us. There is also an user
experience point of view, having similar commands doing similar
operations is often a cause for confusion.

> + - git-restore(1) and git-switch(1) have been introduced as a replacement for
> +   git-checkout(1). As git-checkout(1) is quite established, and as the benefit
> +   of switching to git-restore(1) and git-switch(1) is contended, all three
> +   commands will stay.
> +
> + - git-config(1) has learned to use subcommands that replace implicit actions
> +   (e.g. `git config foo.bar baz`) as well as the action flags (e.g. `git config
> +   --unset-all`). The action flags will not be removed in the next major Git
> +   release as there likely exist a lot of scripts out there that use the old
> +   syntax.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4867 bytes --]

On Tue, May 14, 2024 at 06:48:38AM -0400, Karthik Nayak wrote:
> Patrick Steinhardt <ps@pks.im> writes:
[snip]
> I think it is worthwhile also looking at the number of commands we have
> and see that some of these could possibly be marked deprecated, maybe
> removal could follow too:
> 
> * add, stage
> Here, `stage` is synonym and can be just dropped.

I wonder whether there are any arguments in favor of git-stage(1). I
myself haven't even been aware of this command and have never seen it
out there in the wild. Which would be an indicator that we can safely
remove it.

Comments?

> * prune, prune-packed
> `prune-packed` prunes objects from packed files, perhaps could be a
> sub-command on the existing `prune` command.

I think we should refrain from adding anything to this document that is
not yet feasible. In other words, once git-prune(1) learns to prune
packed objects we may want to think about whether git-prune-packed(1)
can be deprecated, but not beforehand.

> * annotate, blame, pickaxe
> You've mentioned `annotate` below, but we could also remove `pickaxe`.

I think most oldtimers use git-blame(1), whereas git-annotate(1) has
been introduced to make the command less judgemental. I'd thus say that
this falls into the category of commands that we wouldn't want to
deprecate because they are both used.

For git-pickaxe(1) it's a bit of a different story though. We do not
even have a manpage for it anymore. I wouldn't mind deprecating that one
fully.

> * log, whatchanged, shortlog
> Here `log` already handles what the other two commands do.

Does git-log(1) really support everything that git-shortlog(1) does? If
so then this would be entirely new to me, but you never know with Git :)

git-whatchanged(1) has been essentially deprecated already. So that may
be a worthwhile addition.

> * for-each-ref, show-ref
> These two commands do very similar things, i.e. list references. Both
> diverge in the features they provided, but its not clear why we have the
> two.

True, they have clear overlap and both are part of plumbing. I never
quite know which one to pick. But git-show-ref(1) handles things that
git-for-each-ref(1) doesn't ("--exists", "--verify") and the other way
round ("--stdin", "--sort=", many more).

Honestly, I think that both of these are not ideal. I think we should
think bigger in this context and introduce a new command with proper
subcommands to make the whole story around refs more coherent and
discoverable:

  # Replaces git-show-ref(1) and git-for-each-ref(1).
  $ git refs list

  # Replaces `git show-ref --exists`.
  $ git refs exist

  # Replaces `git show-ref --verify <ref>`.
  $ git refs show

  # Replaces git-symbolic-ref(1) to show a ref.
  $ git refs resolve

  # Replaces git-pack-ref(1).
  $ git refs pack

  # Replaces git-update-ref(1).
  $ git refs write

  # Replaces git-check-ref-format(1).
  $ git refs check-format

This is of course a much larger topic and something that is very much up
for discussion. But in any case, it indicates that a deprecation would
be premature at this point in time.

> * verify-commit, verify-pack, verify-tag
> These could probably be subcommands under the verify command.

Same here -- as we don't have the command yet, I think it's premature
the old commands to a list of deprecations.

> * diff, diff-files, diff-index, diff-tree
> Here, `diff` seems to handle everything that the others do.

These do have different scopes though. While git-diff(1) is part of
porcelain, the others are all part of the plumbing layer. As such, we
provide different guarantees. In practice it's likely a different story
though as my assumption is that git-diff(1) will be used in scripts a
lot. But in any case, I think that this is a separate topic that would
first need some discussion.

> > +## Superseded features that will not be deprecated
> > +
> > +Some features have gained newer replacements that aim to improve the design in
> > +certain ways. The fact that there is a replacement does not automatically mean
> > +that the old way of doing things will eventually be removed. This section tracks
> > +those superseded features.
> > +
> > + - git-annotate(1) is an alias for git-blame(1) with the `-c` flag. As
> > +   the maintenance burden of carrying both of these commands is negligible, both
> > +   commands will stay.
> > +
> >
> 
> While maintenance burden is an issue for us. There is also an user
> experience point of view, having similar commands doing similar
> operations is often a cause for confusion.

In this case I think it's okay as the documentation of git-annotate(1)
clearly states that it is the same as git-blame(1). But it is certainly
true that synonyms also add to perceived complexity of Git.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> * annotate, blame, pickaxe
>> You've mentioned `annotate` below, but we could also remove `pickaxe`.
>
> I think most oldtimers use git-blame(1), whereas git-annotate(1) has
> been introduced to make the command less judgemental. I'd thus say that
> this falls into the category of commands that we wouldn't want to
> deprecate because they are both used.

Personally I do not think blame is "judgemental" in the first place,
and I do not think being "judgemental" is bad to begin with.

"git annotate" was there first as a Perl script, added by c65e8987
(Add git-annotate, a tool for assigning blame., 2006-02-20).  It is
intersting to note that "annotate" was advertised as a tool for
assigning blame.

"git blame" was written almost around the same time but with "-c"
compatiblity mode to mimick "git annotate", added by cbfb73d7 (Add
git-blame, a tool for assigning blame., 2006-02-21).

A healthy competition between "annotate" and "blame" continued until
f789e347 (Remove git-annotate.perl and create a builtin-alias for
git-blame, 2006-10-09) retired the "git annotate" Perl script, and
replaced it with an invocation of "git blame -c".

"git blame" was rewritten under the codename "git pickaxe" (cf.
https://lore.kernel.org/git/7vr6xddm7h.fsf@assigned-by-dhcp.cox.net/),
and was released at cee7f245 (git-pickaxe: blame rewritten.,
2006-10-19).  acca687f (git-pickaxe: retire pickaxe, 2006-11-08)
made it take over the old implementation of "git blame".

The name "pickaxe" can be easily removed, as the log message of
acca687f already said back then.  As everybody noticed, it is not
even documented.

>> * log, whatchanged, shortlog
>> Here `log` already handles what the other two commands do.
>
> Does git-log(1) really support everything that git-shortlog(1) does?

Of course not.  The filtering behaviour of shortlog is unique to the
command.

> This is of course a much larger topic and something that is very much up
> for discussion. But in any case, it indicates that a deprecation would
> be premature at this point in time.

Yes, please exclude anything that needs new development while
discussing this topic.  Anybody jumping into this discussion should
take the word "upcoming" in the title more seriously.

So I won't talk about unifying "describe" and "name-rev" somehow ;-)

>> * verify-commit, verify-pack, verify-tag
>> These could probably be subcommands under the verify command.
>
> Same here -- as we don't have the command yet, I think it's premature
> the old commands to a list of deprecations.
>
>> * diff, diff-files, diff-index, diff-tree
>> Here, `diff` seems to handle everything that the others do.

No, diff-files, diff-index and diff-tree can do their thing
without getting broken by end-user configuration.  Writing your
script with "git diff" and you can keep both halves.

Re: [RFC PATCH v2] docs: document upcoming breaking changes

[Dragan Simic]

Hello Karthik,

On 2024-05-14 12:48, Karthik Nayak wrote:
> I think it is worthwhile also looking at the number of commands we have
> and see that some of these could possibly be marked deprecated, maybe
> removal could follow too:
> 
> * log, whatchanged, shortlog
> Here `log` already handles what the other two commands do.

I haven't used "git shortlog" myself, but I think it sees a fair amount
of use in various project maintainer reports.  Thus, I don't think it 
should
be marked as deprecated.

[PATCH v3] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 8905 bytes --]

Over time, Git has grown quite a lot. With this evolution, many ideas
that were sensible at the time they were introduced are not anymore and
are thus considered to be deprecated. And while some deprecations may be
noted in manpages, most of them are actually deprecated in the "hive
mind" of the Git community, only.

Introduce a new document that lists upcoming breaking changes, but also
deprecations which we are not willing to go through with, to address
this issue. This document serves multiple purposes:

  - It is a way to facilitate discussion around proposed deprecations.

  - It allows users to learn about deprecations and speak up in case
    they have good reasons why a certain feature should not be
    deprecated.

  - It states intent and documents where the Git project wants to go,
    both in the case where we want to deprecate, but also in the case
    where we don't want to deprecate a specific feature.

The document is _not_ intended to cast every single discussion into
stone. It is supposed to be a living document that may change over time
when there are good reasons for it to change.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---

I'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

diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md
new file mode 100644
index 0000000000..d057ef7cb3
--- /dev/null
+++ b/Documentation/UpcomingBreakingChanges.md
@@ -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. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
+    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
+
+  - The default hash function for new repositories will be changed from "sha1"
+    to "sha256".
+
+  - The default ref backend for new repositories will be changed from "files" to
+    "reftable".
+
+### Removals
+
+ - git-http-push(1) can be used to push objects to a remote repository via
+   HTTP/DAV. Support for write support via WebDAV is not in widespread use
+   nowadays anymore and will be removed together with the command.
+
+ - The dumb HTTP protocol can be used to serve repositories via a plain HTTP
+   server like Apache. The protocol has not seen any updates recently and is
+   neither compatible with alternative hash functions nor with alternative ref
+   backends. It will thus be removed.
+
+ - git-update-server-info(1) generates data required when serving data via the
+   dumb HTTP protocol. Given the removal of that protocol, it serves no purpose
+   anymore and will be removed together with the protocol. This includes the
+   "receive.updateServerInfo" and "repack.updateServerInfo" config keys and the
+   `git repack -n` flag.
+
+ - `$GIT_DIR/branches/` and `$GIT_DIR/remotes/` can be used to specify
+   shorthands for URLs for git-fetch(1), git-pull(1) and git-push(1). This
+   concept has long been replaced by remotes and will thus be removed.
+
+ - "gitweb" and git-instaweb(1) can be used to browse Git repositories via an
+   HTTP server. These scripts have been unmaintained for a significant amount of
+   time and will be removed.
+
+ - git-filter-branch(1) can be used to rewrite history of a repository. It is
+   very slow, hard to use and has many gotchas. It will thus be removed in favor
+   of [git-filter-repo](https://github.com/newren/git-filter-repo).
+
+ - The "dashed form", i.e. support for calling `git-<command>` instead of
+   `git <command>` in scripts, has been deprecated for a long time and will be
+   removed.
+
+ - The command to import patches from Quilt seems to be used rarely, if
+   ever, and will be removed.
+
+ - Support for importing repositories from GNU Arch will be removed because
+   it would not appear to have any users.
+
+ - Support for interacting with CVS repositories (via `cvsimport`,
+   `cvsexportcommit` and `cvsserver`) is of dubious use by now, judging by
+   the number of times these commands have been mentioned recently. The
+   code has been essentially unmaintained, too, and will be removed.
+
+ - Support for grafting commits has long been superseded by git-replace(1).
+   Grafts are inferior to replacement refs as the mechanism can lead to
+   hard-to-diagnose problems when transferring objects between repositories.
+   They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
+   2014-03-05) and will be removed.
+
+ - 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
-- 
2.45.1.246.gb9cfe4845c.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] docs: document upcoming breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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?

>  Documentation/UpcomingBreakingChanges.md | 122 +++++++++++++++++++++++
>  1 file changed, 122 insertions(+)
>  create mode 100644 Documentation/UpcomingBreakingChanges.md
>
> diff --git a/Documentation/UpcomingBreakingChanges.md b/Documentation/UpcomingBreakingChanges.md
> new file mode 100644
> index 0000000000..d057ef7cb3
> --- /dev/null
> +++ b/Documentation/UpcomingBreakingChanges.md
> @@ -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.

OK.

> +## 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?

> +### Changes
> +
> +  - The default initial branch name will be changed from "master" to "main".
> +
> +    Cf. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
> +    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.

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.

> +  - 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.

"remotes" -> "the 'remotes.*.*' configuration variables", perhaps?

> + - "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)?

> + - 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.

> + - 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),...

> + - 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)?

> + - 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.

Re: [PATCH v3] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 8417 bytes --]

On Fri, May 24, 2024 at 10:27:13AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > 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]
> > +## 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.

> > +### Changes
> > +
> > +  - The default initial branch name will be changed from "master" to "main".
> > +
> > +    Cf. <pull.762.git.1605221038.gitgitgadget@gmail.com>,
> > +    <CAMP44s3BJ3dGsLJ-6yA-Po459=+m826KD9an4+P3qOY1vkbxZg@mail.gmail.com>.
> 
> 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.

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.

> > +  - 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.
> 
> "remotes" -> "the 'remotes.*.*' configuration variables", perhaps?
> 
> > + - "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)?

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.

> > + - 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.

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.

> > + - 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),...
> 
> > + - 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)?

That would certainly be helpful to give us a better base to argue.

> > + - 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.

Good idea, will do.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Commands using -h as an option don't work consistently

[Junio C Hamano]

Kevin Day <toasty@dragondata.com> writes:

>>> 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.

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> 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.

[PATCH 0/3] Branches are branches and not heads

[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.

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(-)

-- 
2.45.2-404-g9eaef5822c

[PATCH 1/3] refs: call branches branches

[Junio C Hamano]

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.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 builtin/ls-remote.c | 6 +++---
 connect.c           | 4 ++--
 remote.h            | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index e8d65ebbdc..9838de69c0 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -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);
diff --git a/connect.c b/connect.c
index 0d77737a53..cf84e631e9 100644
--- a/connect.c
+++ b/connect.c
@@ -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 */
diff --git a/remote.h b/remote.h
index dfd4837e60..02e330f42c 100644
--- a/remote.h
+++ b/remote.h
@@ -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);
-- 
2.45.2-404-g9eaef5822c

Re: [PATCH 1/3] refs: call branches branches

[Eric Sunshine]

On Mon, Jun 3, 2024 at 4:05 PM Junio C Hamano <gitster@pobox.com> wrote:
> 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.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
> @@ -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

[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 <gitster@pobox.com>
---
 Documentation/git-ls-remote.txt | 12 +++++++-----
 builtin/ls-remote.c             | 21 ++++++++++++++++++++-
 t/t5512-ls-remote.sh            | 30 +++++++++++++++++++++++++-----
 3 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index 1c4f696ab5..76c86c3ce4 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -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.
 
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index 9838de69c0..95fbb8b7b5 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -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")),
diff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh
index 5dbe107ce8..b9950ca361 100755
--- a/t/t5512-ls-remote.sh
+++ b/t/t5512-ls-remote.sh
@@ -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
 '
 
-- 
2.45.2-404-g9eaef5822c

Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads

[Rubén Justo]

On Mon, Jun 03, 2024 at 01:05:38PM -0700, Junio C Hamano wrote:
> 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 <gitster@pobox.com>
> ---
>  Documentation/git-ls-remote.txt | 12 +++++++-----
>  builtin/ls-remote.c             | 21 ++++++++++++++++++++-
>  t/t5512-ls-remote.sh            | 30 +++++++++++++++++++++++++-----
>  3 files changed, 52 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> index 1c4f696ab5..76c86c3ce4 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -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::

Perhaps we can avoid this 'single-letter' option, due to we're no giving
the same abbreviation for '--branches' in other places.

> +--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.
>  
> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
> index 9838de69c0..95fbb8b7b5 100644
> --- a/builtin/ls-remote.c
> +++ b/builtin/ls-remote.c
> @@ -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');

> +		*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")),
> diff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh
> index 5dbe107ce8..b9950ca361 100755
> --- a/t/t5512-ls-remote.sh
> +++ b/t/t5512-ls-remote.sh
> @@ -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
>  '
>  
> -- 
> 2.45.2-404-g9eaef5822c
> 

Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads

[Eric Sunshine]

On Mon, Jun 3, 2024 at 5:30 PM Rubén Justo <rjusto@gmail.com> wrote:
> On Mon, Jun 03, 2024 at 01:05:38PM -0700, Junio C Hamano wrote:
> > +     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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> 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

[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 <gitster@pobox.com>
---
 Documentation/git-show-ref.txt | 18 ++++++++++--------
 builtin/show-ref.c             | 33 ++++++++++++++++++++++++++-------
 t/t1403-show-ref.sh            | 22 ++++++++++++++--------
 3 files changed, 50 insertions(+), 23 deletions(-)

diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index ba75747005..616d919655 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -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`
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index 1c15421e60..6b69daeb66 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -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")),
diff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh
index 33fb7a38ff..b72ed70435 100755
--- a/t/t1403-show-ref.sh
+++ b/t/t1403-show-ref.sh
@@ -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 &&
-- 
2.45.2-404-g9eaef5822c

Re: [PATCH 0/3] Branches are branches and not heads

[Rubén Justo]

On Mon, Jun 03, 2024 at 01:05:36PM -0700, Junio C Hamano wrote:
> 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.

All of this sounds like a very sensible step, to me.

I've left a couple of nits;  none important. 

Thanks.

> 
> 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(-)
> 
> -- 
> 2.45.2-404-g9eaef5822c
> 

Re: [PATCH 0/3] Branches are branches and not heads

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1136 bytes --]

On Mon, Jun 03, 2024 at 11:32:18PM +0200, Rubén Justo wrote:
> On Mon, Jun 03, 2024 at 01:05:36PM -0700, Junio C Hamano wrote:
> > 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.
> 
> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 0/3] Branches are branches and not heads

[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.  

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 <gitster@pobox.com>
     
      ## 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 <gitster@pobox.com>
     
      ## 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
     +'
     +
-- 
2.45.2-409-g7b0defb391

[PATCH v2 1/3] refs: call branches branches

[Junio C Hamano]

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.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 builtin/ls-remote.c | 4 ++--
 connect.c           | 4 ++--
 remote.h            | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index e8d65ebbdc..65fb22a8a2 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -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);
diff --git a/connect.c b/connect.c
index 0d77737a53..cf84e631e9 100644
--- a/connect.c
+++ b/connect.c
@@ -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 */
diff --git a/remote.h b/remote.h
index dfd4837e60..02e330f42c 100644
--- a/remote.h
+++ b/remote.h
@@ -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);
-- 
2.45.2-409-g7b0defb391

[PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads

[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 <gitster@pobox.com>
---
 Documentation/git-ls-remote.txt | 12 +++++++-----
 builtin/ls-remote.c             |  7 +++++--
 t/t5512-ls-remote.sh            | 32 +++++++++++++++++++++++++++-----
 3 files changed, 39 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index 1c4f696ab5..76c86c3ce4 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -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.
 
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index 65fb22a8a2..69841ed49f 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -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")),
diff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh
index 5dbe107ce8..42e77eb5a9 100755
--- a/t/t5512-ls-remote.sh
+++ b/t/t5512-ls-remote.sh
@@ -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
 '
 
-- 
2.45.2-409-g7b0defb391

Re: [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2522 bytes --]

On Tue, Jun 04, 2024 at 03:01:44PM -0700, Junio C Hamano wrote:
> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
> index 65fb22a8a2..69841ed49f 100644
> --- a/builtin/ls-remote.c
> +++ b/builtin/ls-remote.c
> @@ -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")),
> diff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh
> index 5dbe107ce8..42e77eb5a9 100755
> --- a/t/t5512-ls-remote.sh
> +++ b/t/t5512-ls-remote.sh
> @@ -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
> +'

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> +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

[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 <gitster@pobox.com>
---
 Documentation/git-show-ref.txt | 18 ++++++++++--------
 builtin/show-ref.c             | 16 +++++++++-------
 t/t1403-show-ref.sh            | 24 ++++++++++++++++--------
 3 files changed, 35 insertions(+), 23 deletions(-)

diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index ba75747005..616d919655 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -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`
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index 1c15421e60..f634bc3e44 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -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")),
diff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh
index 33fb7a38ff..403f6b8f7d 100755
--- a/t/t1403-show-ref.sh
+++ b/t/t1403-show-ref.sh
@@ -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 &&
-- 
2.45.2-409-g7b0defb391

Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads

[Elijah Newren]

On Tue, Jun 4, 2024 at 10:02 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> 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 <gitster@pobox.com>
> ---
>  Documentation/git-show-ref.txt | 18 ++++++++++--------
>  builtin/show-ref.c             | 16 +++++++++-------
>  t/t1403-show-ref.sh            | 24 ++++++++++++++++--------
>  3 files changed, 35 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
> index ba75747005..616d919655 100644
> --- a/Documentation/git-show-ref.txt
> +++ b/Documentation/git-show-ref.txt
> @@ -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`
> diff --git a/builtin/show-ref.c b/builtin/show-ref.c
> index 1c15421e60..f634bc3e44 100644
> --- a/builtin/show-ref.c
> +++ b/builtin/show-ref.c
> @@ -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")),
> diff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh
> index 33fb7a38ff..403f6b8f7d 100755
> --- a/t/t1403-show-ref.sh
> +++ b/t/t1403-show-ref.sh
> @@ -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 &&
> --
> 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

[Junio C Hamano]

Elijah Newren <newren@gmail.com> writes:

> 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

[Elijah Newren]

On Fri, Jun 14, 2024 at 9:21 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Elijah Newren <newren@gmail.com> writes:
>
> > 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

[Elijah Newren]

On Fri, Jun 14, 2024 at 9:34 PM Elijah Newren <newren@gmail.com> wrote:
>
> On Fri, Jun 14, 2024 at 9:21 PM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Elijah Newren <newren@gmail.com> writes:
> >
> > > 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.

...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

[Junio C Hamano]

Elijah Newren <newren@gmail.com> writes:

> ...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?

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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1143 bytes --]

On Tue, Jun 04, 2024 at 03:01:42PM -0700, Junio C Hamano wrote:
> 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.  
> 
> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 0/4] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1884 bytes --]

Hi,

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
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 1/4] docs: introduce document to announce breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4705 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 Documentation/BreakingChanges.md

diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
new file mode 100644
index 0000000000..d8a26c9bf9
--- /dev/null
+++ b/Documentation/BreakingChanges.md
@@ -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.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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 <ps@pks.im>
> ---
>  Documentation/BreakingChanges.md | 66 ++++++++++++++++++++++++++++++++
>  1 file changed, 66 insertions(+)
>  create mode 100644 Documentation/BreakingChanges.md
>
> diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
> new file mode 100644
> index 0000000000..d8a26c9bf9
> --- /dev/null
> +++ b/Documentation/BreakingChanges.md
> @@ -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 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]"?

> +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?

> +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.

> +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.

> +## 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"?

> +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.

> +### 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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4479 bytes --]

On Fri, May 31, 2024 at 09:51:25AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
[snip]
> > +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".
> 
> 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.

> > +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.

> 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.

> > +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]
> > +### 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?

Sure, makes sense.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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/7vprnzt7d5.fsf@gitster.siamese.dyndns.org/

Re: [PATCH v4 1/4] docs: introduce document to announce breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1305 bytes --]

On Mon, Jun 03, 2024 at 09:17:29AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > 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/7vprnzt7d5.fsf@gitster.siamese.dyndns.org/

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3130 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
index d8a26c9bf9..1b0a357e65 100644
--- a/Documentation/BreakingChanges.md
+++ b/Documentation/BreakingChanges.md
@@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+        <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+        <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
 ### Removals
 
 ## Superseded features that will not be deprecated
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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,"

> 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.

> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  Documentation/BreakingChanges.md | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>
> diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
> index d8a26c9bf9..1b0a357e65 100644
> --- a/Documentation/BreakingChanges.md
> +++ b/Documentation/BreakingChanges.md
> @@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
> +        <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
> +        <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?

>  ### Removals
>  
>  ## Superseded features that will not be deprecated

Thanks.

[PATCH v4 3/4] BreakingChanges: document removal of grafting

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1375 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
index 1b0a357e65..14c0972b08 100644
--- a/Documentation/BreakingChanges.md
+++ b/Documentation/BreakingChanges.md
@@ -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. <20140304174806.GA11561@sigill.intra.peff.net>.
+
 ## Superseded features that will not be deprecated
 
 Some features have gained newer replacements that aim to improve the design in
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2026 bytes --]

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.

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/BreakingChanges.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/BreakingChanges.md b/Documentation/BreakingChanges.md
index 14c0972b08..fb2c8ddf5a 100644
--- a/Documentation/BreakingChanges.md
+++ b/Documentation/BreakingChanges.md
@@ -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. <xmqqttjazwwa.fsf@gitster.g>,
+       <xmqqleeubork.fsf@gitster.g>,
+       <112b6568912a6de6672bf5592c3a718e@manjaro.org>.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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.
>
> 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

[Todd Zullinger]

Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
>> 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.
>>
>> 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. :)

-- 
Todd

Re: [PATCH v4 0/4] docs: document upcoming breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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.

Re: [PATCH v4 0/4] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 847 bytes --]

On Fri, May 31, 2024 at 01:43:30AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > 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.

Oh well, fair enough. I'll convert it to AsciiDoc in the next version,
but will wait a bit longer for feedback.

Thanks!

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v5 0/4] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 13072 bytes --]

Hi,

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
     
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
    - ## 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
     
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
    - ## 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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
    ++<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
    ++<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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
    -+        <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
    -+        <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
     
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
    - ## 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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
      
    - ### 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. <20140304174806.GA11561@sigill.intra.peff.net>.
     +
    -+   Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
    -+
    - ## 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.
     
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
    - ## 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. <xmqqttjazwwa.fsf@gitster.g>,
    -+       <xmqqleeubork.fsf@gitster.g>,
    -+       <112b6568912a6de6672bf5592c3a718e@manjaro.org>.
    ++* 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. <xmqqttjazwwa.fsf@gitster.g>,
    ++<xmqqleeubork.fsf@gitster.g>,
    ++<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v5 1/4] docs: introduce document to announce breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4955 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 71 +++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 Documentation/BreakingChanges.txt

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
new file mode 100644
index 0000000000..ddce7cc301
--- /dev/null
+++ b/Documentation/BreakingChanges.txt
@@ -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.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes

[Phillip Wood]

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.

On 03/06/2024 10:28, Patrick Steinhardt wrote:
> +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.


> 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".

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

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> +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".

> +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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 876 bytes --]

On Mon, Jun 03, 2024 at 09:24:48AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> > +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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3053 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index ddce7cc301..904857a636 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
 === Removals
 
 == Superseded features that will not be deprecated
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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 <ps@pks.im>
> ---
>  Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>
> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> index ddce7cc301..904857a636 100644
> --- a/Documentation/BreakingChanges.txt
> +++ b/Documentation/BreakingChanges.txt
> @@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
> +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
> +<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"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 4238 bytes --]

On Mon, Jun 03, 2024 at 09:36:59AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > 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 <ps@pks.im>
> > ---
> >  Documentation/BreakingChanges.txt | 24 ++++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> >
> > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> > index ddce7cc301..904857a636 100644
> > --- a/Documentation/BreakingChanges.txt
> > +++ b/Documentation/BreakingChanges.txt
> > @@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
> > +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
> > +<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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v5 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1354 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 904857a636..b5088dcce2 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 
 === 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. <20140304174806.GA11561@sigill.intra.peff.net>.
+
 == Superseded features that will not be deprecated
 
 Some features have gained newer replacements that aim to improve the design in
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v5 3/4] BreakingChanges: document removal of grafting

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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 <ps@pks.im>
> ---
>  Documentation/BreakingChanges.txt | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> index 904857a636..b5088dcce2 100644
> --- a/Documentation/BreakingChanges.txt
> +++ b/Documentation/BreakingChanges.txt
> @@ -87,6 +87,14 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
>  
>  === 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.

> +  They have been outdated since e650d0643b (docs: mark info/grafts as outdated,
> +  2014-03-05) and will be removed.
> ++
> +Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
> +
>  == 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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2023 bytes --]

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.

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index b5088dcce2..3c38676f49 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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. <xmqqttjazwwa.fsf@gitster.g>,
+<xmqqleeubork.fsf@gitster.g>,
+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v5 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> +
> +* 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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 948 bytes --]

On Mon, Jun 03, 2024 at 09:52:33AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > +
> > +* 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)?

Fair enough, let's add it like this. Thanks!

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v6 0/4] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 6381 bytes --]

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.

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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
     +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
     +<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. <20140304174806.GA11561@sigill.intra.peff.net>.
     +
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.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v6 1/4] docs: introduce document to announce breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 5175 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 74 +++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/BreakingChanges.txt

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
new file mode 100644
index 0000000000..36327b13b8
--- /dev/null
+++ b/Documentation/BreakingChanges.txt
@@ -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.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> +* 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.

> +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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 957 bytes --]

On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > +* 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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v6 1/4] docs: introduce document to announce breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> On Tue, Jun 04, 2024 at 10:59:52AM -0700, Junio C Hamano wrote:
>> Patrick Steinhardt <ps@pks.im> writes:
>> 
>> > +* 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.
>
> 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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> 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(-)

diff --git c/Documentation/BreakingChanges.txt w/Documentation/BreakingChanges.txt
index d977915e52..9c2c5f2328 100644
--- c/Documentation/BreakingChanges.txt
+++ w/Documentation/BreakingChanges.txt
@@ -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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 555 bytes --]

On Wed, Jun 05, 2024 at 10:52:10AM -0700, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
> > 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v6 2/4] BreakingChanges: document upcoming change from "sha1" to "sha256"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3326 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 36327b13b8..5d7e80aebb 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
 === Removals
 
 == Superseded features that will not be deprecated
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v6 3/4] BreakingChanges: document removal of grafting

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1474 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 5d7e80aebb..9fb6d8c78a 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -96,6 +96,18 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 
 === 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. <20140304174806.GA11561@sigill.intra.peff.net>.
+
 == Superseded features that will not be deprecated
 
 Some features have gained newer replacements that aim to improve the design in
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v6 3/4] BreakingChanges: document removal of grafting

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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 <ps@pks.im>
> ---
>  Documentation/BreakingChanges.txt | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
>
> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> index 5d7e80aebb..9fb6d8c78a 100644
> --- a/Documentation/BreakingChanges.txt
> +++ b/Documentation/BreakingChanges.txt
> @@ -96,6 +96,18 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
>  
>  === 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".

> +  ** 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. <20140304174806.GA11561@sigill.intra.peff.net>.
> +
>  == 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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2029 bytes --]

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.

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 9fb6d8c78a..0fd60a7776 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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. <xmqqttjazwwa.fsf@gitster.g>,
+<xmqqleeubork.fsf@gitster.g>,
+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
-- 
2.45.1.410.g58bac47f8e.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v6 0/4] docs: document upcoming breaking changes

[Phillip Wood]

Hi Patrick

On 04/06/2024 13:32, Patrick Steinhardt wrote:
> 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.

This version looks good to me

Thanks for writing this document

Phillip

> 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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
>       +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
>       +<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. <20140304174806.GA11561@sigill.intra.peff.net>.
>       +
> 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.

Re: [PATCH v6 0/4] docs: document upcoming breaking changes

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

> Hi Patrick
>
> On 04/06/2024 13:32, Patrick Steinhardt wrote:
>> 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.
>
> 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.

Re: [PATCH v6 0/4] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1162 bytes --]

On Tue, Jun 04, 2024 at 11:01:21AM -0700, Junio C Hamano wrote:
> Phillip Wood <phillip.wood123@gmail.com> writes:
> 
> > Hi Patrick
> >
> > On 04/06/2024 13:32, Patrick Steinhardt wrote:
> >> 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.
> >
> > 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v7 0/4] docs: document upcoming breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3302 bytes --]

Hi,

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
-- 
2.45.2.457.g8d94cfb545.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v7 1/4] docs: introduce document to announce breaking changes

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 5548 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 80 +++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 Documentation/BreakingChanges.txt

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
new file mode 100644
index 0000000000..cb7e30312f
--- /dev/null
+++ b/Documentation/BreakingChanges.txt
@@ -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.
-- 
2.45.2.457.g8d94cfb545.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v7 1/4] docs: introduce document to announce breaking changes

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> +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"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 3326 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index cb7e30312f..68ad42d805 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
 === Removals
 
 == Superseded features that will not be deprecated
-- 
2.45.2.457.g8d94cfb545.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v7 3/4] BreakingChanges: document removal of grafting

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1485 bytes --]

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 <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 68ad42d805..62695ec2e1 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -102,6 +102,19 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 
 === 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. <20140304174806.GA11561@sigill.intra.peff.net>.
+
 == Superseded features that will not be deprecated
 
 Some features have gained newer replacements that aim to improve the design in
-- 
2.45.2.457.g8d94cfb545.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v7 4/4] BreakingChanges: document that we do not plan to deprecate git-checkout

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2029 bytes --]

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.

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 62695ec2e1..ba86c0224d 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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. <xmqqttjazwwa.fsf@gitster.g>,
+<xmqqleeubork.fsf@gitster.g>,
+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
-- 
2.45.2.457.g8d94cfb545.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]