datalad_next.iter_collections.iter_gitstatus

datalad_next.iter_collections.iter_gitstatus(path: Path, *, untracked: str | None = 'all', recursive: str = 'repository', eval_submodule_state: str = 'full') → Generator[GitDiffItem, None, None][source]

Recursion mode 'no'

This mode limits the reporting to immediate directory items of a given path. This mode is not necessarily faster than a 'repository' recursion. Its primary purpose is the ability to deliver a collapsed report in that subdirectories are treated similar to submodules -- as containers that maybe have modified or untracked content.

Parameters:

  • path (Path) -- 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. If the directory is not the root directory of a non-bare repository, the iterator is constrained to items underneath that directory.

  • untracked ({'all', 'whole-dir', '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. Also see eval_submodule_state for how this parameter is applied in submodule recursion.

  • recursive ({'no', 'repository', 'submodules', 'monolithic'}, optional) -- Behavior for recursion into subtrees. By default (repository), all trees within the repository underneath path) are reported, but no tree within submodules. With submodules, recursion includes any submodule that is present. If no, only direct children are reported on.

  • eval_submodule_state ({"no", "commit", "full"}, optional) -- If 'full' (default), the state of a submodule is evaluated by considering all modifications, with the treatment of untracked files determined by untracked. If 'commit', the modification check is restricted to comparing the submodule's "HEAD" commit to the one recorded in the superdataset. If 'no', the state of the subdataset is not evaluated. When a git-annex repository in adjusted mode is detected, the reference commit that the worktree is being compared to is the basis of the adjusted branch (i.e., the corresponding branch).

Yields:

  • GitDiffItem -- The name and prev_name attributes of an item are a str with the corresponding (relative) path, as reported by Git (in POSIX conventions).

  • .. note:: -- The implementation requires git rev-parse --path-format=relative that was introduced with Git v2.31.