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

From: Junio C Hamano <[email-masked]>
Date: Tue, 14 May 2024 08:45:50 -0700

Patrick Steinhardt <[email-masked]> 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/[email-masked]/),
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.