ENH: Extend rsync-like diff(path='subds/') to path constraints within the subds

When called with a trailing slash in a path argument matching a subdataset,
`diff()` will report on the content, not only on the subdataset record in
its superdataset -- even with `recursive=False`.

While this is not universally loved, it makes sense to not limit this
behavior to a single trailing slash.

When `subds/` reports on the entire subdataset, `subds/subdir` will now
only report on the content within `subdir` of `subds`.

Author: mih

datalad/core/local/diff.py

@@ -306,7 +306,7 @@ def _diff_ds(ds, fr, to, constant_refs, recursion_level, origpaths, untracked,
             if ds.pathobj in p.parents or (p == ds.pathobj and goinside)
         )
     try:
-        lgr.debug("diff %s from '%s' to '%s'", ds, fr, to)
+        lgr.debug("Diff %s from '%s' to '%s'", ds, fr, to)
         diff_state = repo.diffstatus(
             fr,
             to,
@@ -350,10 +350,17 @@ def _diff_ds(ds, fr, to, constant_refs, recursion_level, origpaths, untracked,
             parentds=ds.path,
             status='ok',
         )
-        # if a dataset, and given in rsync-style 'ds/' or with sufficient
-        # recursion level left -> dive in
+        # for a dataset we need to decide whether to dive in, or not
         if props.get('type', None) == 'dataset' and (
-                (paths and paths.get(path, False)) or recursion_level != 0):
+                # subdataset path was given in rsync-style 'ds/'
+                (paths and paths.get(path, False))
+                # there is still sufficient recursion level left
+                or recursion_level != 0
+                # no recursion possible anymore, but one of the given
+                # path arguments is in this subdataset
+                or (recursion_level == 0
+                    and paths
+                    and any(path in p.parents for p in paths))):
             subds_state = props.get('state', None)
             if subds_state in ('clean', 'deleted'):
                 # no need to look into the subdataset
@@ -378,7 +385,10 @@ def _diff_ds(ds, fr, to, constant_refs, recursion_level, origpaths, untracked,
                     # subtract on level on the way down, unless the path
                     # args instructed to go inside this subdataset
                     recursion_level=recursion_level
-                    if paths and paths.get(path, False) else recursion_level - 1,
+                    # protect against dropping below zero (would mean unconditional
+                    # recursion)
+                    if not recursion_level or (paths and paths.get(path, False))
+                    else recursion_level - 1,
                     origpaths=origpaths,
                     untracked=untracked,
                     annexinfo=annexinfo,

datalad/core/local/tests/test_diff.py

@@ -22,6 +22,7 @@
 from datalad.consts import PRE_INIT_COMMIT_SHA
 from datalad.cmd import GitRunner
 from datalad.utils import (
+    Path,
     on_windows,
 )
 from datalad.tests.utils import (
@@ -36,6 +37,7 @@
     get_deeply_nested_structure,
     has_symlink_capability,
     known_failure_githubci_win,
+    neq_,
     OBSCURE_FILENAME,
     ok_,
     SkipTest,
@@ -451,7 +453,7 @@ def test_diff_rsync_syntax(path):
     # three nested datasets
     ds = Dataset(path).create()
     subds = ds.create('sub')
-    subsubds = subds.create('deep')
+    subsubds = subds.create(Path('subdir', 'deep'))
     justtop = ds.diff(fr=PRE_INIT_COMMIT_SHA, path='sub')
     # we only get a single result, the subdataset in question
     assert_result_count(justtop, 1)
@@ -463,6 +465,16 @@ def test_diff_rsync_syntax(path):
     assert_result_count(inside, 1, type='dataset', path=subds.path)
     assert_result_count(inside, 1, type='dataset', path=subsubds.path)
     assert_result_count(inside, 0, type='file', parentds=subsubds.path)
+    # if we point to the subdir in 'sub' the reporting wrt the subsubds
+    # doesn't change. It is merely a path constraint within the queried
+    # subds, but because the subsubds is still underneath it, nothing changes
+    inside_subdir = ds.diff(fr=PRE_INIT_COMMIT_SHA, path=op.join('sub', 'subdir'))
+    assert_result_count(inside_subdir, 2, type='dataset')
+    assert_result_count(inside_subdir, 1, type='dataset', path=subds.path)
+    assert_result_count(inside_subdir, 1, type='dataset', path=subsubds.path)
+    assert_result_count(inside_subdir, 0, type='file', parentds=subsubds.path)
+    # but the rest is different (e.g. all the stuff in .datalad is gone)
+    neq_(inside, inside_subdir)
     # just for completeness, we get more when going full recursive
     rec = ds.diff(fr=PRE_INIT_COMMIT_SHA, recursive=True, path='sub' + os.sep)
     assert(len(inside) < len(rec))