Re: [PATCH] Documentation/git-diff: remove -r from --name-status example

From: Linus Torvalds <torvalds@linux-foundation.org>
Date: Jul 29, 2007, 04:27 UTC
Message-ID: <alpine.LFD.0.999.0707282119010.3442@woody.linux-foundation.org>
In-Reply-To: <20070729041159.GA5544@coredump.intra.peff.net>

On Sun, 29 Jul 2007, Jeff King wrote:

> 
> So if I "git diff" two commits with --raw or --name-status, we don't
> recurse into recurse into subdirectories (because they are actually
> subtrees).

Exactly.

As it pertains to "git diff", none of this actually makes sense, and I think it might make sense to make "git diff" automatically set "recursive", exactly because "git diff" sometimes operates on trees, and sometimes on the index.

> If I "git diff" a commit against the index using --raw or
> --name-status, I we do recurse (since the index is actually flat). But
> if I "git diff" using -p, --stat, or --summary, it _does_ recurse no
> matter what I'm diffing.

When you ask for patches, it has to recurse, because there is no way to show a patch for a directory. So yes, anything non-raw will always enable recursing.

The fact that "--name-status" is not considered a "patch" is an implementation detail, and I would _almost_ suggest that we just make it always recurse, and leave thenon-recursing case for _just_ "--raw". But that is a separate decision.

> Does anybody else find this behavior confusing? I can understand why
> diff-tree might not recurse by default, but I wonder if porcelain like
> git-diff should try to be a little more consistent and always recurse.

I do agree.

The behaviour is obviously historical, and comes from "git diff" being just a shell-script wrapper around the different versions of diffing trees and indexes etc.

So it makes sense in that historical setting (and realizing that the "HEAD<->index" and "index<->files" cases were really a totally different operations), but it makes no sense in the modern world where people don't even *know* about "git diff-tree", but just use "git diff" for everything.

So:

> Something like:

Ack. Patch looks fine, makes sense, and is obviously good.

It *is* a change in behaviour, though, so I can understand if Junio doesn't think it's appropriate this late in the 1.5.3 series.

> For comparison, whatchanged, show, and format-patch are already always
> recursive. log is not.

Yeah. The other cases already default to patches, so they get the recursive from there.

"git log", of course, defaults to no output at all, so the only way to get non-recursive behaviour is to ask for "--raw", and then having to specify explicitly whether to get recursion or not make sense. Once you want raw output, it really _is_ your choice.

Whether we should make "--name-status" default to "-r" is worth discussing. I don't have any really strong opinion, although I _suspect_ that we should. The non-recursive case is useful, but in a very limited sense, and I think we might as well limit it to just the --raw case.

		Linus