path: root/Documentation/diff-options.txt
diff options
authorJeff King <>2018-01-04 16:49:42 (GMT)
committerJunio C Hamano <>2018-01-04 19:09:47 (GMT)
commit46af107bdef7bd9892bf504aa874d24f826dd4ba (patch)
treeee00c2729e193a88300f49d6b55b21d3e92e507d /Documentation/diff-options.txt
parent9752ad0bb79f680bca48db7adc45338b298304b0 (diff)
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 <> Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/diff-options.txt')
1 files changed, 6 insertions, 0 deletions
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index d91ddbd..eec583d 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -422,6 +422,12 @@ ifndef::git-format-patch[]
Also, these upper-case letters can be downcased to exclude. E.g.
`--diff-filter=ad` excludes added and deleted paths.
+Note that not all diffs can feature all types. For instance, diffs
+from the index to the working tree can never have Added entries
+(because the set of paths included in the diff is limited by what is in
+the index). Similarly, copied and renamed entries cannot appear if
+detection for those types is disabled.
Look for differences that change the number of occurrences of