The use of custom backends for the git object database (odb) and reference database (refdb) are supported by pygit2.

The OdbBackend class

The OdbBackend class is subclassable and can be used to build a custom object database.

class pygit2.OdbBackend

Object database backend.

exists(oid: Oid) bool

Returns true if the given oid can be found in this odb.

exists_prefix(partial_id: Oid) Oid

Given a partial oid, returns the full oid. Raises KeyError if not found, or ValueError if ambiguous.


Read raw object data from this odb backend.


Read raw object header from this odb backend.

read_prefix(oid: Oid) tuple[int, bytes, Oid]

Read raw object data from this odb backend based on an oid prefix. The returned tuple contains (type, data, oid).


If the backend supports a refreshing mechanism, this function will invoke it. However, the backend implementation should try to stay up-to-date as much as possible by itself as libgit2 will not automatically invoke this function. For instance, a potential strategy for the backend implementation to utilize this could be internally calling the refresh function on failed lookups.

Built-in OdbBackend implementations

class pygit2.OdbBackendLoose(objects_dir, compression_level, do_fsync, dir_mode=0, file_mode=0)

Object database backend for loose objects.



path to top-level object dir on disk


zlib compression level to use


true to fsync() after writing


mode for new directories, or 0 for default


mode for new files, or 0 for default

class pygit2.OdbBackendPack

Object database backend for packfiles.

The RefdbBackend class

The RefdbBackend class is subclassable and can be used to build a custom reference database.

class pygit2.RefdbBackend

Reference database backend.


Suggests that the implementation compress or optimize its references. This behavior is implementation-specific.

delete(ref_name: str, old_id: Oid, old_target: str)

Deletes a reference.

ensure_log(ref_name: str) bool

Ensure that a particular reference will have a reflog which will be appended to on writes.

exists(refname: str) bool

Returns True if a ref by this name exists, or False otherwise.

has_log(ref_name: str) bool

Returns True if a ref log is available for this reference. It may be empty even if it exists.

lookup(refname: str) Reference

Looks up a reference and returns it, or None if not found.

rename(old_name: str, new_name: str, force: bool, who: Signature, message: str) Reference

Renames a reference.

write(ref: Reference, force: bool, who: Signature, message: str, old: Oid, old_target: str)

Writes a new reference to the reference database.

Built-in RefdbBackend implementations

class pygit2.RefdbFsBackend(repo: Repository)

Reference database filesystem backend. The path to the repository is used as the basis of the reference database.