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

[Junio C Hamano <gitster@pobox.com>]

Æ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.

> -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).
> -