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

From: Karthik Nayak <karthik.188@gmail.com>
Date: May 14, 2024, 10:48 UTC
Message-ID: <CAOLa=ZRkLpi-DSNsTgVf5OCk6gEP7VTx2SeJRKT_Lv+pVu1Nyw@mail.gmail.com>
In-Reply-To: <2ef53ff98b12fe9373a15ec3a795235f040d9049.1715667067.git.ps@pks.im>

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.

Show 44 quoted lines

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

Show 12 quoted lines

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

Show 10 quoted lines

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