`libvcs.sync.git`¶

For git(1).

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

Tool to manage a local git clone from an external git repository.

exception libvcs.sync.git.GitStatusParsingException(git_status_output, *args)[source]¶

Bases: LibVCSException

Raised when git status output is not in the expected format.

Parameters:

git_status_output (str)
args (object)

Return type:

None

exception libvcs.sync.git.GitRemoteOriginMissing(remotes, *args)[source]¶

Bases: LibVCSException

Raised when git origin remote was not found.

Parameters:

remotes (list[str])
args (object)

Return type:

None

exception libvcs.sync.git.GitRemoteSetError(remote_name)[source]¶

Bases: LibVCSException

Raised when a git remote could not be set.

Parameters:: remote_name (str)
Return type:: None

exception libvcs.sync.git.GitNoBranchFound(*args)[source]¶

Bases: LibVCSException

Raised with git branch could not be found.

Parameters:: args (object)
Return type:: None

exception libvcs.sync.git.GitRemoteRefNotFound(git_tag, ref_output, *args)[source]¶

Bases: CommandError

Raised when a git remote ref (tag, branch) could not be found.

Parameters:

git_tag (str)
ref_output (str)
args (object)

Return type:

None

class libvcs.sync.git.GitRemote(name, fetch_url, push_url)[source]¶

Bases: object

Structure containing git working copy information.

Parameters:

name (str)
fetch_url (str)
push_url (str)

name: str¶

fetch_url: str¶

push_url: str¶

class libvcs.sync.git.GitStatus(branch_oid=None, branch_head=None, branch_upstream=None, branch_ab=None, branch_ahead=None, branch_behind=None)[source]¶

Bases: object

Git status information.

Parameters:

branch_oid (str | None)
branch_head (str | None)
branch_upstream (str | None)
branch_ab (str | None)
branch_ahead (str | None)
branch_behind (str | None)

branch_oid: Optional[str] = None¶

branch_head: Optional[str] = None¶

branch_upstream: Optional[str] = None¶

branch_ab: Optional[str] = None¶

branch_ahead: Optional[str] = None¶

branch_behind: Optional[str] = None¶

classmethod from_stdout(value)[source]¶

Return git status -sb --porcelain=2 extracted to a dict.

Return type:: Dictionary of git repo’s status
Parameters:: value (str)

libvcs.sync.git.convert_pip_url(pip_url)[source]¶

Convert pip-style URL to a VCSLocation.

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”.

Return type:: VCSLocation
Parameters:: pip_url (str)

class libvcs.sync.git.GitSync(*, url, path, remotes=None, **kwargs)[source]¶

Bases: BaseSync

Tool to manage a local git clone from an external git repository.

Local git repository.

Parameters:

url (str) – URL of repo
tls_verify (bool) – Should certificate for https be checked (default False)
path (Path)
remotes (None | dict[str, GitRemote] | dict[str, str])
kwargs (Any)

Examples

import os
from libvcs.sync.git import GitSync

checkout = pathlib.Path(__name__) + '/' + 'my_libvcs'

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   path=checkout,
   remotes={
       'gitlab': 'https://gitlab.com/vcs-python/libvcs'
   }
)

import os
from libvcs.sync.git import GitSync

checkout = pathlib.Path(__name__) + '/' + 'my_libvcs'

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   path=checkout,
   remotes={
       'gitlab': {
           'fetch_url': 'https://gitlab.com/vcs-python/libvcs',
           'push_url': 'https://gitlab.com/vcs-python/libvcs',
       },
   }
)

bin_name: str = 'git'¶: VCS app name, e.g. ‘git’

schemes: tuple[str, ...] = ('git+http', 'git+https', 'git+file')¶: List of supported schemes to register in urlparse.uses_netloc

__init__(*, url, path, remotes=None, **kwargs)[source]¶

Local git repository.

Parameters:

url (str) – URL of repo
tls_verify (bool) – Should certificate for https be checked (default False)
path (str | PathLike[str])
remotes (None | dict[str, GitRemote] | dict[str, str])
kwargs (Any)

Return type:

None

Examples

import os
from libvcs.sync.git import GitSync

checkout = pathlib.Path(__name__) + '/' + 'my_libvcs'

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   path=checkout,
   remotes={
       'gitlab': 'https://gitlab.com/vcs-python/libvcs'
   }
)

import os
from libvcs.sync.git import GitSync

checkout = pathlib.Path(__name__) + '/' + 'my_libvcs'

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   path=checkout,
   remotes={
       'gitlab': {
           'fetch_url': 'https://gitlab.com/vcs-python/libvcs',
           'push_url': 'https://gitlab.com/vcs-python/libvcs',
       },
   }
)

_remotes: dict[str, GitRemote]¶

cmd: Git¶

classmethod from_pip_url(pip_url, **kwargs)[source]¶

Clone a git repository from a pip-style URL.

Return type:

GitSync

Parameters:

pip_url (str)
kwargs (Any)

get_revision()[source]¶

Return current revision. Initial repositories return ‘initial’.

Return type:: str

set_remotes(overwrite=False)[source]¶

Apply remotes in local repository to match GitSync’s configuration.

Return type:: None
Parameters:: overwrite (bool)

obtain(*args, **kwargs)[source]¶

Retrieve the repository, clone if doesn’t exist.

Return type:

None

Parameters:

args (Any)
kwargs (Any)

update_repo(set_remotes=False, *args, **kwargs)[source]¶

Pull latest changes from git remote.

Return type:

None

Parameters:

set_remotes (bool)
args (Any)
kwargs (Any)

remotes()[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

remote(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
kwargs (Any)

Return type:

Remote name and url in tuple form

set_remote(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)
overwrite (bool)

Return type:

GitRemote

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

get_git_version()[source]¶

Return current version of git binary.

Return type:: git version

status()[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 = GitSync(
...     url=f'file://{create_git_remote_repo()}',
...     path=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')

get_current_remote_name()[source]¶

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

Return type:

str

Returns:

If upstream the same, returns branch_name.
If upstream mismatches, returns remote_name/branch_name.

libvcs.sync.git¶

`libvcs.sync.git`¶