Matthieu Moy <Matthieu.Moy@xxxxxxx> writes:
> Junio C Hamano <gitster@xxxxxxxxx> writes:
> ...
> Hm, right. Someone used to "$scm annotate" will probably try
> "git an<TAB>" and not finding anything there would be misleading
> (probably why svn has "annotate" as an alias for "blame").
>
>> 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.
>
> git-blame.txt already somehow has it in the documentation for "-c". I
> can't think of a good wording to improve it.
When somebody is reading git-blame.txt (or git-annotate.txt) for the first
time, I think 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. For historical reasons, we will continue supporting
both.
This is essential to squelch noises about "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 squelch
noises about "when will we start deprecating this?"
The mention of "annotate" in the description of "-c" hints almost nothing
in (2) except that the output format might be different (otherwise we
would not have "-c" command to begin with), but I guess that's Ok. As
long as we describe (2) on git-annotate page clearly enough, people who
are really curious could refer to git-annotate page.
So based on your wording, how about doing it like this? I chose to only
hint (3) subtly in this version instead of being overly explicit.
diff --git c/Documentation/git-annotate.txt w/Documentation/git-annotate.txt
index 8b6b56a..78dc5e2 100644
--- c/Documentation/git-annotate.txt
+++ w/Documentation/git-annotate.txt
@@ -14,6 +14,11 @@ DESCRIPTION
Annotates each line in the given file with information from the commit
which introduced the line. Optionally annotate from a given revision.
+The only difference from this command and linkgit:git-blame[1] is that
+they use slightly different output formats, and this command exists only
+for backward compatibility to support existing scripts, and provide more
+familiar command name for people coming from other SCM systems.
+
OPTIONS
-------
include::blame-options.txt[]
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
