feat(iter_gitworktree): add ability to report untracked content only

This change is a preparation for replacing the `gitstatus()` helper
`_yield_repo_untracked()`, and remove that now duplicate implementation
with this standard iterator.

Author: mih

datalad_next/iter_collections/gitworktree.py

@@ -93,6 +93,13 @@ def from_worktreeitem(
     'no-empty-dir':
     ('--stage', '--cached', '--exclude-standard',
      '--others', '--directory', '--no-empty-directory'),
+    'only':
+    ('--exclude-standard', '--others'),
+    'only-whole-dir':
+    ('--exclude-standard', '--others', '--directory'),
+    'only-no-empty-dir':
+    ('--exclude-standard',
+     '--others', '--directory', '--no-empty-directory'),
 }
 
 
@@ -132,12 +139,15 @@ def iter_gitworktree(
       Path of a directory in a Git repository to report on. This directory
       need not be the root directory of the repository, but must be part of
       the repository's work tree.
-    untracked: {'all', 'whole-dir', 'no-empty-dir'} or None, optional
+    untracked: {'all', 'whole-dir', 'no-empty-dir', 'only', 'only-whole-dir', 'only-no-empty-dir'} or None, optional
       If not ``None``, also reports on untracked work tree content.
       ``all`` reports on any untracked file; ``whole-dir`` yields a single
       report for a directory that is entirely untracked, and not individual
       untracked files in it; ``no-empty-dir`` skips any reports on
-      untracked empty directories.
+      untracked empty directories. The modes starting with 'only' offer the
+      same untracked content reporting styles, but only untracked and no
+      tracked content is reported. For example, 'only' is the corresponding
+      mode to 'all' with no tracked content being reported.
     link_target: bool, optional
       If ``True``, information matching a
       :class:`~datalad_next.iter_collections.utils.FileSystemItem`

datalad_next/iter_collections/tests/test_itergitworktree.py

@@ -239,6 +239,28 @@ def test_iter_gitworktree_basic_fp(existing_dataset, no_result_rendering):
     assert not fcount
 
 
+def test_iter_gitworktree_untracked_only(modified_dataset):
+    p = modified_dataset.pathobj
+    # only untracked files
+    repo_items = list(iter_gitworktree(p, untracked='only'))
+    assert all(f.name.name == 'file_u' for f in repo_items)
+    # same report, but compressed to immediate directory children
+    dir_items = list(iter_gitworktree(p, untracked='only', recursive='no'))
+    assert set(f.name.parts[0] for f in repo_items) == \
+        set(f.name.name for f in dir_items)
+    # no wholly untracked directories in standard report
+    assert not any(f.name.name == 'dir_u'
+                   for f in iter_gitworktree(p, untracked='only'))
+    # but this can be requested
+    wholedir_items = list(iter_gitworktree(p, untracked='only-whole-dir'))
+    assert any(f.name.name == 'dir_u' for f in wholedir_items)
+    # smoke test remaining mode, test case doesn't cause difference
+    assert any(f.name.name == 'dirempty_u' for f in wholedir_items)
+    assert not any(f.name.name == 'dirempty_u'
+                   for f in iter_gitworktree(p, untracked='only-no-empty-dir'))
+
+
+
 def test_iter_gitworktree_pathspec(modified_dataset):
     p = modified_dataset.pathobj
     # query for any files that are set to go straight to Git. these are just