dulwich.index.Index

class documentation

class Index:

Constructor: Index(filename, read, skip_hash, version, ...)

A Git Index file.

Method	`__contains__`	Check if a path exists in the index.
Method	`__delitem__`	Delete an entry from the index.
Method	`__getitem__`	Retrieve entry by relative path and stage.
Method	`__init__`	Create an index object associated with the given filename.
Method	`__iter__`	Iterate over the paths and stages in this index.
Method	`__len__`	Number of entries in this index file.
Method	`__repr__`	Return string representation of Index.
Method	`__setitem__`	Set an entry in the index.
Method	`canonical_path`	Resolve `name` to the canonical key stored in the index.
Method	`changes_from_tree`	Find the differences between the contents of this index and a tree.
Method	`clear`	Remove all contents from this index.
Method	`commit`	Create a new tree from an index.
Method	`convert_to_sparse`	Convert full index entries to sparse directory entries.
Method	`ensure_full_index`	Expand all sparse directory entries into full file entries.
Method	`get_mode`	Return the POSIX file mode for the object at a path.
Method	`get_sha1`	Return the (git object) SHA1 for the object at a path.
Method	`has_conflicts`	Check if the index contains any conflicted entries.
Method	`is_sparse`	Check if this index contains sparse directory entries.
Method	`items`	Get an iterator over (path, entry) pairs.
Method	`iteritems`	Iterate over (path, entry) pairs in the index.
Method	`iterobjects`	Iterate over path, sha, mode tuples for use with commit_tree.
Method	`paths`	Generate all paths in the index.
Method	`read`	Read current contents of index from disk.
Method	`update`	Update the index with multiple entries.
Method	`write`	Write current contents of index to disk.
Property	`path`	Get the path to the index file.
Method	`_expand_tree`	Recursively expand a tree into index entries.
Method	`_find_subtree_sha`	Find the SHA of a subtree at a given path.
Instance Variable	`_byname`	Undocumented
Instance Variable	`_extensions`	Undocumented
Instance Variable	`_file_mode`	Undocumented
Instance Variable	`_filename`	Undocumented
Instance Variable	`_normalized`	Undocumented
Instance Variable	`_path_normalizer`	Undocumented
Instance Variable	`_skip_hash`	Undocumented
Instance Variable	`_version`	Undocumented

def __contains__(self, key: bytes) -> bool: ¶

Check if a path exists in the index.

def __delitem__(self, name: bytes): ¶

Delete an entry from the index.

def __getitem__(self, key: bytes) -> IndexEntry | ConflictedIndexEntry: ¶

Retrieve entry by relative path and stage.

Returns: Either a IndexEntry or a ConflictedIndexEntry Raises KeyError: if the entry does not exist

Create an index object associated with the given filename.

Parameters
filename:`bytes \| str \| os.PathLike[str]`	Path to the index file
read:`bool`	Whether to initialize the index from the given file, should it exist.
skip_hash:`bool`	Whether to skip SHA1 hash when writing (for manyfiles feature)
version:`int \| None`	Index format version to use (None = auto-detect from file or use default)
file_mode:`int \| None`	Optional file permission mask for shared repository
path_normalizer:`Callable[[bytes], bytes] \| None`	Optional function mapping a filesystem path to a canonical form (e.g. case-folded, NFC-normalized). When provided, lookups (`index[path]`, `path in index`, `del index[path]`) transparently match paths that normalize to the same form as an existing entry.

def __iter__(self) -> Iterator[bytes]: ¶

Iterate over the paths and stages in this index.

def __len__(self) -> int: ¶

Number of entries in this index file.

def __repr__(self) -> str: ¶

Return string representation of Index.

def __setitem__(self, name: bytes, value: IndexEntry | ConflictedIndexEntry): ¶

Set an entry in the index.

def canonical_path(self, name: bytes) -> bytes: ¶

Resolve name to the canonical key stored in the index.

If an entry already exists under name (or no normalizer is configured), name is returned unchanged. Otherwise the normalizer is applied and the key of any entry with the same normalized form is returned. Falls back to name if none.

Normally callers do not need this because index[name], name in index, and del index[name] already apply normalization transparently. Use this when the path is also being used outside the index (for example to look up the same entry in a commit tree), so that both sides agree on the key.

def changes_from_tree(self, object_store: ObjectContainer, tree: ObjectID, want_unchanged: bool = False) ->

Generator[tuple[tuple[bytes | None, bytes | None], tuple[int | None, int | None], tuple[bytes | None, bytes | None]], None, None]

: ¶

Find the differences between the contents of this index and a tree.

Returns: Iterator over tuples with (oldpath, newpath), (oldmode,: newmode), (oldsha, newsha)

Parameters
object_store:`ObjectContainer`	Object store to use for retrieving tree contents
tree:`ObjectID`	SHA1 of the root tree
want_unchanged:`bool`	Whether unchanged files should be reported

Returns
`Generator[tuple[tuple[bytes \| None, bytes \| None], tuple[int \| None, int \| None], tuple[bytes \| None, bytes \| None]], None, None]`	Undocumented

def clear(self): ¶

Remove all contents from this index.

def commit(self, object_store: ObjectContainer) -> ObjectID: ¶

Create a new tree from an index.

Parameters
object_store:`ObjectContainer`	Object store to save the tree in

Returns
`ObjectID`	Root tree SHA

def convert_to_sparse(self, object_store: BaseObjectStore, tree_sha: ObjectID, sparse_dirs: Set[bytes]): ¶

Convert full index entries to sparse directory entries.

This collapses directories that are entirely outside the sparse checkout cone into single sparse directory entries.

Parameters
object_store:`BaseObjectStore`	Object store to read tree objects
tree_sha:`ObjectID`	SHA of the tree (usually HEAD) to base sparse dirs on
sparse_dirs:`Set[bytes]`	Set of directory paths (with trailing /) to collapse

Raises
`KeyError`	If tree_sha or a subdirectory doesn't exist

def ensure_full_index(self, object_store: BaseObjectStore): ¶

Expand all sparse directory entries into full file entries.

This converts a sparse index into a full index by recursively expanding any sparse directory entries into their constituent files.

Parameters
object_store:`BaseObjectStore`	Object store to read tree objects from

Raises
`KeyError`	If a tree object referenced by a sparse dir entry doesn't exist

def get_mode(self, path: bytes) -> int: ¶

Return the POSIX file mode for the object at a path.

def get_sha1(self, path: bytes) -> ObjectID: ¶

Return the (git object) SHA1 for the object at a path.

def has_conflicts(self) -> bool: ¶

Check if the index contains any conflicted entries.

Returns
`bool`	True if any entries are conflicted, False otherwise

def is_sparse(self) -> bool: ¶

Check if this index contains sparse directory entries.

Returns
`bool`	True if any sparse directory extension is present

def items(self) -> Iterator[tuple[bytes, IndexEntry | ConflictedIndexEntry]]: ¶

Get an iterator over (path, entry) pairs.

Returns
`Iterator[tuple[bytes, IndexEntry \| ConflictedIndexEntry]]`	Iterator of (path, entry) tuples

def iteritems(self) -> Iterator[tuple[bytes, IndexEntry | ConflictedIndexEntry]]: ¶

Iterate over (path, entry) pairs in the index.

Returns
`Iterator[tuple[bytes, IndexEntry \| ConflictedIndexEntry]]`	Iterator of (path, entry) tuples

def iterobjects(self) -> Iterable[tuple[bytes, ObjectID, int]]: ¶

Iterate over path, sha, mode tuples for use with commit_tree.

def paths(self) -> Generator[bytes, None, None]: ¶

Generate all paths in the index.

Yields
Path names as bytes

def read(self): ¶

Read current contents of index from disk.

def update(self, entries: dict[bytes, IndexEntry | ConflictedIndexEntry]): ¶

Update the index with multiple entries.

Parameters
entries:`dict[bytes, IndexEntry \| ConflictedIndexEntry]`	Dictionary mapping paths to index entries

def write(self): ¶

Write current contents of index to disk.

@property

path: bytes | str = ¶

Get the path to the index file.

Returns
Path to the index file

def _expand_tree(self, prefix: bytes, tree: Tree, object_store: BaseObjectStore, template_entry: IndexEntry): ¶

Recursively expand a tree into index entries.

Parameters
prefix:`bytes`	Path prefix for entries (without trailing slash)
tree:`Tree`	Tree object to expand
object_store:`BaseObjectStore`	Object store to read nested trees from
template_entry:`IndexEntry`	Template entry to copy metadata from

def _find_subtree_sha(self, tree: Tree, path: bytes, object_store: BaseObjectStore) -> bytes | None: ¶

Find the SHA of a subtree at a given path.

Parameters
tree:`Tree`	Root tree object to search in
path:`bytes`	Path to the subdirectory (no trailing slash)
object_store:`BaseObjectStore`	Object store to read nested trees from

Returns
`bytes \| None`	SHA of the subtree, or None if path doesn't exist

_byname: dict[bytes, IndexEntry | ConflictedIndexEntry] = ¶

Undocumented

_extensions: list[IndexExtension] = ¶

Undocumented

_file_mode = ¶

Undocumented

_filename = ¶

Undocumented

_normalized: dict[bytes, bytes] | None = ¶

Undocumented

_path_normalizer = ¶

Undocumented

_skip_hash = ¶

Undocumented

_version = ¶

Undocumented