Subject: Re: [PATCH] Mention the fact that 'git annotate' is only for backward compatibility.

From: Junio C Hamano <[email-masked]>
Date: Thu, 04 Sep 2008 12:17:05 -0700

Petr Baudis <[email-masked]> writes:

> Can you please also mark it deprecated in the bash completion and
> command-list.txt?

I am hesitant to use the word "deprecated" in git(7) manual page, as the
word has much stronger connotation than merely "because a more often used
equivalent exists, there is no reason to encourage this for new people,
but on the other hand there is no reason to remove or phase it out to hurt
existing users", which is what "git annotate" is.

"Deprecated" is more like "it is still supported but its use is actively
discouraged".  I do not think we actively discourage it, nor need to phase
it out.

People coming from different background may look for annotate and get
frustrated until they find out blame is the equivalent (or vice versa).

While I do not mind marking annotate as ": infrequently used ;;" in the
completion script, I am skeptical about the value of such a change.
Dropping annotate from the completion is a _slight_ improvement in that
when people type "git a<TAB>" they will see one less candidates, but it is
not a great deal of improvement: four down from five.

Mentioning that we support both names for findability in both annotate and
blame manual pages (not just annotate page) might be a better thing to do.