`libvcs.cmd.git`¶

Use Git when you need direct access to git(1) from Python, with typed helpers for common subcommands and an escape hatch to run raw git arguments.

Compare to: fabtools.git, salt.modules.git, ansible.builtin.git

Managers and Commands¶

libvcs provides Managers and Commands for git subcommands:

Managers (git.branches, git.tags, etc.) let you traverse repository entities intuitively with ORM-like filtering via QueryList
Commands are contextual ways to run git commands against a specific target entity

See Traversing Git Repos for the full guide.

Git instance
├── branches: GitBranchManager
│   ├── ls() -> QueryList[GitBranchCmd]
│   ├── get() -> GitBranchCmd
│   └── create()
├── tags: GitTagManager
├── remotes: GitRemoteManager
├── stashes: GitStashManager
├── worktrees: GitWorktreeManager
├── notes: GitNotesManager
├── submodules: GitSubmoduleManager
└── reflog: GitReflogManager

Quick Example¶

List branches, rename one through its Cmd object, and manage tags:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> branches = git.branches.ls()
>>> len(branches) >= 1
True
>>> git.branches.create(branch='old-name')
''
>>> branch = git.branches.get(branch_name='old-name')
>>> branch.rename('new-name')
''
>>> git.tags.create(name='v1.0.0', message='Release 1.0')
''
>>> tag = git.tags.get(tag_name='v1.0.0')
>>> tag.delete()
"Deleted tag 'v1.0.0' ..."

Subcommands

Run git commands directly against a local git repo.

class libvcs.cmd.git.Git ¶ class[source] class[source] class libvcs.cmd.git.Git ¶

Bases: object

Run commands directly on a git repository.

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

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

Parameters:

path (StrPath) – Operates as PATH in the corresponding git subcommand.
progress_callback (ProgressCallbackProtocol | None)

Return type:

None

Examples

>>> git = Git(path=example_git_repo.path)
>>> git
<Git path=...>

Subcommands:

>>> git.remotes.show(trim=True)
'origin'

>>> git.remotes.add(
...     name='my_remote', url=f'file:///dev/null'
... )
''

>>> git.remotes.show(trim=True)
'my_remote\norigin'

>>> git.stash.save(message="Message", trim=True)
'No local changes to save'

>>> git.submodule.init()
''

# Additional tests

>>> git.remotes.get(remote_name='my_remote').remove()
''
>>> git.remotes.show(trim=True)
'origin'

>>> git.stash.ls()
''

>>> git.stashes.ls()
[]

>>> git.tags.create(name='v1.0.0', message='Version 1.0.0')
''

>>> any(t.tag_name == 'v1.0.0' for t in git.tags.ls())
True

run(args, *, version=None, _help=None, html_path=None, man_path=None, info_path=None, C=None, cwd=None, git_dir=None, work_tree=None, namespace=None, super_prefix=None, exec_path=None, bare=None, no_replace_objects=None, literal_pathspecs=None, global_pathspecs=None, noglob_pathspecs=None, icase_pathspecs=None, no_optional_locks=None, config=None, config_env=None, log_in_real_time=False, timeout=None, **kwargs)
¶
method[source]
method[source]
run(args, *, version=None, _help=None, html_path=None, man_path=None, info_path=None, C=None, cwd=None, git_dir=None, work_tree=None, namespace=None, super_prefix=None, exec_path=None, bare=None, no_replace_objects=None, literal_pathspecs=None, global_pathspecs=None, noglob_pathspecs=None, icase_pathspecs=None, no_optional_locks=None, config=None, config_env=None, log_in_real_time=False, timeout=None, **kwargs)
¶

Run a command for this git repository.

Passing None to a subcommand option, the flag won’t be passed unless otherwise stated.

git help and git help [cmd]

Wraps git’s Options.