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

class

Bases: object

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

remote_name: str

attribute

__init__(*, path, cmd=None)

method

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

Parameters:

• path (StrPath) – 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

attribute

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a git repository’s remotes.

Wraps git remote.

Examples

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

Parameters:

• command (GitRemoteManagerLiteral | None)

• local_flags (list[str] | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

add(*, name, url, fetch=None, track=None, master=None, mirror=None, log_in_real_time=False, check_returncode=None)

method

Git remote add.

Examples

>>> git_remote_repo = create_git_remote_repo()
>>> GitRemoteManager(path=example_git_repo.path).add(
...     name='my_remote',
...     url=f'file://{git_remote_repo}'
... )
''

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)

Return type:

str

show(*, name=None, verbose=None, no_query_remotes=None, log_in_real_time=False, check_returncode=None)

method

Git remote show.

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’]

Parameters:

• name (str | None)

• verbose (bool | None)

• no_query_remotes (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

_ls()

method

List remotes (raw output).

Examples

>>> GitRemoteManager(path=example_git_repo.path)._ls()
'origin\tfile:///... (fetch)\norigin\tfile:///... (push)'

Return type:

str

ls()

method

List remotes.

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

Return type:

QueryList[GitRemoteCmd]

get(*args, **kwargs)

method

Get remote via filter lookup.

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

Parameters:

• args (Any)

• kwargs (Any)

Return type:

GitRemoteCmd | None

filter(*args, **kwargs)

method

Get remotes via filter lookup.

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')
[]

Parameters:

• args (Any)

• kwargs (Any)

Return type:

list[GitRemoteCmd]

class libvcs.cmd.git.GitRemoteCmd

class

Bases: object

Run git commands targeting a specific remote.

__init__(*, path, remote_name, fetch_url=None, push_url=None, cmd=None)

method

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

Parameters:

• path (StrPath) – 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

attribute

Directory to check out

remote_name: str

attribute

fetch_url: str | None

attribute

push_url: str | None

attribute

run(command=None, local_flags=None, *, verbose=None, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run command against a git remote.

Wraps git remote.

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:///...'

Parameters:

• command (GitRemoteCommandLiteral | None)

• local_flags (list[str] | None)

• verbose (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

rename(*, old, new, progress=None, log_in_real_time=False, check_returncode=None)

method

Git remote rename.

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'

Parameters:

• old (str)

• new (str)

• progress (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

remove(*, log_in_real_time=False, check_returncode=None)

method

Git remote remove.

Examples

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

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

show(*, verbose=None, no_query_remotes=None, log_in_real_time=False, check_returncode=None)

method

Git remote show.

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

Parameters:

• verbose (bool | None)

• no_query_remotes (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

prune(*, dry_run=None, log_in_real_time=False, check_returncode=None)

method

Git remote prune.

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)
''

Parameters:

• dry_run (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

get_url(*, push=None, _all=None, log_in_real_time=False, check_returncode=None)

method

Git remote get-url.

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:///...'

Parameters:

• push (bool | None)

• _all (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

set_url(*, url, old_url=None, push=None, add=None, delete=None, log_in_real_time=False, check_returncode=None)

method

Git remote set-url.

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'

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)

Return type:

str

set_branches(*branches, add=False, log_in_real_time=False, check_returncode=None)

method

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)

method

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)

method

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