Re: [PATCH] diff-tree doc: correct & remove wrong documentation

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Feb 04 2019, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>>  <path>...::
>>  	If provided, the results are limited to a subset of files
>> -	matching one of these prefix strings.
>> -	i.e., file matches `/^<pattern1>|<pattern2>|.../`
>> -	Note that this parameter does not provide any wildcard or regexp
>> -	features.
>> +	matching one of the provided pathspecs.
>
> Correct.
>
>> -
>> -
>> -LIMITING OUTPUT
>> ----------------
>> -If you're only interested in differences in a subset of files, for
>> -example some architecture-specific files, you might do:
>> -
>> -	git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
>> -
>> -and it will only show you what changed in those two directories.
>> -
>> -Or if you are searching for what changed in just `kernel/sched.c`, just do
>> -
>> -	git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
>> -
>> -and it will ignore all differences to other files.
>
> All of the above give still useful piece of information to the
> readers.  I do not think it is a good idea to assume familiarilty
> with pathspec limiting to all readers---a new reader must start
> somewhere and diff-tree may just be a random place s/he started at.
>
> So I do not think it is a good idea to drop this example or the
> section from the page.

I was aiming for something like what e.g. "git-ls-files" says, which is
just:

    Files to show. If no files are given all files which match the other
    specified criteria are shown.

But yes, having an example is good, but with this removed isn't the
example we show in "RAW OUTPUT FORMAT" now just below sufficient to show
what this remove section was trying (and failing) to do, i.e.:

    git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]
        compares the trees named by the two arguments.

That doesn't have --abbrev, but I think it's enough to leave that
discussed in "OPTIONS" above.

>> -The pattern is always the prefix, and is matched exactly.  There are no
>> -wildcards.  Even stricter, it has to match a complete path component.
>> -I.e. "foo" does not pick up `foobar.h`.  "foo" does match `foo/bar.h`
>> -so it can be used to name subdirectories.
>
> I agree with the patch that this paragraph should go.
>
>> -An example of normal usage is:
>> -
>> -  torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4
>> -  :100664 100664 ac348b... a01513...	git-fsck-objects.c
>
> Interesting.  This does not work (and I do not think it has ever
> worked) for a tree object 5319e4, but it works as advertised for a
> commit object.
>
> The description section has this near the top
>
>        If there is only one <tree-ish> given, the commit is compared
>        with its parents (see --stdin below).
>
> I think s/given,/& it must be a commit-ish and/ would be appropriate
> there; please include such a fix in a reroll.
>
> I agree with this patch that it is a good idea to drop this example;
> it is more appropriate to use "git show" on the commit-ish in the
> case of the given example anyway.
>
>> -
>> -which tells you that the last commit changed just one file (it's from
>> -this one:
>> -
>> ------------------------------------------------------------------------------
>> -commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
>> -tree 5319e4d609cdd282069cc4dce33c1db559539b03
>> -parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
>> -author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
>> -committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
>> -
>> -Make "git-fsck-objects" print out all the root commits it finds.
>> -
>> -Once I do the reference tracking, I'll also make it print out all the
>> -HEAD commits it finds, which is even more interesting.
>> ------------------------------------------------------------------------------
>> -
>> -in case you care).
>> -