Submodules

A submodule is a foreign repository that is embedded within a dedicated subdirectory of the repositories tree.

class pygit2.Repository(path: str | None = None, flags: ~pygit2.enums.RepositoryOpenFlag = <RepositoryOpenFlag.DEFAULT: 0>)

submodules: The collection of submodules, an instance of pygit2.submodules.SubmoduleCollection

listall_submodules() → list[str]: Return a list with all submodule paths in the repository.

class pygit2.submodules.SubmoduleCollection(repository: BaseRepository)

Collection of submodules in a repository.

add(url: str, path: str, link: bool = True, callbacks: RemoteCallbacks | None = None, depth: int = 0) → Submodule

Add a submodule to the index. The submodule is automatically cloned.

Returns: the submodule that was added.

Parameters:

url: The URL of the submodule.
path: The path within the parent repository to add the submodule
link: Should workdir contain a gitlink to the repo in .git/modules vs. repo directly in workdir.
callbacks: Optional RemoteCallbacks to clone the submodule.
depth: Number of commits to fetch. The default is 0 (full commit history).

cache_all()

Load and cache all submodules in the repository.

Because the .gitmodules file is unstructured, loading submodules is an O(N) operation. Any operation that requires accessing all submodules is O(N^2) in the number of submodules, if it has to look each one up individually. This function loads all submodules and caches them so that subsequent submodule lookups by name are O(1).

cache_clear()

Clear the submodule cache populated by submodule_cache_all. If there is no cache, do nothing.

The cache incorporates data from the repository’s configuration, as well as the state of the working tree, the index, and HEAD. So any time any of these has changed, the cache might become invalid.

get(name: str) → Submodule | None: Look up submodule information by name or path. Unlike __getitem__, this returns None if the submodule is not found.

init(submodules: Iterable[str] | None = None, overwrite: bool = False)

Initialize submodules in the repository. Just like “git submodule init”, this copies information about the submodules into “.git/config”.

Parameters:

submodules: Optional list of submodule paths or names to initialize. Default argument initializes all submodules.
overwrite: Flag indicating if initialization should overwrite submodule entries.

status(name: str, ignore: SubmoduleIgnore = SubmoduleIgnore.UNSPECIFIED) → SubmoduleStatus

Get the status of a submodule.

Returns: A combination of SubmoduleStatus flags.

Parameters:

name: Submodule name or path.
ignore: A SubmoduleIgnore value indicating how deeply to examine the working directory.

update(submodules: Iterable[str] | None = None, init: bool = False, callbacks: RemoteCallbacks | None = None, depth: int = 0)

Update submodules. This will clone a missing submodule and checkout the subrepository to the commit specified in the index of the containing repository. If the submodule repository doesn’t contain the target commit (e.g. because fetchRecurseSubmodules isn’t set), then the submodule is fetched using the fetch options supplied in options.

Parameters:

submodules: Optional list of submodule paths or names. If you omit this parameter or pass None, all submodules will be updated.
init: If the submodule is not initialized, setting this flag to True will initialize the submodule before updating. Otherwise, this will raise an error if attempting to update an uninitialized repository.
callbacks: Optional RemoteCallbacks to clone or fetch the submodule.
depth: Number of commits to fetch. The default is 0 (full commit history).

The Submodule type

class pygit2.Submodule

property branch: Branch that is to be tracked by the submodule.

property head_id: Oid | None: The submodule’s HEAD commit id (as recorded in the superproject’s current HEAD tree). Returns None if the superproject’s HEAD doesn’t contain the submodule.

init(overwrite: bool = False)

Just like “git submodule init”, this copies information about the submodule into “.git/config”.

Parameters:

overwrite: By default, existing submodule entries will not be overwritten, but setting this to True forces them to be updated.

property name: Name of the submodule.

open(): Open the repository for a submodule.

property path: Path of the submodule.

reload(force: bool = False)

Reread submodule info from config, index, and HEAD.

Call this to reread cached submodule information for this submodule if you have reason to believe that it has changed.

Parameters:

force: Force reload even if the data doesn’t seem out of date

update(init: bool = False, callbacks: RemoteCallbacks = None, depth: int = 0)

Update a submodule. This will clone a missing submodule and checkout the subrepository to the commit specified in the index of the containing repository. If the submodule repository doesn’t contain the target commit (e.g. because fetchRecurseSubmodules isn’t set), then the submodule is fetched using the fetch options supplied in options.

Parameters:

init: If the submodule is not initialized, setting this flag to True will initialize the submodule before updating. Otherwise, this will raise an error if attempting to update an uninitialized repository.
callbacks: Optional RemoteCallbacks to clone or fetch the submodule.
depth: Number of commits to fetch. The default is 0 (full commit history).

property url: str | None: URL of the submodule.