dulwich.index module

Parser for the git index file format.

class dulwich.index.Index(filename)

Bases: object

A Git Index file.

Open an index file.

Parameters

filename – Path to the index file

changes_from_tree(object_store, tree, want_unchanged=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()
iterblobs()
iteritems()
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)
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

dulwich.index.blob_from_path_and_mode(fs_path, mode, 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.blob_from_path_and_stat(fs_path, 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, mode, target_path, honor_filemode=True, tree_encoding='utf-8')

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

Parameters
  • obj – 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

Returns: stat object for the file

dulwich.index.build_index_from_tree(root_path, index_path, object_store, tree_id, honor_filemode=True, validate_path_element=<function validate_path_element_default>)

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: dulwich.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: dulwich.index.Index, root_path, 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_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-existant 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_blobs(index, root_path)

Iterate over versions of blobs on disk referenced by index.

Don’t use this function; it removes missing entries from index.

Parameters
  • index – Index file

  • root_path – Root path to access from

  • include_deleted – Include deleted entries with sha and mode set to None

Returns: Iterator over path, sha, mode

dulwich.index.iter_fresh_entries(paths, root_path, object_store: Optional[BaseObjectStore] = None)

Iterate over current versions of index entries on disk.

Parameters
  • paths – Paths to iterate over

  • root_path – Root path to access from

  • store – Optional store to save new blobs in

Returns: Iterator over path, index_entry

dulwich.index.iter_fresh_objects(paths, root_path, include_deleted=False, object_store=None)

Iterate over versions of objecs 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

dulwich.index.pathjoin(*args)

Join a /-delimited path.

dulwich.index.pathsplit(path)

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

Read an index file and return it as a dictionary.

Parameters

f – File object to read from

dulwich.index.read_submodule_head(path)

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, root_path)

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, element_validator=<function validate_path_element_default>)

Default path validator that just checks for .git/.

dulwich.index.validate_path_element_default(element)
dulwich.index.validate_path_element_ntfs(element)
dulwich.index.write_cache_entry(f, name, entry, version)

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, dulwich.index.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, dulwich.index.IndexEntry], version: Optional[int] = None)None

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