`remote`¶

For git-remote(1).

Overview¶

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

Examples¶

List remotes — a freshly cloned repository has its origin:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.remotes.ls()
[<GitRemoteCmd path=... remote_name=origin>]

Add a remote:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.remotes.add(name='upstream', url='https://github.com/org/repo.git')
''

Get a specific remote and operate on it through its Cmd object:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> origin = git.remotes.get(remote_name='origin')
>>> 'origin' in origin.show()
True
>>> origin.prune()
''
>>> origin.set_url(url='https://example.com/new.git')
''

API Reference¶

class libvcs.cmd.git.GitRemoteManager ¶ class[source] class[source] class libvcs.cmd.git.GitRemoteManager ¶

Bases: object

Traverse git remotes with QueryList.

__init__(*, path, cmd=None) ¶ method[source] method[source] __init__(*, path, cmd=None) ¶

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, trim=True)
'fatal: not a git repository (or any of the parent directories): .git'

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

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

Run a command against a git repository’s remotes.

Wraps git remote.

Examples

>>> GitRemoteManager(path=example_git_repo.path).run(trim=True)
'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[source] method[source] add(*, name, url, fetch=None, track=None, master=None, mirror=None, log_in_real_time=False, check_returncode=None) ¶

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, trim=False) ¶ method[source] method[source] show(*, name=None, verbose=None, no_query_remotes=None, log_in_real_time=False, check_returncode=None, trim=False) ¶

Git remote show.

Examples

>>> GitRemoteManager(path=example_git_repo.path).show(trim=True)
'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)
trim (bool)

Return type:

str

ls() ¶ method[source] method[source] ls() ¶

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[source]
method[source]
get(*args, **kwargs)
¶

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

class libvcs.cmd.git.GitRemoteCmd ¶ class[source] class[source] class libvcs.cmd.git.GitRemoteCmd ¶

Bases: object

Run git commands targeting a specific remote.

__init__(*, path, remote_name, fetch_url=None, push_url=None, cmd=None) ¶ method[source] method[source] __init__(*, path, remote_name, fetch_url=None, push_url=None, cmd=None) ¶

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

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

Run command against a git remote.

Wraps git remote.

Examples

>>> GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='master',
... ).run(trim=True)
'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[source] method[source] rename(*, old, new, progress=None, log_in_real_time=False, check_returncode=None) ¶

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(trim=True)
'new_name'

Parameters:

old (str)
new (str)
progress (bool | None)
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[source] method[source] show(*, verbose=None, no_query_remotes=None, log_in_real_time=False, check_returncode=None) ¶

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[source] method[source] prune(*, dry_run=None, log_in_real_time=False, check_returncode=None) ¶

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[source] method[source] get_url(*, push=None, _all=None, log_in_real_time=False, check_returncode=None) ¶

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[source] method[source] set_url(*, url, old_url=None, push=None, add=None, delete=None, log_in_real_time=False, check_returncode=None) ¶

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()
>>> 'fatal' in GitRemoteCmd(
...     path=example_git_repo.path,
...     remote_name='origin'
... ).set_url(
...     url=current_url,
...     delete=True
... )
True

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[source] method[source] set_branches(*branches, add=False, log_in_real_time=False, check_returncode=None) ¶

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[source] method[source] set_head(branch=None, *, auto=False, delete=False, log_in_real_time=False, check_returncode=None) ¶

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

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

The exact message wording varies across git versions (git 2.54+ reports “is unchanged” when HEAD already points at the branch), so assert on the stable parts rather than the literal string:

>>> 'master' in remote.set_head(auto=True)
True
>>> isinstance(remote.set_head('master'), str)
True

update(*, prune=False, log_in_real_time=False, check_returncode=None) ¶ method[source] method[source] update(*, prune=False, log_in_real_time=False, check_returncode=None) ¶

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

remote¶

Overview¶

Examples¶

API Reference¶

`remote`¶