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.

Examples

List submodules — a repository without any simply returns an empty list — and sync submodule URLs into .git/config:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.submodules.ls()
[]
>>> git.submodules.sync()
''

Register a submodule with add(), then initialize and fetch it through the entry’s init() and update() — each method’s API reference below carries a runnable example.

API Reference

class libvcs.cmd.git.GitSubmoduleManager
class[source]
class[source]
class libvcs.cmd.git.GitSubmoduleManager

Bases: object

Traverse git submodules with QueryList.

__init__(*, path, cmd=None)
method[source]
method[source]
__init__(*, path, cmd=None)

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', trim=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitSubmoduleManager(path=example_git_repo.path).run('status')
''
path: Path
attribute
attribute
path: Path

Directory to check out

run(command=None, local_flags=None, *, quiet=False, log_in_real_time=False, check_returncode=None, **kwargs)
method[source]
method[source]
run(command=None, local_flags=None, *, quiet=False, log_in_real_time=False, check_returncode=None, **kwargs)

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[source]
method[source]
add(repository, path=None, *, branch=None, force=False, name=None, depth=None, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
init(*, path=None, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
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)

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[source]
method[source]
foreach(command, *, recursive=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
sync(*, path=None, recursive=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
summary(*, cached=False, files=False, summary_limit=None, commit=None, path=None, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
absorbgitdirs(*, path=None, log_in_real_time=False, check_returncode=None)

Absorb git directories into superproject.

Parameters:
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[source]
method[source]
_ls(*, recursive=False, cached=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
ls(*, recursive=False, cached=False)

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[source]
method[source]
get(path=None, name=None, **kwargs)

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:

Examples

>>> from libvcs._internal.query_list import ObjectDoesNotExist
>>> submodules = GitSubmoduleManager(path=example_git_repo.path)
>>> try:
...     submodules.get(path='vendor/lib')
... except ObjectDoesNotExist:
...     True
True
filter(*args, **kwargs)
method[source]
method[source]
filter(*args, **kwargs)

Filter submodules.

Parameters:

  • *args (Any) – Positional arguments for 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[source]
class[source]
class libvcs.cmd.git.GitSubmodule

Bases: object

Represent a git submodule.

name: str
attribute
attribute
name: str

Submodule name (from .gitmodules).

path: str
attribute
attribute
path: str

Path to submodule relative to repository root.

url: str | None = None
attribute
attribute
url: str | None = None

Remote URL for the submodule.

sha: str | None = None
attribute
attribute
sha: str | None = None

Current commit SHA of the submodule.

branch: str | None = None
attribute
attribute
branch: str | None = None

Configured branch for the submodule.

status_prefix: str = ''
attribute
attribute
status_prefix: str = ''

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

_cmd: GitSubmoduleEntryCmd | None = None
attribute
attribute
_cmd: GitSubmoduleEntryCmd | None = None

Internal: GitSubmoduleEntryCmd for operations on this submodule

property cmd: GitSubmoduleEntryCmd
property
property
property cmd: GitSubmoduleEntryCmd

Return command object for this submodule.

property initialized: bool
property
property
property initialized: bool

Check if submodule is initialized.

__init__(name, path, url=None, sha=None, branch=None, status_prefix='', _cmd=None)
method[source]
method[source]
__init__(name, path, url=None, sha=None, branch=None, status_prefix='', _cmd=None)
Parameters:
Return type:

None

class libvcs.cmd.git.GitSubmoduleEntryCmd
class[source]
class[source]
class libvcs.cmd.git.GitSubmoduleEntryCmd

Bases: object

Run git commands targeting a specific submodule.

__init__(*, path, submodule_path, cmd=None)
method[source]
method[source]
__init__(*, path, submodule_path, cmd=None)

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
attribute
path: Path

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
method[source]
method[source]
run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

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[source]
method[source]
init(*, log_in_real_time=False, check_returncode=None)

Initialize this submodule.

Examples

>>> result = GitSubmoduleEntryCmd(
...     path=example_git_repo.path,
...     submodule_path='vendor/lib',
... ).init()
>>> 'error' in result.lower() or result == ''
True
Parameters:
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[source]
method[source]
update(*, init=False, force=False, checkout=False, rebase=False, merge=False, recursive=False, remote=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
deinit(*, force=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
set_branch(branch=None, *, default=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
set_url(url, *, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
status(*, recursive=False, log_in_real_time=False, check_returncode=None)

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[source]
method[source]
absorbgitdirs(*, log_in_real_time=False, check_returncode=None)

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:
Return type:

str

class libvcs.cmd.git.GitSubmoduleCmd
class[source]
class[source]
class libvcs.cmd.git.GitSubmoduleCmd

Bases: object

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

__init__(*, path, cmd=None)
method[source]
method[source]
__init__(*, path, cmd=None)

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, trim=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
attribute
path: Path

Directory to check out

run(command=None, local_flags=None, *, quiet=None, cached=None, log_in_real_time=False, check_returncode=None, **kwargs)
method[source]
method[source]
run(command=None, local_flags=None, *, quiet=None, cached=None, log_in_real_time=False, check_returncode=None, **kwargs)

Run a command against a git submodule.

Wraps git submodule.

Examples

>>> GitSubmoduleCmd(path=example_git_repo.path).run()
''
Parameters:
Return type:

str

init(*, path=None, log_in_real_time=False, check_returncode=None)
method[source]
method[source]
init(*, path=None, log_in_real_time=False, check_returncode=None)

Git submodule init.

Examples

>>> GitSubmoduleCmd(path=example_git_repo.path).init()
''
Parameters:
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[source]
method[source]
update(*, path=None, init=None, force=None, checkout=None, rebase=None, merge=None, recursive=None, log_in_real_time=False, check_returncode=None, **kwargs)

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:
Return type:

str