libvcs.sync.git#

For git(1).

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

Git Repo object for libvcs.

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

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

Returns 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]#

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, dir, remotes=None, **kwargs)[source]#

Bases: BaseSync

A git repository.

Parameters:

Examples

import os
from libvcs.sync.git import GitSync

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

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   dir=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",
   dir=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, dir, remotes=None, **kwargs)[source]#

A git repository.

Parameters:
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",
   dir=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",
   dir=checkout,
   remotes={
       'gitlab': {
           'fetch_url': 'https://gitlab.com/vcs-python/libvcs',
           'push_url': 'https://gitlab.com/vcs-python/libvcs',
       },
   }
)
_remotes: dict[str, libvcs.sync.git.GitRemote]#
classmethod from_pip_url(pip_url, **kwargs)[source]#
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]#
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]#
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()}',
...     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')
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.