{"thread":{"id":"47530","subject":"Misleading documentation for git-diff-files (diff-filter)","startedAt":"2018-01-03T16:07:32Z","lastAt":"2018-01-04T19:12:21Z","messageCount":6,"participants":["John Cheng","Junio C Hamano","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"335719","messageId":"CAJzZBAT--X8GXg_knege_pZ8A=_Qk9nyMCLaoRMvjhUFGQYsZA@mail.gmail.com","threadId":"47530","inReplyTo":null,"subject":"Misleading documentation for git-diff-files (diff-filter)","fromName":"John Cheng","fromEmail":"johnlicheng@gmail.com","sentAt":"2018-01-03T16:07:03Z","receivedAt":"2018-01-03T16:07:32Z","isPatch":false,"sender":{"key":"johnlicheng@gmail.com","avatar":null},"body":"I originally asked this question on stackoverflow\n(https://stackoverflow.com/q/48039277).\n\nI wanted to know if git diff-files shows files that are not in the\nindex but are in the working tree. The documentation says you can\nsupply --diff-filter=A, which will select file \"that are added\".\nHowever, git-diff-files (appears) to never show any files with the\nstatus of \"A\".\n\nIt seems like the cause is that git diff-files includes\ndiff-options.txt which uses a standard template for --diff-filter\nwhich includes the \"A\" option. Perhaps a clarification can be added?\n\nCompares the files in the working tree and the index. When paths\nare specified, compares only those named paths. Otherwise all\nentries in the index are compared. The output format is the\nsame as for 'git diff-index' and 'git diff-tree'. Files not in the index are\nnot compared.\n\n\n\n\n\n-- \n---\nJohn L Cheng\n"},{"id":"335803","messageId":"xmqqvagifqj8.fsf@gitster.mtv.corp.google.com","threadId":"47530","inReplyTo":"CAJzZBAT--X8GXg_knege_pZ8A=_Qk9nyMCLaoRMvjhUFGQYsZA@mail.gmail.com","subject":"Re: Misleading documentation for git-diff-files (diff-filter)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-01-03T23:53:15Z","receivedAt":"2018-01-03T23:53:23Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Cheng writes:\n\n> I wanted to know if git diff-files shows files that are not in the\n> index but are in the working tree.\n\nAt least in the original design of Git, that would fundamentally be\nimpossible, as Git _only_ cares about paths that are in the index,\nso a new file won't be in the picture until it is added. Because a\nchange is shown as \"A\"dded by the diff family of commands only when\nthe old side lacks a path that appears in the new side, there is no\nway \"diff-files\" that compares the index and the working tree would\nsee a path that is missing from the old (i.e. the index) side.\n"},{"id":"335822","messageId":"CAJzZBAQ_T3JDqsxy=s7gbrRQjDsdZODB8XsBb4TUCs1K1Bmnjw@mail.gmail.com","threadId":"47530","inReplyTo":"xmqqvagifqj8.fsf@gitster.mtv.corp.google.com","subject":"Re: Misleading documentation for git-diff-files (diff-filter)","fromName":"John Cheng","fromEmail":"johnlicheng@gmail.com","sentAt":"2018-01-04T15:53:53Z","receivedAt":"2018-01-04T15:54:19Z","isPatch":false,"sender":{"key":"johnlicheng@gmail.com","avatar":null},"body":"To be clear, I don't mean to imply that diff-files should include\nfiles that are not the index. I was trying to say that as a user, the\ndocumentation gave me a different impression.\n\nFor background, my intent was to have a script to look for local git\nrepos that with unstaged changes. After some trial and error, I found\nthat git-ls-files gave me what I needed. However, I wanted to point\nout why I initially believed git-diff-files with show \"added files\".\nThink of this more as user feedback.\n\nOn Wed, Jan 3, 2018 at 3:53 PM, Junio C Hamano wrote:\n> John Cheng writes:\n>\n>> I wanted to know if git diff-files shows files that are not in the\n>> index but are in the working tree.\n>\n> At least in the original design of Git, that would fundamentally be\n> impossible, as Git _only_ cares about paths that are in the index,\n> so a new file won't be in the picture until it is added. Because a\n> change is shown as \"A\"dded by the diff family of commands only when\n> the old side lacks a path that appears in the new side, there is no\n> way \"diff-files\" that compares the index and the working tree would\n> see a path that is missing from the old (i.e. the index) side.\n\n\n\n-- \n---\nJohn L Cheng\n"},{"id":"335823","messageId":"20180104164941.GB18376@sigill.intra.peff.net","threadId":"47530","inReplyTo":"CAJzZBAQ_T3JDqsxy=s7gbrRQjDsdZODB8XsBb4TUCs1K1Bmnjw@mail.gmail.com","subject":"Re: Misleading documentation for git-diff-files (diff-filter)","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-01-04T16:49:42Z","receivedAt":"2018-01-04T16:49:50Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jan 04, 2018 at 07:53:53AM -0800, John Cheng wrote:\n\n> To be clear, I don't mean to imply that diff-files should include\n> files that are not the index. I was trying to say that as a user, the\n> documentation gave me a different impression.\n> \n> For background, my intent was to have a script to look for local git\n> repos that with unstaged changes. After some trial and error, I found\n> that git-ls-files gave me what I needed. However, I wanted to point\n> out why I initially believed git-diff-files with show \"added files\".\n\nI took your original mail to be a suggestion that the documentation\ncould be more clear. :)\n\nSo maybe something like the patch below?\n\nIt actually would be an interesting feature for a diff from the index to\nthe working tree to include untracked files as new entries. I don't\nthink we'd want to do that by default (since the actions a user needs to\ntake are quite different between a modified file, one marked\nintent-to-add, and an untracked one). But I could see it being useful\nfor a caller to want to consider the whole tree as a single diff.\n\n-- >8 --\nSubject: [PATCH] docs/diff-options: clarify scope of diff-filter types\n\nThe same document for \"--diff-filter\" is included by many\nprograms in the diff family. Because it mentions all\npossible types (added, removed, etc), this may imply to the\nreader that all types can be generated by a particular\ncommand. But this isn't necessarily the case; \"diff-files\"\ncannot generally produce an \"Added\" entry, since the diff is\nlimited to what is already in the index.\n\nLet's make it clear that the list here is the full one, and\ndoes not imply anything about what a particular invocation\nmay produce.\n\nNote that conditionally including items (e.g., omitting\n\"Added\" in the git-diff-files manpage) isn't the right\nsolution here for two reasons:\n\n - The problem isn't diff-files, but doing an index to\n working tree diff. \"git diff\" can do the same diff, but\n also has other modes where \"Added\" does show up.\n\n - The direction of the diff matters. Doing \"diff-files -R\"\n can get you Added entries (but not Deleted ones).\n\nSo it's best just to explain that the set of available types\ndepends on the specific diff invocation.\n\nReported-by: John Cheng \nSigned-off-by: Jeff King \n---\n Documentation/diff-options.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9d1586b956..743af97b06 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -469,6 +469,12 @@ ifndef::git-format-patch[]\n +\n Also, these upper-case letters can be downcased to exclude. E.g.\n `--diff-filter=ad` excludes added and deleted paths.\n++\n+Note that not all diffs can feature all types. For instance, diffs\n+from the index to the working tree can never have Added entries\n+(because the set of paths included in the diff is limited by what is in\n+the index). Similarly, copied and renamed entries cannot appear if\n+detection for those types is disabled.\n \n -S::\n \tLook for differences that change the number of occurrences of\n-- \n2.16.0.rc0.391.gbd38408415\n\n"},{"id":"335837","messageId":"xmqq1sj5fnkt.fsf@gitster.mtv.corp.google.com","threadId":"47530","inReplyTo":"20180104164941.GB18376@sigill.intra.peff.net","subject":"Re: Misleading documentation for git-diff-files (diff-filter)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-01-04T19:09:22Z","receivedAt":"2018-01-04T19:09:29Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 9d1586b956..743af97b06 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -469,6 +469,12 @@ ifndef::git-format-patch[]\n> +\n> Also, these upper-case letters can be downcased to exclude. E.g.\n> `--diff-filter=ad` excludes added and deleted paths.\n> ++\n> +Note that not all diffs can feature all types. For instance, diffs\n> +from the index to the working tree can never have Added entries\n> +(because the set of paths included in the diff is limited by what is in\n> +the index). Similarly, copied and renamed entries cannot appear if\n> +detection for those types is disabled.\n\nMakes sense; thanks.\n"},{"id":"335838","messageId":"CAJzZBARFyadScz_ovhtDrh3NFJwD=RSTMNRtLXj9DRDFGYVd3A@mail.gmail.com","threadId":"47530","inReplyTo":"xmqq1sj5fnkt.fsf@gitster.mtv.corp.google.com","subject":"Re: Misleading documentation for git-diff-files (diff-filter)","fromName":"John Cheng","fromEmail":"johnlicheng@gmail.com","sentAt":"2018-01-04T19:11:55Z","receivedAt":"2018-01-04T19:12:21Z","isPatch":false,"sender":{"key":"johnlicheng@gmail.com","avatar":null},"body":"Thanks for the clarification! I also didn't realize that diff-files -R\nwill show added files. You learn something new everyday ;)\n\nOn Thu, Jan 4, 2018 at 11:09 AM, Junio C Hamano wrote:\n> Jeff King writes:\n>\n>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n>> index 9d1586b956..743af97b06 100644\n>> --- a/Documentation/diff-options.txt\n>> +++ b/Documentation/diff-options.txt\n>> @@ -469,6 +469,12 @@ ifndef::git-format-patch[]\n>> +\n>> Also, these upper-case letters can be downcased to exclude. E.g.\n>> `--diff-filter=ad` excludes added and deleted paths.\n>> ++\n>> +Note that not all diffs can feature all types. For instance, diffs\n>> +from the index to the working tree can never have Added entries\n>> +(because the set of paths included in the diff is limited by what is in\n>> +the index). Similarly, copied and renamed entries cannot appear if\n>> +detection for those types is disabled.\n>\n> Makes sense; thanks.\n\n\n\n-- \n---\nJohn L Cheng\n"}]}