# 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.