Mention the fact that 'git annotate' is only for backward compatibility.
authorJunio C Hamano <gitster@pobox.com>
Fri, 5 Sep 2008 07:29:51 +0000 (00:29 -0700)
committerJunio C Hamano <gitster@pobox.com>
Fri, 5 Sep 2008 08:15:40 +0000 (01:15 -0700)
commitf22a432b157c5673a1004934a2e6ba77dd55b356
tree5c29b4efa93589e6b9951cde646555baa095cc22
parent7ceacdffc5c05f9a763b4cb6ea7cb528004643c3
Mention the fact that 'git annotate' is only for backward compatibility.

When somebody is reading git-blame.txt (or git-annotate.txt) for the first
time, the message we would like to send is:

 (1) Here is why you would want to use this command, what it can do
     (perhaps more than what you would have expected from "$scm blame"),
     and how you tell it to do what it does.

     This is obvious.

 (2) You might have heard of the command with the other name.  There is no
     difference between the two, except they differ in their default
     output formats.

     This is essential to answer: "git has both?  how are they different?"

 (3) We tend to encourage blame over annotate for new scripts and new
     people, but there is no reason to choose one over the other.

     This is not as important as (2), but would be useful to avoid
     repeated questions about "when will we start deprecating this?"

As long as we describe (2) on git-annotate page clearly enough, people who
read git-blame page first and get curious can refer to git-annotate page.
While at it, subtly hint (3) without being overly explicit.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-annotate.txt