libvcs.cmd.git#

For git(1).

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

Subcommands

class libvcs.cmd.git.Git(*, dir, progress_callback=None)[source]#

Bases: object

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

Parameters:

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git
<Git dir=...>

Subcommands:

>>> git.remote.show()
'origin'
>>> git.remote.add(
...     name='my_remote', url=f'file:///dev/null'
... )
''
>>> git.remote.show()
'my_remote\norigin'
>>> git.stash.save(message="Message")
'No local changes to save'
>>> git.submodule.init()
''
__init__(*, dir, progress_callback=None)[source]#

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

Parameters:
Return type:

None

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git
<Git dir=...>

Subcommands:

>>> git.remote.show()
'origin'
>>> git.remote.add(
...     name='my_remote', url=f'file:///dev/null'
... )
''
>>> git.remote.show()
'my_remote\norigin'
>>> git.stash.save(message="Message")
'No local changes to save'
>>> git.submodule.init()
''
dir: Path#

Directory to check out

progress_callback: Optional[ProgressCallbackProtocol] = None#
submodule: GitSubmoduleCmd#
remote: GitRemoteCmd#
stash: GitStashCmd#
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, **kwargs)[source]#

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.

Parameters:
Return type:

str

Examples

>>> git = Git(dir=tmp_path)
>>> git.run(['help'])
"usage: git [...--version] [...--help] [-C <path>]..."
Return type:

str

Parameters:
clone(*, url, separate_git_dir=None, template=None, depth=None, branch=None, origin=None, upload_pack=None, shallow_since=None, shallow_exclude=None, reference=None, reference_if_able=None, server_option=None, jobs=None, force=None, local=None, all=None, no_hardlinks=None, hardlinks=None, shared=None, progress=None, no_checkout=None, no_reject_shallow=None, reject_shallow=None, sparse=None, shallow_submodules=None, no_shallow_submodules=None, remote_submodules=None, no_remote_submodules=None, verbose=None, quiet=None, config=None, log_in_real_time=False, check_returncode=None, make_parents=True, **kwargs)[source]#

Clone a working copy from an git repo.

Wraps git clone.

Parameters:
Return type:

str

Examples

>>> git = Git(dir=tmp_path)
>>> git_remote_repo = create_git_remote_repo()
>>> git.clone(url=f'file://{git_remote_repo}')
''
>>> git.dir.exists()
True
Return type:

str

Parameters:
fetch(*, reftag=None, deepen=None, depth=None, branch=None, origin=None, upload_pack=None, shallow_since=None, shallow_exclude=None, negotiation_tip=None, jobs=None, server_option=None, recurse_submodules=None, recurse_submodules_default=None, submodule_prefix=None, all=None, force=None, keep=None, multiple=None, dry_run=None, append=None, atomic=None, ipv4=None, ipv6=None, progress=None, quiet=None, verbose=None, unshallow=None, update_shallow=None, negotiate_tip=None, no_write_fetch_head=None, write_fetch_head=None, no_auto_maintenance=None, auto_maintenance=None, no_write_commit_graph=None, write_commit_graph=None, prefetch=None, prune=None, prune_tags=None, no_tags=None, tags=None, no_recurse_submodules=None, set_upstream=None, update_head_ok=None, show_forced_updates=None, no_show_forced_updates=None, negotiate_only=None, check_returncode=None, **kwargs)[source]#

Download from repo. Wraps git fetch.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git_remote_repo = create_git_remote_repo()
>>> git.fetch()
''
>>> git = Git(dir=git_local_clone.dir)
>>> git_remote_repo = create_git_remote_repo()
>>> git.fetch(reftag=f'file://{git_remote_repo}')
''
>>> git.dir.exists()
True
Return type:

str

Parameters:
rebase(*, upstream=None, onto=None, branch=None, apply=None, merge=None, quiet=None, verbose=None, stat=None, no_stat=None, verify=None, no_verify=None, fork_point=None, no_fork_point=None, whitespace=None, no_whitespace=None, commit_date_is_author_date=None, ignore_date=None, root=None, autostash=None, no_autostash=None, autosquash=None, no_autosquash=None, reschedule_failed_exec=None, no_reschedule_failed_exec=None, context=None, rerere_autoupdate=None, no_rerere_autoupdate=None, keep_empty=None, no_keep_empty=None, reapply_cherry_picks=None, no_reapply_cherry_picks=None, allow_empty_message=None, signoff=None, keep_base=None, strategy=None, strategy_option=None, exec=None, gpg_sign=None, no_gpg_sign=None, empty=None, rebase_merges=None, interactive=None, edit_todo=None, skip=None, show_current_patch=None, abort=None, quit=None, check_returncode=None, **kwargs)[source]#

Reapply commit on top of another tip.

Wraps git rebase.

Parameters:
Return type:

str

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git_remote_repo = create_git_remote_repo()
>>> git.rebase()
'Current branch master is up to date.'

Declare upstream:

>>> git = Git(dir=git_local_clone.dir)
>>> git_remote_repo = create_git_remote_repo()
>>> git.rebase(upstream='origin')
'Current branch master is up to date.'
>>> git.dir.exists()
True
Return type:

str

Parameters:
pull(*, reftag=None, repository=None, deepen=None, depth=None, branch=None, origin=None, upload_pack=None, shallow_since=None, shallow_exclude=None, negotiation_tip=None, jobs=None, server_option=None, recurse_submodules=None, recurse_submodules_default=None, submodule_prefix=None, cleanup=None, rebase=None, no_rebase=None, strategy=None, strategy_option=None, gpg_sign=None, no_gpg_sign=None, commit=None, no_commit=None, edit=None, no_edit=None, fast_forward_only=None, fast_forward=None, no_fast_forward=None, sign_off=None, no_sign_off=None, stat=None, no_stat=None, squash=None, no_squash=None, verify=None, no_verify=None, verify_signatures=None, no_verify_signatures=None, summary=None, no_summary=None, autostash=None, no_autostash=None, allow_unrelated_histories=None, fetch=None, no_fetch=None, all=None, force=None, keep=None, multiple=None, dry_run=None, append=None, atomic=None, ipv4=None, ipv6=None, progress=None, quiet=None, verbose=None, unshallow=None, update_shallow=None, negotiate_tip=None, no_write_fetch_head=None, write_fetch_head=None, no_auto_maintenance=None, auto_maintenance=None, no_write_commit_graph=None, write_commit_graph=None, prefetch=None, prune=None, prune_tags=None, no_tags=None, tags=None, no_recurse_submodules=None, set_upstream=None, update_head_ok=None, show_forced_updates=None, no_show_forced_updates=None, negotiate_only=None, log_in_real_time=False, check_returncode=None, **kwargs)[source]#

Download from repo. Wraps git pull.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git_remote_repo = create_git_remote_repo()
>>> git.pull()
'Already up to date.'

Fetch via ref:

>>> git = Git(dir=tmp_path)
>>> git.run(['init'])
'Initialized ...'
>>> git_remote_repo = create_git_remote_repo()
>>> git.pull(reftag=f'file://{git_remote_repo}')
''
>>> git.dir.exists()
True
Return type:

str

Parameters:
init(*, template=None, separate_git_dir=None, object_format=None, branch=None, initial_branch=None, shared=None, quiet=None, bare=None, check_returncode=None, **kwargs)[source]#

Create empty repo. Wraps git init.

Parameters:
Return type:

str

Examples

>>> new_repo = tmp_path / 'example'
>>> new_repo.mkdir()
>>> git = Git(dir=new_repo)
>>> git.init()
'Initialized empty Git repository in ...'
>>> pathlib.Path(new_repo / 'test').write_text('foo', 'utf-8')
3
>>> git.run(['add', '.'])
''

Bare:

>>> new_repo = tmp_path / 'example1'
>>> new_repo.mkdir()
>>> git = Git(dir=new_repo)
>>> git.init(bare=True)
'Initialized empty Git repository in ...'
>>> pathlib.Path(new_repo / 'HEAD').exists()
True

Existing repo:

>>> git = Git(dir=new_repo)
>>> git = Git(dir=git_local_clone.dir)
>>> git_remote_repo = create_git_remote_repo()
>>> git.init()
'Reinitialized existing Git repository in ...'
Return type:

str

Parameters:
help(*, all=None, verbose=None, no_external_commands=None, no_aliases=None, config=None, guides=None, info=None, man=None, web=None, check_returncode=None, **kwargs)[source]#

Help info. Wraps git help.

Parameters:
  • all (bool) – Prints everything.

  • no_external_commands (bool) – For use with all, excludes external commands.

  • no_aliases (bool) – For use with all, excludes aliases.

  • verbose (bool) – For us with all, on by default.

  • config (bool) – List all config vars.

  • guides (bool) – List concept guides.

  • info (bool) – Display man page in info format.

  • man (bool) – Man page.

  • web (bool) – Man page in HTML.

  • check_returncode (Optional[bool]) –

  • kwargs (Any) –

Return type:

str

Examples

>>> git = Git(dir=tmp_path)
>>> git.help()
"usage: git [...--version] [...--help] [-C <path>]..."
>>> git.help(all=True)
"See 'git help <command>' to read about a specific subcommand..."
>>> git.help(info=True)
"usage: git [...--version] [...--help] [-C <path>] [-c <name>=<value>]..."
>>> git.help(man=True)
"usage: git [...--version] [...--help] [-C <path>] [-c <name>=<value>]..."
Return type:

str

Parameters:
reset(*, quiet=None, refresh=None, no_refresh=None, pathspec_from_file=None, pathspec=None, soft=None, mixed=None, hard=None, merge=None, keep=None, commit=None, recurse_submodules=None, no_recurse_submodules=None, check_returncode=None, **kwargs)[source]#

Reset HEAD. Wraps git help.

Parameters:
Return type:

str

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.reset()
''
>>> git.reset(soft=True, commit='HEAD~0')
''
Return type:

str

Parameters:
checkout(*, quiet=None, progress=None, no_progress=None, pathspec_from_file=None, pathspec=None, force=None, ours=None, theirs=None, no_track=None, guess=None, no_guess=None, _list=None, detach=None, merge=None, ignore_skip_worktree_bits=None, patch=None, orphan=None, conflict=None, overwrite_ignore=None, no_overwrite_ignore=None, recurse_submodules=None, no_recurse_submodules=None, overlay=None, no_overlay=None, commit=None, branch=None, new_branch=None, start_point=None, treeish=None, check_returncode=None, **kwargs)[source]#

Switches branches or checks out files. Wraps git checkout (git co).

Parameters:
Return type:

str

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.checkout()
"Your branch is up to date with 'origin/master'."
>>> git.checkout(branch='origin/master', pathspec='.')
''
Return type:

str

Parameters:
status(*, verbose=None, long=None, short=None, branch=None, z=None, column=None, no_column=None, ahead_behind=None, no_ahead_behind=None, renames=None, no_renames=None, find_renames=None, porcelain=None, untracked_files=None, ignored=None, ignored_submodules=None, pathspec=None, check_returncode=None, **kwargs)[source]#

Status of working tree. Wraps git status.

git ls-files has similar params (e.g. z)

Parameters:
Return type:

str

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.status()
"On branch master..."
>>> pathlib.Path(git_local_clone.dir / 'new_file.txt').touch()
>>> git.status(porcelain=True)
'?? new_file.txt'
>>> git.status(porcelain='1')
'?? new_file.txt'
>>> git.status(porcelain='2')
'? new_file.txt'
>>> git.status(C=git_local_clone.dir / '.git', porcelain='2')
'? new_file.txt'
>>> git.status(porcelain=True, untracked_files="no")
''
Return type:

str

Parameters:
config(*, replace_all=None, get=None, get_all=None, get_regexp=None, get_urlmatch=None, system=None, local=None, worktree=None, file=None, blob=None, remove_section=None, rename_section=None, unset=None, unset_all=None, _list=None, fixed_value=None, no_type=None, null=None, name_only=None, show_origin=None, show_scope=None, get_color=None, get_colorbool=None, default=None, _type=None, edit=None, no_includes=None, includes=None, add=None, check_returncode=None, **kwargs)[source]#

Status of working tree. Wraps git status.

git ls-files has similar params (e.g. z)

Parameters:
  • replace_all (Optional[bool]) –

  • get (Optional[bool]) –

  • get_all (Optional[bool]) –

  • get_regexp (Optional[bool]) –

  • get_urlmatch (Optional[tuple[str, str]]) –

  • system (Optional[bool]) –

  • local (Optional[bool]) –

  • worktree (Optional[bool]) –

  • file (Optional[StrOrBytesPath]) –

  • blob (Optional[str]) –

  • remove_section (Optional[bool]) –

  • rename_section (Optional[bool]) –

  • unset (Optional[bool]) –

  • unset_all (Optional[bool]) –

  • _list (Optional[bool]) –

  • fixed_value (Optional[bool]) –

  • no_type (Optional[bool]) –

  • null (Optional[bool]) –

  • name_only (Optional[bool]) –

  • show_origin (Optional[bool]) –

  • show_scope (Optional[bool]) –

  • get_color (Optional[Union[str, bool]]) –

  • get_colorbool (Optional[Union[str, bool]]) –

  • default (Optional[str]) –

  • _type ("bool", "int", "bool-or-int", "path", "expiry-date", "color") –

  • edit (Optional[bool]) –

  • no_includes (Optional[bool]) –

  • includes (Optional[bool]) –

  • add (Optional[bool]) –

  • check_returncode (Optional[bool]) –

  • kwargs (Any) –

Return type:

str

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.config()
'usage: git config ...'
>>> git.config(_list=True)
'...user.email=...'
>>> git.config(get='color.diff')
'auto'
Return type:

str

Parameters:
version(*, build_options=None, check_returncode=None, **kwargs)[source]#

Version. Wraps git version.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.version()
'git version ...'
>>> git.version(build_options=True)
'git version ...'
Return type:

str

Parameters:
rev_parse(*, parseopt=None, sq_quote=None, keep_dashdash=None, stop_at_non_option=None, stuck_long=None, verify=None, args=None, check_returncode=None, **kwargs)[source]#

rev-parse. Wraps git rev-parse.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.rev_parse()
''
>>> git.rev_parse(parseopt=True)
'usage: git rev-parse --parseopt...'
>>> git.rev_parse(verify=True, args='HEAD')
'...'
Return type:

str

Parameters:
rev_list(*, commit, path=None, max_count=None, skip=None, since=None, after=None, until=None, before=None, max_age=None, min_age=None, author=None, committer=None, grep=None, all_match=None, invert_grep=None, regexp_ignore_case=None, basic_regexp=None, extended_regexp=None, fixed_strings=None, perl_regexp=None, remove_empty=None, merges=None, no_merges=None, no_min_parents=None, min_parents=None, no_max_parents=None, max_parents=None, first_parent=None, exclude_first_parent_only=None, _not=None, all=None, branches=None, tags=None, remotes=None, exclude=None, reflog=None, alternative_refs=None, single_worktree=None, ignore_missing=None, stdin=None, disk_usage=None, cherry_mark=None, cherry_pick=None, left_only=None, right_only=None, cherry=None, walk_reflogs=None, merge=None, boundary=None, use_bitmap_index=None, progress=None, header=None, check_returncode=True, log_in_real_time=False, **kwargs)[source]#

rev-list. Wraps git rev-list.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.rev_list(commit="HEAD")
'...'
>>> git.run(['commit', '--allow-empty', '--message=Moo'])
'[master ...] Moo'
>>> git.rev_list(commit="HEAD", max_count=1)
''
>>> git.rev_list(commit="HEAD", path=".", max_count=1, header=True)
''
>>> git.rev_list(commit="origin..HEAD", max_count=1, all=True, header=True)
''
>>> git.rev_list(commit="origin..HEAD", max_count=1, header=True)
''
Return type:

str

Parameters:
symbolic_ref(*, name, ref=None, message=None, short=None, delete=None, quiet=None, check_returncode=None, **kwargs)[source]#

symbolic-ref. Wraps git symbolic-ref.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.symbolic_ref(name="test")
'fatal: ref test is not a symbolic ref'
>>> git.symbolic_ref(name="test")
'fatal: ref test is not a symbolic ref'
Return type:

str

Parameters:
show_ref(*, pattern=None, quiet=None, verify=None, head=None, dereference=None, tags=None, hash=None, abbrev=None, check_returncode=None, **kwargs)[source]#

show-ref. Wraps git show-ref.

Examples

>>> git = Git(dir=git_local_clone.dir)
>>> git.show_ref()
'...'
>>> git.show_ref(pattern='master')
'...'
>>> git.show_ref(pattern='master', head=True)
'...'
>>> git.show_ref(pattern='HEAD', verify=True)
'... HEAD'
>>> git.show_ref(pattern='master', dereference=True)
'... refs/heads/master\n... refs/remotes/origin/master'
>>> git.show_ref(pattern='HEAD', tags=True)
''
Return type:

str

Parameters: