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

[Patrick Steinhardt <ps@pks.im>]

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