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

From: Junio C Hamano <gitster@pobox.com>
Date: May 14, 2024, 15:45 UTC
Message-ID: <xmqqh6f05rdd.fsf@gitster.g>
In-Reply-To: <ZkNJaaKTTKbns8wo@tanuki>

Patrick Steinhardt <ps@pks.im> writes:

Show 7 quoted lines

>> * 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 ;-)

Show 8 quoted lines

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