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(self, *, 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:

• quiet (bool) –

• progress (bool) –

• no_progress (bool) –

• pathspec_from_file (libvcs._internal.types.StrOrBytesPath) –

• pathspec (libvcs._internal.types.StrOrBytesPath or list) – libvcs._internal.types.StrOrBytesPath

• force (bool) –

• ours (bool) –

• theirs (bool) –

• no_track (bool) –

• guess (bool) –

• no_guess (bool) –

• ignore_skip_worktree_bits (bool) –

• merge (bool) –

• _list (bool) –

• detach (bool) –

• patch (bool) –

• orphan (bool) –

• conflict (str) –

• overwrite_ignore (bool) –

• no_overwrite_ignore (bool) –

• commit (str) –

• branch (str) –

• new_branch (str) –

• start_point (str) –

• treeish (str) –

• recurse_submodules (Optional[bool]) –

• no_recurse_submodules (Optional[bool]) –

• overlay (Optional[bool]) –

• no_overlay (Optional[bool]) –

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(self, *, 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]) –

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(self, *, 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]) –

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(self, *, 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]) –

help(self, *, 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.

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(self, *, 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]) –

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(self, *, 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]) –

rebase(self, *, 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]) –

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(self, *, 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:

• quiet (bool) –

• no_refresh (bool) –

• refresh (bool) –

• pathspec_from_file (libvcs._internal.types.StrOrBytesPath) –

• pathspec_file_nul (bool) –

• pathspec (libvcs._internal.types.StrOrBytesPath or list) – libvcs._internal.types.StrOrBytesPath

• soft (bool) –

• mixed (bool) –

• hard (bool) –

• merge (bool) –

• keep (bool) –

• commit (str) –

• recurse_submodules (Optional[bool]) –

• no_recurse_submodules (Optional[bool]) –

Examples

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

>>> git.reset()
''

>>> git.reset(soft=True, commit='HEAD~1')
''

status(self, *, 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:

• verbose (bool) –

• long (bool) –

• short (bool) –

• branch (bool) –

• z (bool) –

• column (bool) –

• no_column (bool) –

• ahead_behind (bool) –

• no_ahead_behind (bool) –

• find_renames (bool) –

• no_find_renames (bool) –

• porcelain (str, bool) –

• untracked_files ("no", "normal", "all") –

• ignored ("traditional", "no", "matching") –

• ignored_submodules ("untracked", "dirty", "all") –

• pathspec (libvcs._internal.types.StrOrBytesPath or list) – libvcs._internal.types.StrOrBytesPath

• renames (Optional[bool]) –

• no_renames (Optional[bool]) –

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'