submodule

For git-submodule(1).

Overview

Manage git submodules using GitSubmoduleManager (collection-level) and GitSubmoduleEntryCmd (per-submodule operations).

Note

GitSubmoduleCmd is the legacy interface. Use git.submodules (GitSubmoduleManager) for the new Manager/Cmd pattern.

Example

from libvcs.cmd.git import Git

git = Git(path='/path/to/repo')

# Add a submodule
git.submodules.add(url='https://github.com/org/lib.git', path='vendor/lib')

# List all submodules
submodules = git.submodules.ls()

# Get a specific submodule and operate on it
submodule = git.submodules.get(path='vendor/lib')
submodule.init()
submodule.update()
submodule.deinit()

# Sync submodule URLs
git.submodules.sync()

API Reference

class libvcs.cmd.git.GitSubmoduleManager

class

Bases: object

Traverse and manage git submodules with ORM-like filtering via QueryList.

__init__(*, path, cmd=None)

method

Wrap some of git-submodule(1), manager.

Parameters:

• path (StrPath) – Operates as PATH in the corresponding git subcommand.

• cmd (Git | None)

Return type:

None

Examples

>>> GitSubmoduleManager(path=tmp_path)
<GitSubmoduleManager path=...>

>>> GitSubmoduleManager(path=tmp_path).run('status')
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitSubmoduleManager(path=example_git_repo.path).run('status')
''

path: Path

attribute

Directory to check out

run(command=None, local_flags=None, *, quiet=False, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a git repository’s submodules.

Wraps git submodule.

Parameters:

• command (GitSubmoduleCmdCommandLiteral | None) – Submodule command to run.

• local_flags (list[str] | None) – Additional flags to pass.

• quiet (bool) – Suppress output.

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

Examples

>>> GitSubmoduleManager(path=example_git_repo.path).run('status')
''

add(repository, path=None, *, branch=None, force=False, name=None, depth=None, log_in_real_time=False, check_returncode=None)

method

Add a new submodule.

Parameters:

• repository (str) – URL of the repository to add as submodule.

• path (str | None) – Path where submodule will be cloned.

• branch (str | None) – Branch to track.

• force (bool) – Force add.

• name (str | None) – Logical name for the submodule.

• depth (int | None) – Shallow clone depth.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> result = GitSubmoduleManager(path=example_git_repo.path).add(
...     f'file://{git_remote_repo}',
...     'vendor/example'
... )
>>> 'error' in result.lower() or 'fatal' in result.lower() or result == ''
True

init(*, path=None, log_in_real_time=False, check_returncode=None)

method

Initialize submodules.

Parameters:

• path (list[str] | str | None) – Specific submodule path(s) to initialize.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitSubmoduleManager(path=example_git_repo.path).init()
''

update(*, path=None, init=False, force=False, checkout=False, rebase=False, merge=False, recursive=False, remote=False, log_in_real_time=False, check_returncode=None)

method

Update submodules.

Parameters:

• path (list[str] | str | None) – Specific submodule path(s) to update.

• init (bool) – Initialize if not already.

• force (bool) – Discard local changes.

• checkout (bool) – Check out superproject’s recorded commit.

• rebase (bool) – Rebase current branch onto commit.

• merge (bool) – Merge commit into current branch.

• recursive (bool) – Recurse into nested submodules.

• remote (bool) – Use remote tracking branch.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitSubmoduleManager(path=example_git_repo.path).update()
''

>>> GitSubmoduleManager(path=example_git_repo.path).update(init=True)
''

foreach(command, *, recursive=False, log_in_real_time=False, check_returncode=None)

method

Run command in each submodule.

Parameters:

• command (str) – Shell command to run.

• recursive (bool) – Recurse into nested submodules.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleManager(path=example_git_repo.path).foreach(
...     'git status'
... )
>>> isinstance(result, str)
True

sync(*, path=None, recursive=False, log_in_real_time=False, check_returncode=None)

method

Sync submodule URLs.

Parameters:

• path (list[str] | str | None) – Specific submodule path(s) to sync.

• recursive (bool) – Recurse into nested submodules.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitSubmoduleManager(path=example_git_repo.path).sync()
''

summary(*, cached=False, files=False, summary_limit=None, commit=None, path=None, log_in_real_time=False, check_returncode=None)

method

Show commit summary for submodules.

Parameters:

• cached (bool) – Use cached info.

• files (bool) – Compare to working tree.

• summary_limit (int | None) – Limit number of commits shown.

• commit (str | None) – Commit to compare against.

• path (list[str] | str | None) – Specific submodule path(s).

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleManager(path=example_git_repo.path).summary()
>>> isinstance(result, str)
True

absorbgitdirs(*, path=None, log_in_real_time=False, check_returncode=None)

method

Absorb git directories into superproject.

Parameters:

• path (list[str] | str | None) – Specific submodule path(s).

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleManager(path=example_git_repo.path).absorbgitdirs()
>>> isinstance(result, str)
True

_ls(*, recursive=False, cached=False, log_in_real_time=False, check_returncode=None)

method

Parse submodule status output into structured data.

Parameters:

• recursive (bool) – Include nested submodules.

• cached (bool) – Use cached info.

• log_in_real_time (bool)

• check_returncode (bool | None)

Returns:

List of parsed submodule data.

Return type:

list[dict[str, Any]]

Examples

>>> submodules = GitSubmoduleManager(path=example_git_repo.path)._ls()
>>> isinstance(submodules, list)
True

ls(*, recursive=False, cached=False)

method

List submodules as GitSubmodule objects.

Parameters:

• recursive (bool) – Include nested submodules.

• cached (bool) – Use cached info.

Returns:

List of submodules with ORM-like filtering.

Return type:

QueryList[GitSubmodule]

Examples

>>> submodules = GitSubmoduleManager(path=example_git_repo.path).ls()
>>> isinstance(submodules, QueryList)
True

get(path=None, name=None, **kwargs)

method

Get a specific submodule.

Parameters:

• path (str | None) – Submodule path to find.

• name (str | None) – Submodule name to find.

• **kwargs (Any) – Additional filter criteria.

Returns:

The matching submodule.

Return type:

GitSubmodule

Raises:

• ObjectDoesNotExist – If no matching submodule found.

• MultipleObjectsReturned – If multiple submodules match.

Examples

>>> submodules = GitSubmoduleManager(path=example_git_repo.path)
>>> # submodule = submodules.get(path='vendor/lib')

filter(*args, **kwargs)

method

Filter submodules.

Parameters:

• *args (Any) – Positional arguments for QueryList.filter().

• **kwargs (Any) – Keyword arguments for filtering (supports Django-style lookups).

Returns:

Filtered list of submodules.

Return type:

QueryList[GitSubmodule]

Examples

>>> submodules = GitSubmoduleManager(path=example_git_repo.path).filter()
>>> isinstance(submodules, QueryList)
True

class libvcs.cmd.git.GitSubmodule

class

Bases: object

Represent a git submodule.

name: str

attribute

Submodule name (from .gitmodules).

path: str

attribute

Path to submodule relative to repository root.

url: str | None = None

attribute

Remote URL for the submodule.

sha: str | None = None

attribute

Current commit SHA of the submodule.

branch: str | None = None

attribute

Configured branch for the submodule.

status_prefix: str = ''

attribute

Status prefix: ‘-’ not initialized, ‘+’ differs, ‘U’ conflicts.

_cmd: GitSubmoduleEntryCmd | None = None

attribute

Internal: GitSubmoduleEntryCmd for operations on this submodule

property cmd: GitSubmoduleEntryCmd

property

Return command object for this submodule.

property initialized: bool

property

Check if submodule is initialized.

__init__(name, path, url=None, sha=None, branch=None, status_prefix='', _cmd=None)

method

Parameters:

• name (str)

• path (str)

• url (str | None)

• sha (str | None)

• branch (str | None)

• status_prefix (str)

• _cmd (GitSubmoduleEntryCmd | None)

Return type:

None

class libvcs.cmd.git.GitSubmoduleEntryCmd

class

Bases: object

Run git commands targeting a specific submodule.

__init__(*, path, submodule_path, cmd=None)

method

Wrap some of git-submodule(1) for specific submodule operations.

Parameters:

• path (StrPath) – Operates as PATH in the corresponding git subcommand.

• submodule_path (str) – Path to the submodule relative to repository root.

• cmd (Git | None)

Return type:

None

Examples

>>> GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... )
<GitSubmoduleEntryCmd vendor/lib>

path: Path

attribute

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a specific submodule.

Wraps git submodule.

Parameters:

• command (GitSubmoduleCmdCommandLiteral | None) – Submodule command to run.

• local_flags (list[str] | None) – Additional flags to pass.

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

Examples

>>> GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).run('status')
''

init(*, log_in_real_time=False, check_returncode=None)

method

Initialize this submodule.

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).init()
>>> 'error' in result.lower() or result == ''
True

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

update(*, init=False, force=False, checkout=False, rebase=False, merge=False, recursive=False, remote=False, log_in_real_time=False, check_returncode=None)

method

Update this submodule.

Parameters:

• init (bool) – Initialize if not already.

• force (bool) – Discard local changes.

• checkout (bool) – Check out superproject’s recorded commit.

• rebase (bool) – Rebase current branch onto commit.

• merge (bool) – Merge commit into current branch.

• recursive (bool) – Recurse into nested submodules.

• remote (bool) – Use remote tracking branch.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).update()
>>> 'error' in result.lower() or result == ''
True

deinit(*, force=False, log_in_real_time=False, check_returncode=None)

method

Unregister this submodule.

Parameters:

• force (bool) – Force removal even if has local modifications.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).deinit()
>>> 'error' in result.lower() or result == ''
True

set_branch(branch=None, *, default=False, log_in_real_time=False, check_returncode=None)

method

Set branch for this submodule.

Parameters:

• branch (str | None) – Branch to track.

• default (bool) – Reset to default (remove branch setting).

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).set_branch('main')
>>> 'fatal' in result.lower() or 'error' in result.lower() or result == ''
True

set_url(url, *, log_in_real_time=False, check_returncode=None)

method

Set URL for this submodule.

Parameters:

• url (str) – New URL for the submodule.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).set_url('https://example.com/repo.git')
>>> 'fatal' in result.lower() or 'error' in result.lower() or result == ''
True

status(*, recursive=False, log_in_real_time=False, check_returncode=None)

method

Get status of this submodule.

Parameters:

• recursive (bool) – Recurse into nested submodules.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).status()
>>> isinstance(result, str)
True

absorbgitdirs(*, log_in_real_time=False, check_returncode=None)

method

Absorb git directory for this submodule.

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).absorbgitdirs()
>>> 'error' in result.lower() or result == ''
True

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

class libvcs.cmd.git.GitSubmoduleCmd

class

Bases: object

Run git submodule commands (low-level, use GitSubmoduleManager for traversal).

__init__(*, path, cmd=None)

method

Lite, typed, pythonic wrapper for git-submodule(1).

Parameters:

• path (StrPath) – Operates as PATH in the corresponding git subcommand.

• cmd (Git | None)

Return type:

None

Examples

>>> GitSubmoduleCmd(path=tmp_path)
<GitSubmoduleCmd path=...>

>>> GitSubmoduleCmd(path=tmp_path).run(quiet=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitSubmoduleCmd(path=example_git_repo.path).run(quiet=True)
''

path: Path

attribute

Directory to check out

run(command=None, local_flags=None, *, quiet=None, cached=None, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a git submodule.

Wraps git submodule.

Examples

>>> GitSubmoduleCmd(path=example_git_repo.path).run()
''

Parameters:

• command (GitSubmoduleCmdCommandLiteral | None)

• local_flags (list[str] | None)

• quiet (bool | None)

• cached (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

init(*, path=None, log_in_real_time=False, check_returncode=None)

method

Git submodule init.

Examples

>>> GitSubmoduleCmd(path=example_git_repo.path).init()
''

Parameters:

• path (list[StrPath] | StrPath | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

update(*, path=None, init=None, force=None, checkout=None, rebase=None, merge=None, recursive=None, log_in_real_time=False, check_returncode=None, **kwargs)

method

Git submodule update.

Examples

>>> GitSubmoduleCmd(path=example_git_repo.path).update()
''
>>> GitSubmoduleCmd(path=example_git_repo.path).update(init=True)
''
>>> GitSubmoduleCmd(
...     path=example_git_repo.path
... ).update(init=True, recursive=True)
''
>>> GitSubmoduleCmd(path=example_git_repo.path).update(force=True)
''
>>> GitSubmoduleCmd(path=example_git_repo.path).update(checkout=True)
''
>>> GitSubmoduleCmd(path=example_git_repo.path).update(rebase=True)
''
>>> GitSubmoduleCmd(path=example_git_repo.path).update(merge=True)
''

Parameters:

• path (list[StrPath] | StrPath | None)

• init (bool | None)

• force (bool | None)

• checkout (bool | None)

• rebase (bool | None)

• merge (bool | None)

• recursive (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str