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

From: Patrick Steinhardt <ps@pks.im>
Date: May 14, 2024, 11:22 UTC
Message-ID: <ZkNJaaKTTKbns8wo@tanuki>
In-Reply-To: <CAOLa=ZRkLpi-DSNsTgVf5OCk6gEP7VTx2SeJRKT_Lv+pVu1Nyw@mail.gmail.com>

On Tue, May 14, 2024 at 06:48:38AM -0400, Karthik Nayak wrote:

> Patrick Steinhardt <ps@pks.im> writes:

[snip]

Show 6 quoted lines

> I think it is worthwhile also looking at the number of commands we have
> and see that some of these could possibly be marked deprecated, maybe
> removal could follow too:
> 
> * add, stage
> Here, `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.

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

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