Re: [PATCH] diff-tree doc: correct & remove wrong documentation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Feb 4, 2019, 21:10 UTC
- Message-ID
- <xmqqpns7tg2x.fsf@gitster-ct.c.googlers.com>
- In-Reply-To
- <20190204103618.17992-1-avarab@gmail.com>
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
Show 7 quoted lines
> <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.
Show 16 quoted lines
> - > - > -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.
Show 19 quoted lines
> - > -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). > -