datalad_next.iter_collections.iter_gitworktree

datalad_next.iter_collections.iter_gitworktree(path: Path, *, untracked: str | None = 'all', link_target: bool = False, fp: bool = False, recursive: str = 'repository', pathspecs: list[str] | GitPathSpecs | None = None) → Generator[GitWorktreeItem | GitWorktreeFileSystemItem, None, None][source]

Uses git ls-files to report on a work tree of a Git repository

This iterator can be used to report on all tracked, and untracked content of a Git repository's work tree. This includes files that have been removed from the work tree (deleted), unless their removal has already been staged.

For any tracked content, yielded items include type information and gitsha as last known to Git. This means that such reports reflect the last committed or staged content, not the state of a potential unstaged modification in the work tree.

When no reporting of link targets or file-objects are requested, items of type GitWorktreeItem are yielded, otherwise GitWorktreeFileSystemItem instances. In both cases, gitsha and gittype properties are provided. Either of them being None indicates untracked work tree content.

Note

The gitsha is not equivalent to a SHA1 hash of a file's content, but is the SHA-type blob identifier as reported and used by Git.

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's work tree.

  • 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. 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 FileSystemItem will be included for each yielded item, and the targets of any symlinks will be reported, too.

  • fp (bool, optional) -- If True, information matching a FileSystemItem will be included for each yielded item, but without a link target detection, unless link_target is given. Moreover, each file-type item includes a file-like object to access the file's content. This file handle will be closed automatically when the next item is yielded.

  • recursive ({'submodules', 'repository', 'no'}, optional) -- Behavior for recursion into subdirectories of path. By default (repository), all directories within the repository are reported. This possibly includes untracked ones (see untracked), but not directories within submodules. With submodules, the full worktree is reported on with recursion into submodules. With no, only direct children of path are reported on. For any worktree items in subdirectories of path only a single record for the containing immediate subdirectory path is yielded. For example, with 'path/subdir/file1' and 'path/subdir/file2' there will only be a single item with name='subdir' and type='directory'.

  • pathspecs (optional) -- Patterns used to limit results to particular paths. Any pathspecs supported by Git can be used and are passed to the underlying git ls-files queries. Pathspecs are also supported for recursive reporting on submodules. In such a case, the results match those of individual queries with analog pathspecs on the respective submodules (Git itself does not support pathspecs for submodule-recursive operations). For example, a submodule recursion with a pathspec *.jpg will yield reports on all JPG files in all submodules, even though a submodule path itself does not match *.jpg. On the other hand, a pathspec submoddir/*.jpg will only report on JPG files in the submodule at submoddir/, but on all JPG files in that submodule. As of version 1.5, the pathspec support for submodule recursion is preliminary and results should be carefully investigated.

Yields:

GitWorktreeItem or GitWorktreeFileSystemItem -- The name attribute of an item is a PurePath instance with the corresponding (relative) path, in platform conventions.