libvcs.projects.git#

For git(1).

Compare to: fabtools.require.git, salt.projects.git, ansible.builtin.git

Git Repo object for libvcs.

libvcs.projects.git.GitFullRemoteDict#
class libvcs.projects.git.GitProject(*, url, dir, remotes=None, **kwargs)[source]#

Bases: libvcs.projects.base.BaseProject

Base class for repositories.

Parameters:
  • url (str) –

  • dir (libvcs._internal.types.StrPath) –

  • remotes (GitRemotesArgs) –

bin_name = git#
static chomp_protocol(url)[source]#

Return clean VCS url from RFC-style url

Parameters:

url (str) – PIP-style url

Return type:

URL as VCS software would accept it

classmethod from_pip_url(cls, pip_url, **kwargs)[source]#
get_current_remote_name(self)[source]#

Retrieve name of the remote / upstream of currently checked out branch.

Returns:

  • If upstream the same, returns branch_name.

  • If upstream mismatches, returns remote_name/branch_name.

Return type:

str

get_git_version(self)[source]#

Return current version of git binary

Return type:

git version

get_revision(self)[source]#

Return current revision. Initial repositories return ‘initial’.

obtain(self, *args, **kwargs)[source]#

Retrieve the repository, clone if doesn’t exist.

remote(self, name, **kwargs)[source]#

Get the fetch and push URL for a specified remote name.

Parameters:

name (str) – The remote name used to define the fetch and push URL

Return type:

Remote name and url in tuple form

remotes(self, flat: Literal[False] = ...)[source]#

Return remotes like git remote -v.

Parameters:

flat (bool) – Return a dict of tuple instead of dict, default False.

Return type:

dict of git upstream / remote URLs

schemes = ['git+http', 'git+https', 'git+file']#
set_remote(self, name, url, push=False, overwrite=False)[source]#

Set remote with name and URL like git remote add.

Parameters:
  • name (str) – defines the remote name.

  • url (str) – defines the remote URL

  • push (bool) –

set_remotes(self, overwrite=False)[source]#
Parameters:

overwrite (bool) –

status(self)[source]#

Retrieve status of project in dict format.

Wraps git status --sb --porcelain=2. Does not include changed files, yet.

Return type:

Status of current checked out repository

Examples

>>> git_repo = GitProject(
...     url=f'file://{create_git_remote_repo()}',
...     dir=tmp_path
... )
>>> git_repo.obtain()
>>> git_repo.status()
GitStatus(branch_oid='...', branch_head='master', branch_upstream='origin/master', branch_ab='+0 -0', branch_ahead='0', branch_behind='0')
update_repo(self, set_remotes=False, *args, **kwargs)[source]#
Parameters:

set_remotes (bool) –

libvcs.projects.git.GitProjectRemoteDict#
class libvcs.projects.git.GitRemote[source]#

Structure containing git working copy information.

fetch_url#
name#
push_url#
to_dict(self)[source]#
to_tuple(self)[source]#
class libvcs.projects.git.GitRemoteDict[source]#

Bases: TypedDict

For use when hydrating GitProject via dict.

fetch_url#
push_url#
libvcs.projects.git.GitRemotesArgs#
class libvcs.projects.git.GitStatus[source]#
branch_ab#
branch_ahead#
branch_behind#
branch_head#
branch_oid#
branch_upstream#
classmethod from_stdout(cls, value)[source]#

Returns git status -sb --porcelain=2 extracted to a dict

Return type:

Dictionary of git repo’s status

Parameters:

value (str) –

to_dict(self)[source]#
to_tuple(self)[source]#
class libvcs.projects.git.VCSLocation[source]#

Bases: NamedTuple

rev#
url#
libvcs.projects.git.base_convert_pip_url(pip_url)[source]#

Parse pip URL via libvcs.projects.base.BaseProject.url.

Parameters:

pip_url (str) –

Return type:

VCSLocation

libvcs.projects.git.convert_pip_url(pip_url)[source]#

Prefixes stub URLs like ‘user@hostname:user/repo.git’ with ‘ssh://’. That’s required because although they use SSH they sometimes doesn’t work with a ssh:// scheme (e.g. Github). But we need a scheme for parsing. Hence we remove it again afterwards and return it as a stub. The manpage for git-clone(1) refers to this as the “scp-like styntax”.

Parameters:

pip_url (str) –

Return type:

libvcs.projects.base.VCSLocation

libvcs.projects.git.logger#