remote¶

For git-remote(1).

Overview¶

Manage git remotes using GitRemoteManager (collection-level) and GitRemoteCmd (per-remote operations).

Example¶

from libvcs.cmd.git import Git

git = Git(path='/path/to/repo')

# List all remotes
remotes = git.remotes.ls()

# Add a new remote
git.remotes.add(name='upstream', url='https://github.com/org/repo.git')

# Get a specific remote and operate on it
origin = git.remotes.get(remote_name='origin')
origin.show()
origin.prune()
origin.set_url('https://new-url.git')

API Reference¶

class libvcs.cmd.git.GitRemoteManager(*, path, cmd=None)[source]¶

Bases: object

Traverse and manage git remotes with ORM-like filtering via QueryList.

Wrap some of git-remote(1), git-checkout(1), manager.

Parameters:

  • path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

  • cmd (Git | None)

Examples

>>> GitRemoteManager(path=tmp_path)
<GitRemoteManager path=...>

>>> GitRemoteManager(path=tmp_path).run(check_returncode=False)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitRemoteManager(
...     path=example_git_repo.path
... ).run()
'origin'
remote_name: str¶
__init__(*, path, cmd=None)[source]¶

Wrap some of git-remote(1), git-checkout(1), manager.

Parameters:

  • path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

  • cmd (Git | None)

Return type:

None

Examples

>>> GitRemoteManager(path=tmp_path)
<GitRemoteManager path=...>

>>> GitRemoteManager(path=tmp_path).run(check_returncode=False)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitRemoteManager(
...     path=example_git_repo.path
... ).run()
'origin'
path: Path¶

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)[source]¶

Run a command against a git repository’s remotes.

Wraps git remote.

Return type:

str

Parameters:

  • command (Literal['--verbose', 'add', 'rename', 'remove', 'set-branches', 'set-head', 'set-branch', 'get-url', 'set-url', 'set-url --add', 'set-url --delete', 'prune', 'show', 'update'] | None)

  • local_flags (list[str] | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Examples

>>> GitRemoteManager(path=example_git_repo.path).run()
'origin'
add(*, name, url, fetch=None, track=None, master=None, mirror=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote add.

Return type:

str

Parameters:

  • name (str)

  • url (str)

  • fetch (bool | None)

  • track (str | None)

  • master (str | None)

  • mirror (Literal['push', 'fetch'] | bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> GitRemoteManager(path=example_git_repo.path).add(
...     name='my_remote',
...     url=f'file://{git_remote_repo}'
... )
''
show(*, name=None, verbose=None, no_query_remotes=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote show.

Return type:

str

Parameters:

  • name (str | None)

  • verbose (bool | None)

  • no_query_remotes (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> GitRemoteManager(path=example_git_repo.path).show()
'origin'

For the example below, add a remote: >>> GitRemoteManager(path=example_git_repo.path).add( … name=’my_remote’, url=f’file:///dev/null’ … ) ‘’

Retrieve a list of remote names: >>> GitRemoteManager(path=example_git_repo.path).show().splitlines() [‘my_remote’, ‘origin’]

_ls()[source]¶

List remotes (raw output).

Return type:

str

Examples

>>> GitRemoteManager(path=example_git_repo.path)._ls()
'origin\tfile:///... (fetch)\norigin\tfile:///... (push)'
ls()[source]¶

List remotes.

Return type:

QueryList[GitRemoteCmd]

Examples

>>> GitRemoteManager(path=example_git_repo.path).ls()
[<GitRemoteCmd path=... remote_name=origin>]

For the example below, add a remote: >>> GitRemoteManager(path=example_git_repo.path).add( … name=’my_remote’, url=f’file:///dev/null’ … ) ‘’

>>> GitRemoteManager(path=example_git_repo.path).ls()
[<GitRemoteCmd path=... remote_name=my_remote>,
 <GitRemoteCmd path=... remote_name=origin>]
get(*args, **kwargs)[source]¶

Get remote via filter lookup.

Return type:

GitRemoteCmd | None

Parameters:

Examples

>>> GitRemoteManager(
...     path=example_git_repo.path
... ).get(remote_name='origin')
<GitRemoteCmd path=... remote_name=origin>

>>> GitRemoteManager(
...     path=example_git_repo.path
... ).get(remote_name='unknown')
Traceback (most recent call last):
    exec(compile(example.source, filename, "single",
    ...
    return self.ls().get(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "..._internal/query_list.py", line ..., in get
    raise ObjectDoesNotExist
libvcs._internal.query_list.ObjectDoesNotExist
filter(*args, **kwargs)[source]¶

Get remotes via filter lookup.

Return type:

list[GitRemoteCmd]

Parameters:

Examples

>>> GitRemoteManager(
...     path=example_git_repo.path
... ).filter(remote_name__contains='origin')
[<GitRemoteCmd path=... remote_name=origin>]

>>> GitRemoteManager(
...     path=example_git_repo.path
... ).filter(remote_name__contains='unknown')
[]
class libvcs.cmd.git.GitRemoteCmd(*, path, remote_name, fetch_url=None, push_url=None, cmd=None)[source]¶

Bases: object

Run git commands targeting a specific remote.

Lite, typed, pythonic wrapper for git-remote(1).

Parameters:

  • path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

  • remote_name (str) – Name of remote

  • fetch_url (str | None)

  • push_url (str | None)

  • cmd (Git | None)

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... )
<GitRemoteCmd path=... remote_name=...>

>>> GitRemoteCmd(
...     path=tmp_path,
...     remote_name='origin',
... ).run(verbose=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... ).run(verbose=True)
'origin\tfile:///...'
__init__(*, path, remote_name, fetch_url=None, push_url=None, cmd=None)[source]¶

Lite, typed, pythonic wrapper for git-remote(1).

Parameters:

  • path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

  • remote_name (str) – Name of remote

  • fetch_url (str | None)

  • push_url (str | None)

  • cmd (Git | None)

Return type:

None

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... )
<GitRemoteCmd path=... remote_name=...>

>>> GitRemoteCmd(
...     path=tmp_path,
...     remote_name='origin',
... ).run(verbose=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... ).run(verbose=True)
'origin\tfile:///...'
path: Path¶

Directory to check out

remote_name: str¶
fetch_url: str | None¶
push_url: str | None¶
run(command=None, local_flags=None, *, verbose=None, log_in_real_time=False, check_returncode=None, **kwargs)[source]¶

Run command against a git remote.

Wraps git remote.

Return type:

str

Parameters:

  • command (Literal['add', 'rename', 'remove', 'set-branches', 'set-head', 'set-branch', 'get-url', 'set-url', 'set-url --add', 'set-url --delete', 'prune', 'show', 'update'] | None)

  • local_flags (list[str] | None)

  • verbose (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='master',
... ).run()
'origin'
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='master',
... ).run(verbose=True)
'origin\tfile:///...'
rename(*, old, new, progress=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote rename.

Return type:

str

Parameters:

  • old (str)

  • new (str)

  • progress (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... ).rename(old='origin', new='new_name')
''
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... ).run()
'new_name'
remove(*, log_in_real_time=False, check_returncode=None)[source]¶

Git remote remove.

Return type:

str

Parameters:

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... ).remove()
''
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin',
... ).run()
''
show(*, verbose=None, no_query_remotes=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote show.

Return type:

str

Parameters:

  • verbose (bool | None)

  • no_query_remotes (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> print(
...     GitRemoteCmd(
...         path=example_git_repo.path,
...         remote_name='origin',
...     ).show()
... )
* remote origin
Fetch URL: ...
Push  URL: ...
HEAD branch: master
Remote branch:
master tracked...
prune(*, dry_run=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote prune.

Return type:

str

Parameters:

  • dry_run (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).prune()
''

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).prune(dry_run=True)
''
get_url(*, push=None, _all=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote get-url.

Return type:

str

Parameters:

  • push (bool | None)

  • _all (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).get_url()
'file:///...'

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).get_url(push=True)
'file:///...'

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).get_url(_all=True)
'file:///...'
set_url(*, url, old_url=None, push=None, add=None, delete=None, log_in_real_time=False, check_returncode=None)[source]¶

Git remote set-url.

Return type:

str

Parameters:

  • url (str)

  • old_url (str | None)

  • push (bool | None)

  • add (bool | None)

  • delete (bool | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_url(
...     url='http://localhost'
... )
''

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_url(
...     url='http://localhost',
...     push=True
... )
''

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_url(
...     url='http://localhost',
...     add=True
... )
''

>>> current_url = GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).get_url()
>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_url(
...     url=current_url,
...     delete=True
... )
'fatal: Will not delete all non-push URLs'
set_branches(*branches, add=False, log_in_real_time=False, check_returncode=None)[source]¶

Git remote set-branches.

Configure remote tracking branches for the remote.

Parameters:

  • *branches (str) – Branch names to track.

  • add (bool) – Add to existing tracked branches instead of replacing.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_branches('master')
''

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_branches('master', 'develop', add=True)
''
set_head(branch=None, *, auto=False, delete=False, log_in_real_time=False, check_returncode=None)[source]¶

Git remote set-head.

Set or delete the default branch (HEAD) for the remote.

Parameters:

  • branch (str | None) – Branch name to set as HEAD. Required unless auto or delete is True.

  • auto (bool) – Query the remote to determine HEAD automatically.

  • delete (bool) – Delete the remote HEAD reference.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_head(auto=True)
'origin/HEAD set to master'

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_head('master')
''
update(*, prune=False, log_in_real_time=False, check_returncode=None)[source]¶

Git remote update.

Fetch updates for the remote.

Parameters:

  • prune (bool) – Prune remote-tracking branches no longer on remote.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).update()
'Fetching origin...'

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).update(prune=True)
'Fetching origin...'