dulwich.index module

Parser for the git index file format.

class dulwich.index.Index(filename: Union[bytes, str], read=True)

Bases: object

A Git Index file.

Create an index object associated with the given filename.

Parameters

  • filename – Path to the index file

  • read – Whether to initialize the index from the given file, should it exist.

changes_from_tree(object_store, tree: bytes, want_unchanged: bool = False)

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

Parameters

  • object_store – Object store to use for retrieving tree contents

  • tree – SHA1 of the root tree

  • want_unchanged – Whether unchanged files should be reported

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

newmode), (oldsha, newsha)

clear()

Remove all contents from this index.

commit(object_store)

Create a new tree from an index.

Parameters

object_store – Object store to save the tree in

Returns

Root tree SHA

get_mode(path: bytes) → int

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

get_sha1(path: bytes) → bytes

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

items() → Iterator[Tuple[bytes, IndexEntry]]
iteritems() → Iterator[Tuple[bytes, IndexEntry]]
iterobjects() → Iterable[Tuple[bytes, bytes, int]]

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

property path
read()

Read current contents of index from disk.

update(entries: Dict[bytes, IndexEntry])
write() → None

Write current contents of index to disk.

class dulwich.index.IndexEntry(ctime, mtime, dev, ino, mode, uid, gid, size, sha, flags, extended_flags)

Bases: tuple

Create new instance of IndexEntry(ctime, mtime, dev, ino, mode, uid, gid, size, sha, flags, extended_flags)

ctime

Alias for field number 0

dev

Alias for field number 2

extended_flags

Alias for field number 10

flags

Alias for field number 9

gid

Alias for field number 6

ino

Alias for field number 3

mode

Alias for field number 4

mtime

Alias for field number 1

sha

Alias for field number 8

size

Alias for field number 7

uid

Alias for field number 5

exception dulwich.index.UnsupportedIndexFormat(version)

Bases: Exception

An unsupported index format was encountered.

dulwich.index.blob_from_path_and_mode(fs_path: bytes, mode: int, tree_encoding='utf-8')

Create a blob from a path and a stat object.

Parameters

  • fs_path – Full file system path to file

  • mode – File mode

Returns: A Blob object

dulwich.index.blob_from_path_and_stat(fs_path: bytes, st, tree_encoding='utf-8')

Create a blob from a path and a stat object.

Parameters

  • fs_path – Full file system path to file

  • st – A stat object

Returns: A Blob object

dulwich.index.build_file_from_blob(blob: Blob, mode: int, target_path: bytes, *, honor_filemode=True, tree_encoding='utf-8', symlink_fn=None)

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

Parameters

  • blob – The git object

  • mode – File mode

  • target_path – 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

  • symlink – Function to use for creating symlinks

Returns: stat object for the file

dulwich.index.build_index_from_tree(root_path: ~typing.Union[str, bytes], index_path: ~typing.Union[str, bytes], object_store: BaseObjectStore, tree_id: bytes, honor_filemode: bool = True, validate_path_element=<function validate_path_element_default>, symlink_fn=None)

Generate and materialize index from a tree

Parameters

  • tree_id – Tree to materialize

  • root_path – Target dir for materialized index files

  • index_path – Target path for generated index

  • object_store – Non-empty object store holding tree contents

  • honor_filemode – 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.

Note: existing index is wiped and contents are not merged

in a working dir. Suitable only for fresh clones.

dulwich.index.changes_from_tree(names: Iterable[bytes], lookup_entry: Callable[[bytes], Tuple[bytes, int]], object_store: BaseObjectStore, tree: Optional[bytes], want_unchanged=False) → Iterable[Tuple[Tuple[Optional[bytes], Optional[bytes]], Tuple[Optional[int], Optional[int]], Tuple[Optional[bytes], Optional[bytes]]]]

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

Parameters

  • names – Iterable of names in the working copy

  • lookup_entry – Function to lookup an entry in the working copy

  • object_store – Object store to use for retrieving tree contents

  • tree – SHA1 of the root tree, or None for an empty tree

  • want_unchanged – Whether unchanged files should be reported

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

(oldsha, newsha)

dulwich.index.cleanup_mode(mode: int) → int

Cleanup a mode value.

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

Parameters

mode – Mode to clean up.

Returns

mode

dulwich.index.commit_index(object_store: BaseObjectStore, index: Index) → bytes

Create a new tree from an index.

Parameters

  • object_store – Object store to save the tree in

  • index – Index file

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

dulwich.index.commit_tree(object_store: BaseObjectStore, blobs: Iterable[Tuple[bytes, bytes, int]]) → bytes

Commit a new tree.

Parameters

  • object_store – Object store to add trees to

  • blobs – Iterable over blob path, sha, mode entries

Returns

SHA1 of the created tree.

dulwich.index.get_unstaged_changes(index: Index, root_path: Union[str, bytes], filter_blob_callback=None)

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

Parameters

  • index – index to check

  • root_path – path in which to find files

Returns: iterator over paths with unstaged changes

dulwich.index.index_entry_from_directory(st, path: bytes) → Optional[IndexEntry]
dulwich.index.index_entry_from_path(path: bytes, object_store: Optional[BaseObjectStore] = None) → Optional[IndexEntry]

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

Parameters

  • path – Path to create an index entry for

  • object_store – Optional object store to save new blobs in

Returns: An index entry; None for directories

dulwich.index.index_entry_from_stat(stat_val, hex_sha: bytes, flags: int, mode: Optional[int] = None, extended_flags: Optional[int] = None)

Create a new index entry from a stat value.

Parameters

  • stat_val – POSIX stat_result instance

  • hex_sha – Hex sha of the object

  • flags – Index flags

dulwich.index.iter_fresh_entries(paths: Iterable[bytes], root_path: bytes, object_store: Optional[BaseObjectStore] = None) → Iterator[Tuple[bytes, Optional[IndexEntry]]]

Iterate over current versions of index entries on disk.

Parameters

  • paths – Paths to iterate over

  • root_path – Root path to access from

  • object_store – Optional store to save new blobs in

Returns: Iterator over path, index_entry

dulwich.index.iter_fresh_objects(paths: Iterable[bytes], root_path: bytes, include_deleted=False, object_store=None) → Iterator[Tuple[bytes, Optional[bytes], Optional[int]]]

Iterate over versions of objects on disk referenced by index.

Parameters

  • root_path – 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 over path, sha, mode

class dulwich.index.locked_index(path: Union[bytes, str])

Bases: object

Lock the index while making modifications.

Works as a context manager.

dulwich.index.pathjoin(*args)

Join a /-delimited path.

dulwich.index.pathsplit(path: bytes) → Tuple[bytes, bytes]

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

Parameters

path – The path to split.

Returns

Tuple with directory name and basename

dulwich.index.read_cache_entry(f, version: int) → Tuple[str, IndexEntry]

Read an entry from a cache file.

Parameters

f – File-like object to read from

Returns

name, IndexEntry

Return type

tuple with

dulwich.index.read_cache_time(f)

Read a cache time.

Parameters

f – File-like object to read from

Returns

Tuple with seconds and nanoseconds

dulwich.index.read_index(f: BinaryIO)

Read an index file, yielding the individual entries.

dulwich.index.read_index_dict(f) → Dict[bytes, IndexEntry]

Read an index file and return it as a dictionary.

Parameters

f – File object to read from

dulwich.index.read_submodule_head(path: Union[str, bytes]) → Optional[bytes]

Read the head commit of a submodule.

Parameters

path – path to the submodule

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

dulwich.index.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 to update

  • root_path – Root filesystem path

dulwich.index.validate_path(path: bytes, element_validator=<function validate_path_element_default>) → bool

Default path validator that just checks for .git/.

dulwich.index.validate_path_element_default(element: bytes) → bool
dulwich.index.validate_path_element_ntfs(element: bytes) → bool
dulwich.index.write_cache_entry(f, name: bytes, entry: IndexEntry, version: int) → None

Write an index entry to a file.

Parameters

  • f – File object

  • entry – IndexEntry to write, tuple with:

dulwich.index.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)

dulwich.index.write_index(f: BinaryIO, entries: List[Tuple[bytes, IndexEntry]], version: Optional[int] = None)

Write an index file.

Parameters

  • f – File-like object to write to

  • version – Version number to write

  • entries – Iterable over the entries to write

dulwich.index.write_index_dict(f: BinaryIO, entries: Dict[bytes, IndexEntry], version: Optional[int] = None) → None

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