Re: Remove old forgotten command: whatchanged

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 8, 2013, 19:19 UTC
Message-ID: <7v61vg9eht.fsf@alter.siamese.dyndns.org>
In-Reply-To: <ku0lqj$qvs$1@ger.gmane.org>

Damien Robert <damien.olivier.robert+gmane@gmail.com> writes:

Show 32 quoted lines

> Matthieu Moy  wrote in message <vpqfvukdy39.fsf@anie.imag.fr>:
>>> that confuses users.
>> 
>> ... but I do agree that the doc is really confusing. It would be much
>> better if the doc could be reduced to:
>> 
>> "This is a synonym for linkgit:git-log[1] --raw --some --other ---options.
>> Please refer to the documentation of that command."
>
> If I may chime in as a user: what really confused me about git whatchanged
> is this part of man gitcore-tutorial:
>
>        To see the whole history of our pitiful little git-tutorial project,
>        you can do
>
>            $ git log
>
>
>        which shows just the log messages, or if we want to see the log
>        together with the associated patches use the more complex (and much
>        more powerful)
>
>            $ git whatchanged -p
>
>
>        and you will see exactly what has changed in the repository over its
>        short history.
>
> I had to go look at the source code to realize that nowadays git log and
> git whatchanged are basically the same functions with different defaults. A
> pointer to that in the man page of git whatchanged would definitively be
> helpful.

The "tutorial" was written in fairly early days of Git's history, in order to primarily help those who want to use the plumbing command to script their own Porcelain commands. As it says at the very beginning, the end-user tutorial to use Git's Porcelain is gittutorial.txt and the user manual, not this document.

The above section primarily explains the use of diff-tree and it was appropriate back when git-whatchanged was a script. The intent of the whole document, not just this section, was to tickle the curiousity of the users and encourage them to see how the above "much more powerful" whatchanged was implemented by going to the source.

Which no longer is easy to do, as we have many Porcelains reimplemented in C.

I think a good way forward is to rewrite the above to:

        To see the whole history of our pitiful little git-tutorial
        project, you can do

            $ git log

        which shows just the log messages, or if we want to see the
        log together with the associated patches, use

            $ git log -p

        and you will see exactly what has changed in the repository
        over its short history.

and show a skeleton scripted implementation of "git log" using the plumbing commands which would be essentially "git rev-list" piped to "git diff-tree --stdin". Either have it as an example under contrib/examples, or as part of the text in this section of this document.