docs/diff-options: clarify scope of diff-filter types
authorJeff King <peff@peff.net>
Thu, 4 Jan 2018 16:49:42 +0000 (11:49 -0500)
committerJunio C Hamano <gitster@pobox.com>
Thu, 4 Jan 2018 19:09:47 +0000 (11:09 -0800)
commit46af107bdef7bd9892bf504aa874d24f826dd4ba
treeee00c2729e193a88300f49d6b55b21d3e92e507d
parent9752ad0bb79f680bca48db7adc45338b298304b0
docs/diff-options: clarify scope of diff-filter types

The same document for "--diff-filter" is included by many
programs in the diff family. Because it mentions all
possible types (added, removed, etc), this may imply to the
reader that all types can be generated by a particular
command. But this isn't necessarily the case; "diff-files"
cannot generally produce an "Added" entry, since the diff is
limited to what is already in the index.

Let's make it clear that the list here is the full one, and
does not imply anything about what a particular invocation
may produce.

Note that conditionally including items (e.g., omitting
"Added" in the git-diff-files manpage) isn't the right
solution here for two reasons:

  - The problem isn't diff-files, but doing an index to
    working tree diff. "git diff" can do the same diff, but
    also has other modes where "Added" does show up.

  - The direction of the diff matters. Doing "diff-files -R"
    can get you Added entries (but not Deleted ones).

So it's best just to explain that the set of available types
depends on the specific diff invocation.

Reported-by: John Cheng <johnlicheng@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/diff-options.txt