Re: [PATCH 3/3] last-modified: better document how depth in handled

[Patrick Steinhardt <ps@pks.im>]

On Tue, Dec 02, 2025 at 12:01:18PM +0100, Toon Claes wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > Hm, that's confusing indeed. Is it possible for git-last-modified(1) to
> > do the "right thing" automatically? That is, given "sub/file", show when
> > that specific file has been last modified? Or is there a good
> > (non-technical) reason it behaves the way it does?
> 
> You bring up a good point. In the version of git-blame-tree(1) that
> GitHub did share, the `--recursive` flag is enabled by default. So if
> you pass a file path to the command, you'll get the "right thing". But
> as I am pointing out in this patch, if you pass a subtree, everything in
> that subtree is shown too. You could argue this is the "right thing".
> 
> Anyhow, in the version of git-last-modified(1) I submitted upstream,
> recursive is not enabled by default. My reason, at the time option
> --max-depth wasn't implemented yet. I submitted those changes in a
> separate series (these patches also originate from GitHub by the way).
> If those patches wouldn't land, I think always-on recursive behavior for
> git-last-modified(1) would be quite annoying.
> 
> So long story short, as git-last-modified(1) is still marked as
> "EXPERIMENTAL", shall we make recursive always-on?

I think that is a good idea, as it sounds like it would make common use
cases way more intuitive.

An alternative would be to default to a max-depth of 0 and stick to the
non-recursive default. In that case, the command would work intuitively
to the user, right? At least it would work intuitively if the user
doesn't want a recursive listing.

So maybe we should combine these two improvements. That is, we use:

  - An infinite max-depth by default with the recursive bahviour.

  - A max-depth of 0 in the non-recursive case.

In this case, we'd always recursively list all entries by default, but
in case the user explicitly doesn't want recursive behaviour we'd know
to show the last modification date of all provided files.

I was briefly thinking that a max-depth of 1 might be a more obvious
default for the non-recursive case. In that case, doing e.g. `git
last-modified --no-recursive t` would list the contents of "t/", but
nothing more. I'm a bit torn there though whether that really is a
sufficient improvement over a max-depth of 0.

Patrick