| Message ID | 20190204103618.17992-1-avarab@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | diff-tree doc: correct & remove wrong documentation | expand |
On Mon, Feb 4, 2019 at 5:36 PM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: > > The documentation saying that diff-tree didn't support anything except > literal prefixes hasn't been true since > d38f28093e ("tree_entry_interesting(): support wildcard matching", > 2010-12-15), but this documentation was not updated at the time. > > Since this command uses pathspecs like most other commands, there's no > need to show examples of how the various "cmd <revs> <paths>" > invocations work. > > Furthermore, the "git diff-tree --abbrev 5319e4" example shown here > never worked. We'd ended up with that through a combination of > 62b42d3487 ("docs: fix some antique example output", 2011-05-26) and > ac4e086929 ("Adjust core-git documentation to more recent Linus GIT.", > 2005-05-05), but "git diff-tree <tree>" was always invalid. Nice! I was going to protest "but it does not work!" but I was thinking ls-tree instead of diff-tree. > > Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > --- > Documentation/git-diff-tree.txt | 51 +-------------------------------- > 1 file changed, 1 insertion(+), 50 deletions(-) > > diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt > index 2319b2b192..43daa7c046 100644 > --- a/Documentation/git-diff-tree.txt > +++ b/Documentation/git-diff-tree.txt > @@ -31,10 +31,7 @@ include::diff-options.txt[] > > <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. > > -r:: > recurse into sub-trees > @@ -114,52 +111,6 @@ include::pretty-options.txt[] > > > include::pretty-formats.txt[] > - > - > -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. > - > -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. > - > -An example of normal usage is: > - > - torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4 > - :100664 100664 ac348b... a01513... git-fsck-objects.c > - > -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). > - > - > include::diff-format.txt[] > > GIT > -- > 2.20.1.611.gfbb209baf1 >
Æ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). > -
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). >> -
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 2319b2b192..43daa7c046 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -31,10 +31,7 @@ include::diff-options.txt[] <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. -r:: recurse into sub-trees @@ -114,52 +111,6 @@ include::pretty-options.txt[] include::pretty-formats.txt[] - - -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. - -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. - -An example of normal usage is: - - torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4 - :100664 100664 ac348b... a01513... git-fsck-objects.c - -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). - - include::diff-format.txt[] GIT
The documentation saying that diff-tree didn't support anything except literal prefixes hasn't been true since d38f28093e ("tree_entry_interesting(): support wildcard matching", 2010-12-15), but this documentation was not updated at the time. Since this command uses pathspecs like most other commands, there's no need to show examples of how the various "cmd <revs> <paths>" invocations work. Furthermore, the "git diff-tree --abbrev 5319e4" example shown here never worked. We'd ended up with that through a combination of 62b42d3487 ("docs: fix some antique example output", 2011-05-26) and ac4e086929 ("Adjust core-git documentation to more recent Linus GIT.", 2005-05-05), but "git diff-tree <tree>" was always invalid. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- Documentation/git-diff-tree.txt | 51 +-------------------------------- 1 file changed, 1 insertion(+), 50 deletions(-)