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') → 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'} 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.

  • 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 ({'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. If 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'.

Yields:

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