dulwich.index

module documentation

Parser for the git index file format.

Class	`ConflictedIndexEntry`	Index entry that represents a conflict.
Class	`Index`	A Git Index file.
Class	`IndexEntry`	Represents an entry in the Git index.
Class	`IndexExtension`	Base class for index extensions.
Class	`locked_index`	Lock the index while making modifications.
Class	`ResolveUndoExtension`	Resolve undo extension for recording merge conflicts.
Class	`SerializedIndexEntry`	Represents a serialized index entry as stored in the index file.
Class	`SparseDirExtension`	Sparse directory extension.
Class	`Stage`	Represents the stage of an index entry during merge conflicts.
Class	`TreeExtension`	Tree cache extension.
Class	`UntrackedExtension`	Untracked cache extension.
Exception	`UnmergedEntries`	Unmerged entries exist in the index.
Exception	`UnsupportedIndexFormat`	An unsupported index format was encountered.
Exception	`WindowsSymlinkPermissionError`	Windows-specific error for symlink creation failures.
Function	`blob_from_path_and_mode`	Create a blob from a path and a stat object.
Function	`blob_from_path_and_stat`	Create a blob from a path and a stat object.
Function	`build_file_from_blob`	Build a file or symlink on disk based on a Git object.
Function	`build_index_from_tree`	Generate and materialize index from a tree.
Function	`changes_from_tree`	Find the differences between the contents of a tree and a working copy.
Function	`cleanup_mode`	Cleanup a mode value.
Function	`commit_index`	Create a new tree from an index.
Function	`commit_tree`	Commit a new tree.
Function	`detect_case_only_renames`	Detect and transform case-only renames in a list of tree changes.
Function	`get_path_element_normalizer`	Get the appropriate path element normalization function based on config.
Function	`get_unstaged_changes`	Walk through an index and check for differences against working tree.
Function	`index_entry_from_directory`	Create an index entry for a directory.
Function	`index_entry_from_path`	Create an index from a filesystem path.
Function	`index_entry_from_stat`	Create a new index entry from a stat value.
Function	`iter_fresh_entries`	Iterate over current versions of index entries on disk.
Function	`iter_fresh_objects`	Iterate over versions of objects on disk referenced by index.
Function	`make_path_normalizer`	Build a path normalizer honoring `core.ignorecase` and `core.precomposeunicode`.
Function	`pathjoin`	Join a /-delimited path.
Function	`pathsplit`	Split a /-delimited path into a directory part and a basename.
Function	`read_cache_entry`	Read an entry from a cache file.
Function	`read_cache_time`	Read a cache time.
Function	`read_index`	Read an index file, yielding the individual entries.
Function	`read_index_dict`	Read an index file and return it as a dictionary.
Function	`read_index_dict_with_version`	Read an index file and return it as a dictionary along with the version.
Function	`read_index_header`	Read an index header from a file.
Function	`read_submodule_head`	Read the head commit of a submodule.
Function	`refresh_index`	Refresh the contents of an index.
Function	`symlink`	Create a symbolic link on Windows with better error handling.
Function	`update_working_tree`	Update the working tree and index to match a new tree.
Function	`validate_path`	Default path validator that just checks for .git/.
Function	`validate_path_element_default`	Validate a path element using default rules.
Function	`validate_path_element_hfs`	Validate path element for HFS+ filesystem.
Function	`validate_path_element_ntfs`	Validate a path element using NTFS filesystem rules.
Function	`write_cache_entry`	Write an index entry to a file.
Function	`write_cache_time`	Write a cache time.
Function	`write_index`	Write an index file.
Function	`write_index_dict`	Write an index file based on the contents of a dictionary.
Function	`write_index_extension`	Write an index extension.
Constant	`DEFAULT_VERSION`	Undocumented
Constant	`EOIE_EXTENSION`	Undocumented
Constant	`EXTENDED_FLAG_INTEND_TO_ADD`	Undocumented
Constant	`EXTENDED_FLAG_SKIP_WORKTREE`	Undocumented
Constant	`FLAG_EXTENDED`	Undocumented
Constant	`FLAG_NAMEMASK`	Undocumented
Constant	`FLAG_STAGEMASK`	Undocumented
Constant	`FLAG_STAGESHIFT`	Undocumented
Constant	`FLAG_VALID`	Undocumented
Constant	`HFS_IGNORABLE_CHARS`	Undocumented
Constant	`IEOT_EXTENSION`	Undocumented
Constant	`INVALID_DOTNAMES`	Undocumented
Constant	`REUC_EXTENSION`	Undocumented
Constant	`SDIR_EXTENSION`	Undocumented
Constant	`TREE_EXTENSION`	Undocumented
Constant	`UNTR_EXTENSION`	Undocumented
Type Alias	`TreeDict`	Undocumented
Variable	`os_sep_bytes`	Undocumented
Function	`_check_entry_for_changes`	Check a single index entry for changes.
Function	`_check_file_matches`	Check if a file on disk matches the expected git object.
Function	`_check_symlink_matches`	Check if symlink target matches expected target.
Function	`_compress_path`	Compress a path relative to the previous path for index version 4.
Function	`_decode_varint`	Decode a variable-width encoded integer.
Function	`_decompress_path`	Decompress a path from index version 4 compressed format.
Function	`_decompress_path_from_stream`	Decompress a path from index version 4 compressed format, reading from stream.
Function	`_encode_varint`	Encode an integer using variable-width encoding.
Function	`_ensure_parent_dir_exists`	Ensure parent directory exists, checking no parent is a file.
Function	`_fs_to_tree_path`	Convert a file system path to a git tree path.
Function	`_has_directory_changed`	Check if a directory has changed after getting an error.
Function	`_normalize_path_element_default`	Normalize path element for default case-insensitive comparison.
Function	`_normalize_path_element_hfs`	Normalize path element for HFS+ filesystem.
Function	`_normalize_path_element_ntfs`	Normalize path element for NTFS filesystem.
Function	`_remove_empty_parents`	Remove empty parent directories up to stop_at.
Function	`_remove_file_with_readonly_handling`	Remove a file, handling read-only files on Windows.
Function	`_stat_matches_entry`	Check if filesystem stat matches index entry stat.
Function	`_transition_to_absent`	Remove any type of entry.
Function	`_transition_to_file`	Transition any type to regular file or symlink.
Function	`_transition_to_submodule`	Transition any type to submodule.
Function	`_tree_to_fs_path`	Convert a git tree path to a file system path.

def blob_from_path_and_mode(fs_path: bytes, mode: int, tree_encoding: str = 'utf-8') -> Blob: ¶

Create a blob from a path and a stat object.

Returns: A Blob object

Parameters
fs_path:`bytes`	Full file system path to file
mode:`int`	File mode
tree_encoding:`str`	Encoding to use for tree contents

Returns
`Blob`	Undocumented

def blob_from_path_and_stat(fs_path: bytes, st: os.stat_result, tree_encoding: str = 'utf-8') -> Blob: ¶

Create a blob from a path and a stat object.

Returns: A Blob object

Parameters
fs_path:`bytes`	Full file system path to file
st:`os.stat_result`	A stat object
tree_encoding:`str`	Encoding to use for tree contents

Returns
`Blob`	Undocumented

def build_file_from_blob(blob: Blob, mode: int, target_path: bytes, *, honor_filemode: bool = True, tree_encoding: str = 'utf-8', symlink_fn: Callable[[(str | bytes | os.PathLike[str]), (str | bytes | os.PathLike[str])], None] | None = None) -> os.stat_result: ¶

Build a file or symlink on disk based on a Git object.

Returns: stat object for the file

Parameters
blob:`Blob`	The git object
mode:`int`	File mode
target_path:`bytes`	Path to write to
honor_filemode:`bool`	An optional flag to honor core.filemode setting in config file, default is core.filemode=True, change executable bit
tree_encoding:`str`	Encoding to use for tree contents
symlink_fn:`Callable[[(str \| bytes \| os.PathLike[str]), (str \| bytes \| os.PathLike[str])], None] \| None`	Function to use for creating symlinks

Returns
`os.stat_result`	Undocumented

def build_index_from_tree(root_path: str | bytes, index_path: str | bytes, object_store: ObjectContainer, tree_id: ObjectID, honor_filemode: bool = True, validate_path_element: Callable[[bytes], bool] = validate_path_element_default, symlink_fn: Callable[[(str | bytes | os.PathLike[str]), (str | bytes | os.PathLike[str])], None] | None = None, blob_normalizer: FilterBlobNormalizer | None = None, tree_encoding: str = 'utf-8'): ¶

Generate and materialize index from a tree.

Note: existing index is wiped and contents are not merged: in a working dir. Suitable only for fresh clones.

Parameters
root_path:`str \| bytes`	Target dir for materialized index files
index_path:`str \| bytes`	Target path for generated index
object_store:`ObjectContainer`	Non-empty object store holding tree contents
tree_id:`ObjectID`	Tree to materialize
honor_filemode:`bool`	An optional flag to honor core.filemode setting in config file, default is core.filemode=True, change executable bit
validate_path_element:`Callable[[bytes], bool]`	Function to validate path elements to check out; default just refuses .git and .. directories.
symlink_fn:`Callable[[(str \| bytes \| os.PathLike[str]), (str \| bytes \| os.PathLike[str])], None] \| None`	Function to use for creating symlinks
blob_normalizer:`FilterBlobNormalizer \| None`	An optional BlobNormalizer to use for converting line endings when writing blobs to the working directory.
tree_encoding:`str`	Encoding used for tree paths (default: utf-8)

Find the differences between the contents of a tree and a working copy.

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

Parameters
names:`Iterable[bytes]`	Iterable of names in the working copy
lookup_entry:`Callable[[bytes], tuple[bytes, int]]`	Function to lookup an entry in the working copy
object_store:`ObjectContainer`	Object store to use for retrieving tree contents
tree:`ObjectID \| None`	SHA1 of the root tree, or None for an empty tree
want_unchanged:`bool`	Whether unchanged files should be reported

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

def cleanup_mode(mode: int) -> int: ¶

Cleanup a mode value.

This will return a mode that can be stored in a tree object.

Parameters
mode:`int`	Mode to clean up.

Returns
`int`	mode

def commit_index(object_store: ObjectContainer, index: Index) -> ObjectID: ¶

Create a new tree from an index.

Note: This function is deprecated, use index.commit() instead. Returns: Root tree sha.

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

Returns
`ObjectID`	Undocumented

def commit_tree(object_store: ObjectContainer, blobs: Iterable[tuple[bytes, ObjectID, int]]) -> ObjectID: ¶

Commit a new tree.

Parameters
object_store:`ObjectContainer`	Object store to add trees to
blobs:`Iterable[tuple[bytes, ObjectID, int]]`	Iterable over blob path, sha, mode entries

Returns
`ObjectID`	SHA1 of the created tree.

def detect_case_only_renames(changes: Sequence[TreeChange], config: Config) -> list[TreeChange]: ¶

Detect and transform case-only renames in a list of tree changes.

This function identifies file renames that only differ in case (e.g., README.txt -> readme.txt) and transforms matching ADD/DELETE pairs into CHANGE_RENAME operations. It uses filesystem-appropriate path normalization based on the repository configuration.

Parameters
changes:`Sequence[TreeChange]`	List of TreeChange objects representing file changes
config:`Config`	Repository configuration object

Returns
`list[TreeChange]`	New list of TreeChange objects with case-only renames converted to CHANGE_RENAME

def get_path_element_normalizer(config: Config) -> Callable[[bytes], bytes]: ¶

Get the appropriate path element normalization function based on config.

Parameters
config:`Config`	Repository configuration object

Returns
`Callable[[bytes], bytes]`	Function that normalizes path elements for the configured filesystem

def get_unstaged_changes(index: Index, root_path: str | bytes, filter_blob_callback: Callable[..., Any] | None = None, preload_index: bool = False, trust_ctime: bool = True, max_stat: int | None = None) -> Generator[bytes, None, None]: ¶

Walk through an index and check for differences against working tree.

Returns: iterator over paths with unstaged changes

Parameters
index:`Index`	index to check
root_path:`str \| bytes`	path in which to find files
filter_blob_callback:`Callable[..., Any] \| None`	Optional callback to filter blobs
preload_index:`bool`	If True, use parallel threads to check files (requires threading support)
trust_ctime:`bool`	If True, use ctime for change detection (default: True)
max_stat:`int \| None`	If set, limit the number of stat operations performed. When the limit is reached, remaining files are assumed unchanged.

Returns
`Generator[bytes, None, None]`	Undocumented

def index_entry_from_directory(st: os.stat_result, path: bytes) -> IndexEntry | None: ¶

Create an index entry for a directory.

This is only used for submodules (directories containing .git).

Parameters
st:`os.stat_result`	Stat result for the directory
path:`bytes`	Path to the directory

Returns
`IndexEntry \| None`	IndexEntry for a submodule, or None if not a submodule

def index_entry_from_path(path: bytes, object_store: ObjectContainer | None = None) -> IndexEntry | None: ¶

Create an index from a filesystem path.

This returns an index value for files, symlinks and tree references. for directories and non-existent files it returns None

Returns: An index entry; None for directories

Parameters
path:`bytes`	Path to create an index entry for
object_store:`ObjectContainer \| None`	Optional object store to save new blobs in

Returns
`IndexEntry \| None`	Undocumented

def index_entry_from_stat(stat_val: os.stat_result, hex_sha: bytes, mode: int | None = None) -> IndexEntry: ¶

Create a new index entry from a stat value.

Parameters
stat_val:`os.stat_result`	POSIX stat_result instance
hex_sha:`bytes`	Hex sha of the object
mode:`int \| None`	Optional file mode, will be derived from stat if not provided

Returns
`IndexEntry`	Undocumented

def iter_fresh_entries(paths: Iterable[bytes], root_path: bytes, object_store: ObjectContainer | None = None) -> Iterator[tuple[bytes, IndexEntry | None]]: ¶

Iterate over current versions of index entries on disk.

Returns: Iterator over path, index_entry

Parameters
paths:`Iterable[bytes]`	Paths to iterate over
root_path:`bytes`	Root path to access from
object_store:`ObjectContainer \| None`	Optional store to save new blobs in

Returns
`Iterator[tuple[bytes, IndexEntry \| None]]`	Undocumented

def iter_fresh_objects(paths: Iterable[bytes], root_path: bytes, include_deleted: bool = False, object_store: ObjectContainer | None = None) -> Iterator[tuple[bytes, ObjectID | None, int | None]]: ¶

Iterate over versions of objects on disk referenced by index.

Returns: Iterator over path, sha, mode

Parameters
paths:`Iterable[bytes]`	Paths to check
root_path:`bytes`	Root path to access from
include_deleted:`bool`	Include deleted entries with sha and mode set to None
object_store:`ObjectContainer \| None`	Optional object store to report new items to

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

def make_path_normalizer(config: Config) -> Callable[[bytes], bytes] | None: ¶

Build a path normalizer honoring core.ignorecase and core.precomposeunicode.

The returned callable maps a filesystem-form path to a canonical form used to match equivalent paths (e.g. Foo.txt ↔ foo.txt when core.ignorecase=true, NFD ↔ NFC when core.precomposeunicode=true). Returns None when neither option is active so callers can skip the comparison entirely.

def pathjoin(*args: bytes) -> bytes: ¶

Join a /-delimited path.

def pathsplit(path: bytes) -> tuple[bytes, bytes]: ¶

Split a /-delimited path into a directory part and a basename.

Parameters
path:`bytes`	The path to split.

Returns
`tuple[bytes, bytes]`	Tuple with directory name and basename

def read_cache_entry(f: BinaryIO, version: int, previous_path: bytes = b'') -> SerializedIndexEntry: ¶

Read an entry from a cache file.

Parameters
f:`BinaryIO`	File-like object to read from
version:`int`	Index version
previous_path:`bytes`	Previous entry's path (for version 4 compression)

Returns
`SerializedIndexEntry`	Undocumented

def read_cache_time(f: BinaryIO) -> tuple[int, int]: ¶

Read a cache time.

Parameters
f:`BinaryIO`	File-like object to read from

Returns
`tuple[int, int]`	Tuple with seconds and nanoseconds

def read_index(f: BinaryIO) -> Iterator[SerializedIndexEntry]: ¶

Read an index file, yielding the individual entries.

def read_index_dict(f: BinaryIO) -> dict[bytes, IndexEntry | ConflictedIndexEntry]: ¶

Read an index file and return it as a dictionary.

Dict Key is tuple of path and stage number, as

path alone is not unique

Parameters
f:`BinaryIO`	File object to read fromls.

Returns
`dict[bytes, IndexEntry \| ConflictedIndexEntry]`	Undocumented

def read_index_dict_with_version(f: BinaryIO) -> tuple[dict[bytes, IndexEntry | ConflictedIndexEntry], int, list[IndexExtension]]: ¶

Read an index file and return it as a dictionary along with the version.

Returns
`tuple[dict[bytes, IndexEntry \| ConflictedIndexEntry], int, list[IndexExtension]]`	tuple of (entries_dict, version, extensions)

def read_index_header(f: BinaryIO) -> tuple[int, int]: ¶

Read an index header from a file.

Returns
`tuple[int, int]`	tuple of (version, num_entries)

def read_submodule_head(path: str | bytes) -> bytes | None: ¶

Read the head commit of a submodule.

Returns: HEAD sha, None if not a valid head/repository

Parameters
path:`str \| bytes`	path to the submodule

Returns
`bytes \| None`	Undocumented

def refresh_index(index: Index, root_path: bytes): ¶

Refresh the contents of an index.

This is the equivalent to running 'git commit -a'.

Parameters
index:`Index`	Index to update
root_path:`bytes`	Root filesystem path

def symlink(src: str | bytes, dst: str | bytes, target_is_directory: bool = False, *, dir_fd: int | None = None): ¶

Create a symbolic link on Windows with better error handling.

Parameters
src:`str \| bytes`	Source path for the symlink
dst:`str \| bytes`	Destination path where symlink will be created
target_is_directory:`bool`	Whether the target is a directory
dir_fd:`int \| None`	Optional directory file descriptor

Raises
`WindowsSymlinkPermissionError`	If symlink creation fails due to permissions

def update_working_tree(repo: Repo, old_tree_id: bytes | None, new_tree_id: bytes, change_iterator: Iterator[TreeChange], honor_filemode: bool = True, validate_path_element: Callable[[bytes], bool] | None = None, symlink_fn: Callable[[(str | bytes | os.PathLike[str]), (str | bytes | os.PathLike[str])], None] | None = None, force_remove_untracked: bool = False, blob_normalizer: FilterBlobNormalizer | None = None, tree_encoding: str = 'utf-8', allow_overwrite_modified: bool = False): ¶

Update the working tree and index to match a new tree.

This function handles: - Adding new files - Updating modified files - Removing deleted files - Cleaning up empty directories

Parameters
repo:`Repo`	Repository object
old_tree_id:`bytes \| None`	SHA of the tree before the update
new_tree_id:`bytes`	SHA of the tree to update to
change_iterator:`Iterator[TreeChange]`	Iterator of TreeChange objects to apply
honor_filemode:`bool`	An optional flag to honor core.filemode setting
validate_path_element:`Callable[[bytes], bool] \| None`	Function to validate path elements to check out
symlink_fn:`Callable[[(str \| bytes \| os.PathLike[str]), (str \| bytes \| os.PathLike[str])], None] \| None`	Function to use for creating symlinks
force_remove_untracked:`bool`	If True, remove files that exist in working directory but not in target tree, even if old_tree_id is None
blob_normalizer:`FilterBlobNormalizer \| None`	An optional BlobNormalizer to use for converting line endings when writing blobs to the working directory.
tree_encoding:`str`	Encoding used for tree paths (default: utf-8)
allow_overwrite_modified:`bool`	If False, raise an error when attempting to overwrite files that have been modified compared to old_tree_id

def validate_path(path: bytes, element_validator: Callable[[bytes], bool] = validate_path_element_default) -> bool: ¶

Default path validator that just checks for .git/.

def validate_path_element_default(element: bytes) -> bool: ¶

Validate a path element using default rules.

Parameters
element:`bytes`	Path element to validate

Returns
`bool`	True if path element is valid, False otherwise

def validate_path_element_hfs(element: bytes) -> bool: ¶

Validate path element for HFS+ filesystem.

Equivalent to Git's is_hfs_dotgit and related checks. Uses NFD normalization and ignores HFS+ ignorable characters.

def validate_path_element_ntfs(element: bytes) -> bool: ¶

Validate a path element using NTFS filesystem rules.

Parameters
element:`bytes`	Path element to validate

Returns
`bool`	True if path element is valid for NTFS, False otherwise

def write_cache_entry(f: IO[bytes], entry: SerializedIndexEntry, version: int, previous_path: bytes = b''): ¶

Write an index entry to a file.

Parameters
f:`IO[bytes]`	File object
entry:`SerializedIndexEntry`	IndexEntry to write
version:`int`	Index format version
previous_path:`bytes`	Previous entry's path (for version 4 compression)

def write_cache_time(f: IO[bytes], t: int | float | tuple[int, int]): ¶

Write a cache time.

Parameters
f:`IO[bytes]`	File-like object to write to
t:`int \| float \| tuple[int, int]`	Time to write (as int, float or tuple with secs and nsecs)

def write_index(f: IO[bytes], entries: Sequence[SerializedIndexEntry], version: int | None = None, extensions: Sequence[IndexExtension] | None = None): ¶

Write an index file.

Parameters
f:`IO[bytes]`	File-like object to write to
entries:`Sequence[SerializedIndexEntry]`	Iterable over the entries to write
version:`int \| None`	Version number to write
extensions:`Sequence[IndexExtension] \| None`	Optional list of extensions to write

def write_index_dict(f: IO[bytes], entries: Mapping[bytes, IndexEntry | ConflictedIndexEntry], version: int | None = None, extensions: Sequence[IndexExtension] | None = None): ¶

Write an index file based on the contents of a dictionary.

being careful to sort by path and then by stage.

def write_index_extension(f: IO[bytes], extension: IndexExtension): ¶

Write an index extension.

Parameters
f:`IO[bytes]`	File-like object to write to
extension:`IndexExtension`	Extension to write

DEFAULT_VERSION: int = ¶

Undocumented

Value

EOIE_EXTENSION: bytes = ¶

Undocumented

Value

b'EOIE'

EXTENDED_FLAG_INTEND_TO_ADD: int = ¶

Undocumented

Value

EXTENDED_FLAG_SKIP_WORKTREE: int = ¶

Undocumented

Value

FLAG_EXTENDED: int = ¶

Undocumented

Value

FLAG_NAMEMASK: int = ¶

Undocumented

Value

FLAG_STAGEMASK: int = ¶

Undocumented

Value

FLAG_STAGESHIFT: int = ¶

Undocumented

Value

FLAG_VALID: int = ¶

Undocumented

Value

HFS_IGNORABLE_CHARS: set[int] = ¶

Undocumented

Value

IEOT_EXTENSION: bytes = ¶

Undocumented

Value

b'IEOT'

INVALID_DOTNAMES: tuple[bytes, ...] = ¶

Undocumented

Value

(b'.git', b'.', b'..', b'')

REUC_EXTENSION: bytes = ¶

Undocumented

Value

b'REUC'

SDIR_EXTENSION: bytes = ¶

Undocumented

Value

b'sdir'

TREE_EXTENSION: bytes = ¶

Undocumented

Value

b'TREE'

UNTR_EXTENSION: bytes = ¶

Undocumented

Value

b'UNTR'

TreeDict = ¶

Undocumented

Value

dict[bytes, TreeDict | tuple[int, ObjectID]]

os_sep_bytes = ¶

Undocumented

def _check_entry_for_changes(tree_path: bytes, entry: IndexEntry | ConflictedIndexEntry, root_path: bytes, filter_blob_callback: Callable[[Blob, bytes], Blob] | None = None, trust_ctime: bool = True) -> bytes | None: ¶

Check a single index entry for changes.

Returns: tree_path if changed, None otherwise

Parameters
tree_path:`bytes`	Path in the tree
entry:`IndexEntry \| ConflictedIndexEntry`	Index entry to check
root_path:`bytes`	Root filesystem path
filter_blob_callback:`Callable[[Blob, bytes], Blob] \| None`	Optional callback to filter blobs
trust_ctime:`bool`	If True, use ctime for change detection (default: True)

Returns
`bytes \| None`	Undocumented

def _check_file_matches(repo_object_store: BaseObjectStore, full_path: bytes, entry_sha: ObjectID, entry_mode: int, current_stat: os.stat_result, honor_filemode: bool, blob_normalizer: FilterBlobNormalizer | None = None, tree_path: bytes | None = None) -> bool: ¶

Check if a file on disk matches the expected git object.

Returns True if file matches, False if it doesn't match.

def _check_symlink_matches(full_path: bytes, repo_object_store: BaseObjectStore, entry_sha: ObjectID) -> bool: ¶

Check if symlink target matches expected target.

Returns True if symlink matches, False if it doesn't match.

def _compress_path(path: bytes, previous_path: bytes) -> bytes: ¶

Compress a path relative to the previous path for index version 4.

Parameters
path:`bytes`	Path to compress
previous_path:`bytes`	Previous path for comparison

Returns
`bytes`	Compressed path data (varint prefix_len + suffix)

def _decode_varint(data: bytes, offset: int = 0) -> tuple[int, int]: ¶

Decode a variable-width encoded integer.

Parameters
data:`bytes`	Bytes to decode from
offset:`int`	Starting offset in data

Returns
`tuple[int, int]`	tuple of (decoded_value, new_offset)

def _decompress_path(data: bytes, offset: int, previous_path: bytes) -> tuple[bytes, int]: ¶

Decompress a path from index version 4 compressed format.

Parameters
data:`bytes`	Raw data containing compressed path
offset:`int`	Starting offset in data
previous_path:`bytes`	Previous path for decompression

Returns
`tuple[bytes, int]`	tuple of (decompressed_path, new_offset)

def _decompress_path_from_stream(f: BinaryIO, previous_path: bytes) -> tuple[bytes, int]: ¶

Decompress a path from index version 4 compressed format, reading from stream.

Parameters
f:`BinaryIO`	File-like object to read from
previous_path:`bytes`	Previous path for decompression

Returns
`tuple[bytes, int]`	tuple of (decompressed_path, bytes_consumed)

def _encode_varint(value: int) -> bytes: ¶

Encode an integer using variable-width encoding.

Same format as used for OFS_DELTA pack entries and index v4 path compression. Uses 7 bits per byte, with the high bit indicating continuation.

Parameters
value:`int`	Integer to encode

Returns
`bytes`	Encoded bytes

def _ensure_parent_dir_exists(full_path: bytes): ¶

Ensure parent directory exists, checking no parent is a file.

def _fs_to_tree_path(fs_path: str | bytes, tree_encoding: str = 'utf-8') -> bytes: ¶

Convert a file system path to a git tree path.

Returns: Git tree path as bytes (encoded with tree_encoding)

Parameters
fs_path:`str \| bytes`	File system path.
tree_encoding:`str`	Encoding to use for tree paths (default: utf-8)

Returns
`bytes`	Undocumented

def _has_directory_changed(tree_path: bytes, entry: IndexEntry) -> bool: ¶

Check if a directory has changed after getting an error.

When handling an error trying to create a blob from a path, call this function. It will check if the path is a directory. If it's a directory and a submodule, check the submodule head to see if it's has changed. If not, consider the file as changed as Git tracked a file and not a directory.

Return true if the given path should be considered as changed and False otherwise or if the path is not a directory.

def _normalize_path_element_default(element: bytes) -> bytes: ¶

Normalize path element for default case-insensitive comparison.

def _normalize_path_element_hfs(element: bytes) -> bytes: ¶

Normalize path element for HFS+ filesystem.

def _normalize_path_element_ntfs(element: bytes) -> bytes: ¶

Normalize path element for NTFS filesystem.

def _remove_empty_parents(path: bytes, stop_at: bytes): ¶

Remove empty parent directories up to stop_at.

def _remove_file_with_readonly_handling(path: bytes): ¶

Remove a file, handling read-only files on Windows.

Parameters
path:`bytes`	Path to the file to remove

def _stat_matches_entry(st: os.stat_result, entry: IndexEntry, trust_ctime: bool = True) -> bool: ¶

Check if filesystem stat matches index entry stat.

This is used to determine if a file might have changed without reading its content. Git uses this optimization to avoid expensive filter operations on unchanged files.

Returns: True if stat matches and file is likely unchanged

Parameters
st:`os.stat_result`	Filesystem stat result
entry:`IndexEntry`	Index entry to compare against
trust_ctime:`bool`	If True, also check ctime (default: True, matching Git behavior)

Returns
`bool`	Undocumented

def _transition_to_absent(repo: Repo, path: bytes, full_path: bytes, current_stat: os.stat_result | None, index: Index): ¶

Remove any type of entry.

def _transition_to_file(object_store: BaseObjectStore, path: bytes, full_path: bytes, current_stat: os.stat_result | None, entry: IndexEntry | TreeEntry, index: Index, honor_filemode: bool, symlink_fn: Callable[[(str | bytes | os.PathLike[str]), (str | bytes | os.PathLike[str])], None] | None, blob_normalizer: FilterBlobNormalizer | None, tree_encoding: str = 'utf-8'): ¶

Transition any type to regular file or symlink.

def _transition_to_submodule(repo: Repo, path: bytes, full_path: bytes, current_stat: os.stat_result | None, entry: IndexEntry | TreeEntry, index: Index): ¶

Transition any type to submodule.

def _tree_to_fs_path(root_path: bytes, tree_path: bytes, tree_encoding: str = 'utf-8') -> bytes: ¶

Convert a git tree path to a file system path.

Returns: File system path.

Parameters
root_path:`bytes`	Root filesystem path
tree_path:`bytes`	Git tree path as bytes (encoded with tree_encoding)
tree_encoding:`str`	Encoding used for tree paths (default: utf-8)

Returns
`bytes`	Undocumented