dulwich.index

module documentation

Parser for the git index file format.

Class	`Index`	A Git Index file.
Class	`locked_index`	Lock the index while making modifications.
Exception	`UnsupportedIndexFormat`	An unsupported index format was encountered.
Exception	`WindowsSymlinkPermissionError`	Undocumented
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	`get_unstaged_changes`	Walk through an index and check for differences against working tree.
Function	`index_entry_from_directory`	Undocumented
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	`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_submodule_head`	Read the head commit of a submodule.
Function	`refresh_index`	Refresh the contents of an index.
Function	`symlink`	Undocumented
Function	`validate_path`	Default path validator that just checks for .git/.
Function	`validate_path_element_default`	Undocumented
Function	`validate_path_element_ntfs`	Undocumented
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.
Constant	`DEFAULT_VERSION`	Undocumented
Constant	`EXTENDED_FLAG_INTEND_TO_ADD`	Undocumented
Constant	`EXTENDED_FLAG_SKIP_WORKTREE`	Undocumented
Constant	`FLAG_EXTENDED`	Undocumented
Constant	`FLAG_STAGEMASK`	Undocumented
Constant	`FLAG_VALID`	Undocumented
Constant	`INVALID_DOTNAMES`	Undocumented
Variable	`IndexEntry`	Undocumented
Variable	`os_sep_bytes`	Undocumented
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	`_tree_to_fs_path`	Convert a git tree path to a file system path.

def blob_from_path_and_mode(fs_path, mode, tree_encoding='utf-8'): ¶

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	Undocumented

def blob_from_path_and_stat(fs_path, st, tree_encoding='utf-8'): ¶

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	A stat object
tree_encoding	Undocumented

def build_file_from_blob(blob, mode, target_path, *, honor_filemode=True, tree_encoding='utf-8', symlink_fn=None): ¶

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	An optional flag to honor core.filemode setting in config file, default is core.filemode=True, change executable bit
tree_encoding	Undocumented
symlink_fn	Undocumented
symlink	Function to use for creating symlinks

def build_index_from_tree(root_path, index_path, object_store, tree_id, honor_filemode=True, validate_path_element=validate_path_element_default, symlink_fn=None): ¶

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:`Union[str, bytes]`	Target dir for materialized index files
index_path:`Union[str, bytes]`	Target path for generated index
object_store:`BaseObjectStore`	Non-empty object store holding tree contents
tree_id:`bytes`	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	Function to validate path elements to check out; default just refuses .git and .. directories.
symlink_fn	Undocumented

def changes_from_tree(names, lookup_entry, object_store, tree, want_unchanged=False): ¶

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:`BaseObjectStore`	Object store to use for retrieving tree contents
tree:`Optional[bytes]`	SHA1 of the root tree, or None for an empty tree
want_unchanged	Whether unchanged files should be reported
Returns
`Iterable[Tuple[Tuple[Optional[bytes], Optional[bytes]], Tuple[Optional[int], Optional[int]], Tuple[Optional[bytes], Optional[bytes]]]]`	Undocumented

def cleanup_mode(mode): ¶

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, index): ¶

Create a new tree from an index.

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

Parameters
object_store:`BaseObjectStore`	Object store to save the tree in
index:`Index`	Index file
Returns
`bytes`	Undocumented

def commit_tree(object_store, blobs): ¶

Commit a new tree.

Parameters
object_store:`BaseObjectStore`	Object store to add trees to
blobs:`Iterable[Tuple[bytes, bytes, int]]`	Iterable over blob path, sha, mode entries
Returns
`bytes`	SHA1 of the created tree.

def get_unstaged_changes(index, root_path, filter_blob_callback=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:`Union[str, bytes]`	path in which to find files
filter_blob_callback	Undocumented

def index_entry_from_directory(st, path): ¶

Undocumented

Parameters
st	Undocumented
path:`bytes`	Undocumented
Returns
`Optional[IndexEntry]`	Undocumented

def index_entry_from_path(path, object_store=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:`Optional[BaseObjectStore]`	Optional object store to save new blobs in
Returns
`Optional[IndexEntry]`	Undocumented

def index_entry_from_stat(stat_val, hex_sha, flags, mode=None, extended_flags=None): ¶

Create a new index entry from a stat value.

Parameters
stat_val	POSIX stat_result instance
hex_sha:`bytes`	Hex sha of the object
flags:`int`	Index flags
mode:`Optional[int]`	Undocumented
extended_flags:`Optional[int]`	Undocumented

def iter_fresh_entries(paths, root_path, object_store=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:`Optional[BaseObjectStore]`	Optional store to save new blobs in
Returns
`Iterator[Tuple[bytes, Optional[IndexEntry]]]`	Undocumented

def iter_fresh_objects(paths, root_path, include_deleted=False, object_store=None): ¶

Iterate over versions of objects on disk referenced by index.

Returns: Iterator over path, sha, mode

Parameters
paths:`Iterable[bytes]`	Undocumented
root_path:`bytes`	Root path to access from
include_deleted	Include deleted entries with sha and mode set to None
object_store	Optional object store to report new items to
Returns
`Iterator[Tuple[bytes, Optional[bytes], Optional[int]]]`	Undocumented

def pathjoin(*args): ¶

Join a /-delimited path.

def pathsplit(path): ¶

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, version): ¶

Read an entry from a cache file.

Parameters
f	File-like object to read from
version:`int`	Undocumented
Returns
tuple with	name, IndexEntry

def read_cache_time(f): ¶

Read a cache time.

Parameters
f	File-like object to read from
Returns
Tuple with seconds and nanoseconds

def read_index(f): ¶

Read an index file, yielding the individual entries.

Parameters
f:`BinaryIO`	Undocumented

def read_index_dict(f): ¶

Read an index file and return it as a dictionary.

Parameters
f	File object to read from
Returns
`Dict[bytes, IndexEntry]`	Undocumented

def read_submodule_head(path): ¶

Read the head commit of a submodule.

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

Parameters
path:`Union[str, bytes]`	path to the submodule
Returns
`Optional[bytes]`	Undocumented

def refresh_index(index, root_path): ¶

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, dst, target_is_directory=False, *, dir_fd=None): ¶

Undocumented

def validate_path(path, element_validator=validate_path_element_default): ¶

Default path validator that just checks for .git/.

Parameters
path:`bytes`	Undocumented
element_validator	Undocumented
Returns
`bool`	Undocumented

def validate_path_element_default(element): ¶

Undocumented

Parameters
element:`bytes`	Undocumented
Returns
`bool`	Undocumented

def validate_path_element_ntfs(element): ¶

Undocumented

Parameters
element:`bytes`	Undocumented
Returns
`bool`	Undocumented

def write_cache_entry(f, name, entry, version): ¶

Write an index entry to a file.

Parameters
f	File object
name:`bytes`	Undocumented
entry:`IndexEntry`	IndexEntry to write, tuple with:
version:`int`	Undocumented

def write_cache_time(f, t): ¶

Write a cache time.

Parameters
f	File-like object to write to
t	Time to write (as int, float or tuple with secs and nsecs)

def write_index(f, entries, version=None): ¶

Write an index file.

Parameters
f:`BinaryIO`	File-like object to write to
entries:`List[Tuple[bytes, IndexEntry]]`	Iterable over the entries to write
version:`Optional[int]`	Version number to write

def write_index_dict(f, entries, version=None): ¶

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

Parameters
f:`BinaryIO`	Undocumented
entries:`Dict[bytes, IndexEntry]`	Undocumented
version:`Optional[int]`	Undocumented

DEFAULT_VERSION: int = ¶

Undocumented

Value

EXTENDED_FLAG_INTEND_TO_ADD: int = ¶

Undocumented

Value

EXTENDED_FLAG_SKIP_WORKTREE: int = ¶

Undocumented

Value

FLAG_EXTENDED: int = ¶

Undocumented

Value

FLAG_STAGEMASK: int = ¶

Undocumented

Value

FLAG_VALID: int = ¶

Undocumented

Value

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

Undocumented

Value

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

IndexEntry = ¶

Undocumented

os_sep_bytes = ¶

Undocumented

def _fs_to_tree_path(fs_path): ¶

Convert a file system path to a git tree path.

Returns: Git tree path as bytes

Parameters
fs_path:`Union[str, bytes]`	File system path.
Returns
`bytes`	Undocumented

def _has_directory_changed(tree_path, entry): ¶

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.

Parameters
tree_path:`bytes`	Undocumented
entry	Undocumented

def _tree_to_fs_path(root_path, tree_path): ¶

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