From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS31976 209.132.180.0/23 X-Spam-Status: No, score=-3.4 required=3.0 tests=AWL,BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,RCVD_IN_DNSWL_HI,T_RP_MATCHES_RCVD shortcircuit=no autolearn=ham autolearn_force=no version=3.4.0 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by dcvr.yhbt.net (Postfix) with ESMTP id EB96E1F404 for ; Thu, 4 Jan 2018 16:49:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753394AbeADQto (ORCPT ); Thu, 4 Jan 2018 11:49:44 -0500 Received: from cloud.peff.net ([104.130.231.41]:53136 "HELO cloud.peff.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with SMTP id S1752344AbeADQto (ORCPT ); Thu, 4 Jan 2018 11:49:44 -0500 Received: (qmail 5055 invoked by uid 109); 4 Jan 2018 16:49:44 -0000 Received: from Unknown (HELO peff.net) (10.0.1.2) by cloud.peff.net (qpsmtpd/0.94) with SMTP; Thu, 04 Jan 2018 16:49:44 +0000 Authentication-Results: cloud.peff.net; auth=none Received: (qmail 5642 invoked by uid 111); 4 Jan 2018 16:50:15 -0000 Received: from sigill.intra.peff.net (HELO sigill.intra.peff.net) (10.0.0.7) by peff.net (qpsmtpd/0.94) with ESMTPA; Thu, 04 Jan 2018 11:50:15 -0500 Authentication-Results: peff.net; auth=pass (cram-md5) smtp.auth=relayok Received: by sigill.intra.peff.net (sSMTP sendmail emulation); Thu, 04 Jan 2018 11:49:42 -0500 Date: Thu, 4 Jan 2018 11:49:42 -0500 From: Jeff King To: John Cheng Cc: Junio C Hamano , git@vger.kernel.org Subject: Re: Misleading documentation for git-diff-files (diff-filter) Message-ID: <20180104164941.GB18376@sigill.intra.peff.net> References: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org On Thu, Jan 04, 2018 at 07:53:53AM -0800, John Cheng wrote: > To be clear, I don't mean to imply that diff-files should include > files that are not the index. I was trying to say that as a user, the > documentation gave me a different impression. > > For background, my intent was to have a script to look for local git > repos that with unstaged changes. After some trial and error, I found > that git-ls-files gave me what I needed. However, I wanted to point > out why I initially believed git-diff-files with show "added files". I took your original mail to be a suggestion that the documentation could be more clear. :) So maybe something like the patch below? It actually would be an interesting feature for a diff from the index to the working tree to include untracked files as new entries. I don't think we'd want to do that by default (since the actions a user needs to take are quite different between a modified file, one marked intent-to-add, and an untracked one). But I could see it being useful for a caller to want to consider the whole tree as a single diff. -- >8 -- Subject: [PATCH] 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 --- Documentation/diff-options.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9d1586b956..743af97b06 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -469,6 +469,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. -S:: Look for differences that change the number of occurrences of -- 2.16.0.rc0.391.gbd38408415