libvcs.cmd.git#

For git(1).

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

class libvcs.cmd.git.Git(*, dir)#
Parameters:

dir (libvcs._internal.types.StrPath) –

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, **kwargs)#

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='.')
''
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, make_parents=True, **kwargs)#

Clone a working copy from an git repo.

Wraps git clone.

Parameters:

  • url (str) –

  • directory (str) –

  • separate_git_dir (StrOrBytesPath) – Separate repository (.git/ ) from working tree

  • force (bool, optional) – force operation to run

  • make_parents (bool, default: True) – Creates checkout directory (:attr:`self.dir) if it doesn’t already exist.

  • template (Optional[str]) –

  • depth (Optional[str]) –

  • branch (Optional[str]) –

  • origin (Optional[str]) –

  • upload_pack (Optional[str]) –

  • shallow_since (Optional[str]) –

  • shallow_exclude (Optional[str]) –

  • reference (Optional[str]) –

  • reference_if_able (Optional[str]) –

  • server_option (Optional[str]) –

  • jobs (Optional[str]) –

  • local (Optional[bool]) –

  • all (Optional[bool]) –

  • no_hardlinks (Optional[bool]) –

  • hardlinks (Optional[bool]) –

  • shared (Optional[bool]) –

  • progress (Optional[bool]) –

  • no_checkout (Optional[bool]) –

  • no_reject_shallow (Optional[bool]) –

  • reject_shallow (Optional[bool]) –

  • sparse (Optional[bool]) –

  • shallow_submodules (Optional[bool]) –

  • no_shallow_submodules (Optional[bool]) –

  • remote_submodules (Optional[bool]) –

  • no_remote_submodules (Optional[bool]) –

  • verbose (Optional[bool]) –

  • quiet (Optional[bool]) –

  • kwargs (Any) –

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
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, **kwargs)#

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]) –

  • 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'
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, **kwargs)#

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
Parameters:

  • reftag (Optional[Any]) –

  • deepen (Optional[str]) –

  • depth (Optional[str]) –

  • branch (Optional[str]) –

  • origin (Optional[str]) –

  • upload_pack (Optional[str]) –

  • shallow_since (Optional[str]) –

  • shallow_exclude (Optional[str]) –

  • negotiation_tip (Optional[str]) –

  • jobs (Optional[str]) –

  • server_option (Optional[str]) –

  • recurse_submodules (Optional[Union[bool, Literal[yes, on-demand, no]]]) –

  • recurse_submodules_default (Optional[Union[bool, Literal[yes, on-demand]]]) –

  • submodule_prefix (Optional[libvcs._internal.types.StrOrBytesPath]) –

  • all (Optional[bool]) –

  • force (Optional[bool]) –

  • keep (Optional[bool]) –

  • multiple (Optional[bool]) –

  • dry_run (Optional[bool]) –

  • append (Optional[bool]) –

  • atomic (Optional[bool]) –

  • ipv4 (Optional[bool]) –

  • ipv6 (Optional[bool]) –

  • progress (Optional[bool]) –

  • quiet (Optional[bool]) –

  • verbose (Optional[bool]) –

  • unshallow (Optional[bool]) –

  • update_shallow (Optional[bool]) –

  • negotiate_tip (Optional[bool]) –

  • no_write_fetch_head (Optional[bool]) –

  • write_fetch_head (Optional[bool]) –

  • no_auto_maintenance (Optional[bool]) –

  • auto_maintenance (Optional[bool]) –

  • no_write_commit_graph (Optional[bool]) –

  • write_commit_graph (Optional[bool]) –

  • prefetch (Optional[bool]) –

  • prune (Optional[bool]) –

  • prune_tags (Optional[bool]) –

  • no_tags (Optional[bool]) –

  • tags (Optional[bool]) –

  • no_recurse_submodules (Optional[bool]) –

  • set_upstream (Optional[bool]) –

  • update_head_ok (Optional[bool]) –

  • show_forced_updates (Optional[bool]) –

  • no_show_forced_updates (Optional[bool]) –

  • negotiate_only (Optional[bool]) –

  • kwargs (Any) –

Return type:

str

help(*, all=None, verbose=None, no_external_commands=None, no_aliases=None, config=None, guides=None, info=None, man=None, web=None, **kwargs)#

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.

  • 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>]..."
init(*, template=None, separate_git_dir=None, object_format=None, branch=None, initial_branch=None, shared=None, quiet=None, bare=None, **kwargs)#

Create empty repo. Wraps git init.

Parameters:

  • quiet (bool) – --quiet

  • bare (bool) – --bare

  • object_format (Optional[Literal[sha1, sha256]]) – Hash algorithm used for objects. SHA-256 is still experimental as of git 2.36.0.

  • template (Optional[str]) –

  • separate_git_dir (Optional[libvcs._internal.types.StrOrBytesPath]) –

  • branch (Optional[str]) –

  • initial_branch (Optional[str]) –

  • shared (Optional[bool]) –

  • kwargs (Any) –

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 ...'
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, **kwargs)#

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
Parameters:

  • reftag (Optional[Any]) –

  • repository (Optional[str]) –

  • deepen (Optional[str]) –

  • depth (Optional[str]) –

  • branch (Optional[str]) –

  • origin (Optional[str]) –

  • upload_pack (Optional[str]) –

  • shallow_since (Optional[str]) –

  • shallow_exclude (Optional[str]) –

  • negotiation_tip (Optional[str]) –

  • jobs (Optional[str]) –

  • server_option (Optional[str]) –

  • recurse_submodules (Optional[Union[bool, Literal[yes, on-demand, no]]]) –

  • recurse_submodules_default (Optional[Union[bool, Literal[yes, on-demand]]]) –

  • submodule_prefix (Optional[libvcs._internal.types.StrOrBytesPath]) –

  • cleanup (Optional[str]) –

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

  • no_rebase (Optional[bool]) –

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

  • strategy_option (Optional[str]) –

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

  • no_gpg_sign (Optional[bool]) –

  • commit (Optional[bool]) –

  • no_commit (Optional[bool]) –

  • edit (Optional[bool]) –

  • no_edit (Optional[bool]) –

  • fast_forward_only (Optional[bool]) –

  • fast_forward (Optional[bool]) –

  • no_fast_forward (Optional[bool]) –

  • sign_off (Optional[bool]) –

  • no_sign_off (Optional[bool]) –

  • stat (Optional[bool]) –

  • no_stat (Optional[bool]) –

  • squash (Optional[bool]) –

  • no_squash (Optional[bool]) –

  • verify (Optional[bool]) –

  • no_verify (Optional[bool]) –

  • verify_signatures (Optional[bool]) –

  • no_verify_signatures (Optional[bool]) –

  • summary (Optional[bool]) –

  • no_summary (Optional[bool]) –

  • autostash (Optional[bool]) –

  • no_autostash (Optional[bool]) –

  • allow_unrelated_histories (Optional[bool]) –

  • fetch (Optional[bool]) –

  • no_fetch (Optional[bool]) –

  • all (Optional[bool]) –

  • force (Optional[bool]) –

  • keep (Optional[bool]) –

  • multiple (Optional[bool]) –

  • dry_run (Optional[bool]) –

  • append (Optional[bool]) –

  • atomic (Optional[bool]) –

  • ipv4 (Optional[bool]) –

  • ipv6 (Optional[bool]) –

  • progress (Optional[bool]) –

  • quiet (Optional[bool]) –

  • verbose (Optional[bool]) –

  • unshallow (Optional[bool]) –

  • update_shallow (Optional[bool]) –

  • negotiate_tip (Optional[bool]) –

  • no_write_fetch_head (Optional[bool]) –

  • write_fetch_head (Optional[bool]) –

  • no_auto_maintenance (Optional[bool]) –

  • auto_maintenance (Optional[bool]) –

  • no_write_commit_graph (Optional[bool]) –

  • write_commit_graph (Optional[bool]) –

  • prefetch (Optional[bool]) –

  • prune (Optional[bool]) –

  • prune_tags (Optional[bool]) –

  • no_tags (Optional[bool]) –

  • tags (Optional[bool]) –

  • no_recurse_submodules (Optional[bool]) –

  • set_upstream (Optional[bool]) –

  • update_head_ok (Optional[bool]) –

  • show_forced_updates (Optional[bool]) –

  • no_show_forced_updates (Optional[bool]) –

  • negotiate_only (Optional[bool]) –

  • kwargs (Any) –

Return type:

str

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, **kwargs)#

Reapply commit on top of another tip.

Wraps git rebase.

Parameters:

  • continue (bool) – Accepted via kwargs

  • upstream (Optional[str]) –

  • onto (Optional[str]) –

  • branch (Optional[str]) –

  • apply (Optional[bool]) –

  • merge (Optional[bool]) –

  • quiet (Optional[bool]) –

  • verbose (Optional[bool]) –

  • stat (Optional[bool]) –

  • no_stat (Optional[bool]) –

  • verify (Optional[bool]) –

  • no_verify (Optional[bool]) –

  • fork_point (Optional[bool]) –

  • no_fork_point (Optional[bool]) –

  • whitespace (Optional[str]) –

  • no_whitespace (Optional[bool]) –

  • commit_date_is_author_date (Optional[bool]) –

  • ignore_date (Optional[bool]) –

  • root (Optional[bool]) –

  • autostash (Optional[bool]) –

  • no_autostash (Optional[bool]) –

  • autosquash (Optional[bool]) –

  • no_autosquash (Optional[bool]) –

  • reschedule_failed_exec (Optional[bool]) –

  • no_reschedule_failed_exec (Optional[bool]) –

  • context (Optional[int]) –

  • rerere_autoupdate (Optional[bool]) –

  • no_rerere_autoupdate (Optional[bool]) –

  • keep_empty (Optional[bool]) –

  • no_keep_empty (Optional[bool]) –

  • reapply_cherry_picks (Optional[bool]) –

  • no_reapply_cherry_picks (Optional[bool]) –

  • allow_empty_message (Optional[bool]) –

  • signoff (Optional[bool]) –

  • keep_base (Optional[bool]) –

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

  • strategy_option (Optional[str]) –

  • exec (Optional[str]) –

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

  • no_gpg_sign (Optional[bool]) –

  • empty (Optional[Union[str, Literal[drop, keep, ask]]]) –

  • rebase_merges (Optional[Union[str, Literal[rebase-cousins, no-rebase-cousins]]]) –

  • interactive (Optional[bool]) –

  • edit_todo (Optional[bool]) –

  • skip (Optional[bool]) –

  • show_current_patch (Optional[bool]) –

  • abort (Optional[bool]) –

  • quit (Optional[bool]) –

  • kwargs (Any) –

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
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, **kwargs)#

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')
''
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, **kwargs)#

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'