datalad_next.iter_collections.gitworktree
Report on the content of a Git repository worktree
The main functionality is provided by the iter_gitworktree()
function.
- class datalad_next.iter_collections.gitworktree.GitTreeItemType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
Enum
Enumeration of item types of Git trees
- directory = 'directory'
- executablefile = 'executablefile'
- file = 'file'
- submodule = 'submodule'
- symlink = 'symlink'
- class datalad_next.iter_collections.gitworktree.GitWorktreeFileSystemItem(type: 'FileSystemItemType', name: 'PurePath', size: 'int', mtime: 'float | None' = None, mode: 'int | None' = None, uid: 'int | None' = None, gid: 'int | None' = None, link_target: 'PurePath | None' = None, fp: 'IO | None' = None, gitsha: 'str | None' = None, gittype: 'GitTreeItemType | None' = None)[source]
Bases:
FileSystemItem
- gitsha: str | None = None
- gittype: GitTreeItemType | None = None
- class datalad_next.iter_collections.gitworktree.GitWorktreeItem(name: 'PurePath', gitsha: 'str | None' = None, gittype: 'GitTreeItemType | None' = None)[source]
Bases:
PathBasedItem
- gitsha: str | None = None
- gittype: datalad_next.iter_collections.gitworktree.GitTreeItemType | None = None
- name: PurePath
- datalad_next.iter_collections.gitworktree.iter_gitworktree(path: Path, *, untracked: str | None = 'all', link_target: bool = False, fp: bool = False) Generator[datalad_next.iter_collections.gitworktree.GitWorktreeItem | datalad_next.iter_collections.gitworktree.GitWorktreeFileSystemItem, None, None] [source]
Uses
git ls-files
to report on a work tree of a Git repositoryThis 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, otherwiseGitWorktreeFileSystemItem
instances. In both cases,gitsha
andgittype
properties are provided. Either of them beingNone
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'} 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. Any untracked content is yielded as aPurePosixPath
.link_target (bool, optional) -- If
True
, 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.fp (bool, optional) -- If
True
, 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.
- Yields:
GitWorktreeItem
or GitWorktreeFileSystemItem