Damien Robert <damien.olivier.robert+gmane@xxxxxxxxx> writes:
> Matthieu Moy wrote in message <vpqfvukdy39.fsf@xxxxxxxxxxxx>:
>>> 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.
--
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