# Remotes

Repository.remotes

  The collection of configured remotes, an instance of `pygit2.remotes.RemoteCollection`

## The remote collection

class pygit2.remotes.RemoteCollection(repo: BaseRepository)

  Collection of configured remotes

  You can use this class to look up and manage the remotes configured in a repository. You can access repositories using index access. E.g. to look up the “origin” remote, you can use

      >>> repo.remotes["origin"]

  add_fetch(name: str, refspec: str) → None

    Add a fetch refspec (str) to the remote

  add_push(name: str, refspec: str) → None

    Add a push refspec (str) to the remote

  create(name: str, url: str, fetch: str | None = None) → Remote

    Create a new remote with the given name and url. Returns a <Remote> object.

    If ‘fetch’ is provided, this fetch refspec will be used instead of the default.

  create_anonymous(url: str) → Remote

    Create a new anonymous (in-memory only) remote with the given URL. Returns a <Remote> object.

  delete(name: str) → None

    Remove a remote from the configuration

    All remote-tracking branches and configuration settings for the remote will be removed.

  names() → Generator[str | None, None, None]

    An iterator over the names of the available remotes.

  rename(name: str, new_name: str) → list[str]

    Rename a remote in the configuration. The refspecs in standard format will be renamed.

    Returns a list of fetch refspecs (list of strings) which were not in the standard format and thus could not be remapped.

  set_push_url(name: str, url: str) → None

    Set the push-URL for a remote

  set_url(name: str, url: str) → None

    Set the URL for a remote

## The Remote type

class pygit2.Remote(repo: BaseRepository, ptr: GitRemoteC)
  connect(callbacks: RemoteCallbacks | None = None, direction: int = 0, proxy: None | bool | str = None) → None

    Connect to the remote.

    Parameters:

    proxyNone or True or str

      Proxy configuration. Can be one of:

      - None (the default) to disable proxy usage

      - True to enable automatic proxy detection

      - an url to a proxy (http://proxy.example.org:3128/)

  fetch(refspecs: list[str] | None = None, message: str | None = None, callbacks: RemoteCallbacks | None = None, prune: FetchPrune = FetchPrune.UNSPECIFIED, proxy: None | Literal[True] | str = None, depth: int = 0) → TransferProgress

    Perform a fetch against this remote. Returns a <TransferProgress> object.

    Parameters:

    pruneenums.FetchPrune

      - UNSPECIFIED: use the configuration from the repository.

      - PRUNE: remove any remote branch in the local repository

          that does not exist in the remote.

      - NO_PRUNE: always keep the remote branches

    proxyNone or True or str

      Proxy configuration. Can be one of:

      - None (the default) to disable proxy usage

      - True to enable automatic proxy detection

      - an url to a proxy (http://proxy.example.org:3128/)

    depthint

      Number of commits from the tip of each remote branch history to fetch.

      If non-zero, the number of commits from the tip of each remote branch history to fetch. If zero, all history is fetched. The default is 0 (all history is fetched).

  property fetch_refspecs: list[str]

    Refspecs that will be used for fetching

  get_refspec(n: int) → Refspec

    Return the <Refspec> object at the given position.

  list_heads(callbacks: RemoteCallbacks | None = None, proxy: str | None | bool = None, connect: bool = True) → list[RemoteHead]

    Get the list of references with which the server responds to a new connection.

    Parameters:

    callbacks : Passed to connect()

    proxy : Passed to connect()

    connect : Whether to connect to the remote first. You can pass False if the remote has already connected. The list remains available after disconnecting as long as a new connection is not initiated.

  ls_remotes(callbacks: RemoteCallbacks | None = None, proxy: str | None | bool = None, connect: bool = True) → list[dict[str, Any]]

    Deprecated interface to list_heads

  property name: str | None

    Name of the remote

  prune(callbacks: RemoteCallbacks | None = None) → None

    Perform a prune against this remote.

  push(specs: list[str], callbacks: RemoteCallbacks | None = None, proxy: None | bool | str = None, push_options: None | list[str] = None, threads: int = 1) → None

    Push the given refspec to the remote. Raises `GitError` on protocol error or unpack failure.

    When the remote has a githook installed, that denies the reference this function will return successfully. Thus it is strongly recommended to install a callback, that implements `RemoteCallbacks.push_update_reference()` and check the passed parameters for successful operations.

    Parameters:

    specs[str]

      Push refspecs to use.

    callbacks :

    proxyNone or True or str

      Proxy configuration. Can be one of:

      - None (the default) to disable proxy usage

      - True to enable automatic proxy detection

      - an url to a proxy (http://proxy.example.org:3128/)

    push_options[str]

      Push options to send to the server, which passes them to the pre-receive as well as the post-receive hook.

    threadsint

      If the transport being used to push to the remote requires the creation of a pack file, this controls the number of worker threads used by the packbuilder when creating that pack file to be sent to the remote.

      If set to 0, the packbuilder will auto-detect the number of threads to create. The default value is 1.

  property push_refspecs: list[str]

    Refspecs that will be used for pushing

  property push_url: str | None

    Push url of the remote

  property refspec_count: int

    Total number of refspecs in this remote

  property url: str | None

    Url of the remote

## The RemoteCallbacks type

See Callbacks for the full reference. The following autoclass is only included here for discoverability.

class pygit2.RemoteCallbacks(credentials: Username | UserPass | Keypair | None = None, certificate_check: Callable[[None, bool, bytes], bool] | None = None)

  Base class for pygit2 remote callbacks.

  Inherit from this class and override the callbacks which you want to use in your class, which you can then pass to the network operations.

  For the credentials, you can either subclass and override the ‘credentials’ method, or if it’s a constant value, pass the value to the constructor, e.g. RemoteCallbacks(credentials=credentials).

  You can as well pass the certificate the same way, for example: RemoteCallbacks(certificate=certificate).

  certificate_check(certificate: None, valid: bool, host: bytes) → bool

    Certificate callback. Override with your own function to determine whether to accept the server’s certificate.

    Returns: True to connect, False to abort.

    Parameters:

    certificateNone

      The certificate. It is currently always None while we figure out how to represent it cross-platform.

    validbool

      Whether the TLS/SSH library thinks the certificate is valid.

    hoststr

      The hostname we want to connect to.

  credentials(url: str, username_from_url: str | None, allowed_types: CredentialType) → Username | UserPass | Keypair

    Credentials callback. If the remote server requires authentication, this function will be called and its return value used for authentication. Override it if you want to be able to perform authentication.

    Returns: credential

    Parameters:

    urlstr

      The url of the remote.

    username_from_urlstr or None

      Username extracted from the url, if any.

    allowed_typesCredentialType

      A combination of CredentialType bitflags representing the credential types supported by the remote.

  push_negotiation(updates: list[PushUpdate]) → None

    During a push, called once between the negotiation step and the upload. Provides information about what updates will be performed.

    Override with your own function to check the pending updates and possibly reject them (by raising an exception).

  push_transfer_progress(objects_pushed: int, total_objects: int, bytes_pushed: int) → None

    During the upload portion of a push, this will be regularly called with progress information.

    Be aware that this is called inline with pack building operations, so performance may be affected.

    Override with your own function to report push transfer progress.

  push_update_reference(refname: str, message: str) → None

    Push update reference callback. Override with your own function to report the remote’s acceptance or rejection of reference updates.

    refnamestr

      The name of the reference (on the remote).

    messagestr

      Rejection message from the remote. If None, the update was accepted.

  sideband_progress(string: str) → None

    Progress output callback. Override this function with your own progress reporting function

    Parameters:

    stringstr

      Progress output from the remote.

  transfer_progress(stats: TransferProgress) → None

    During the download of new data, this will be regularly called with the indexer’s progress.

    Override with your own function to report transfer progress.

    Parameters:

    statsTransferProgress

      The progress up to now.

  update_tips(refname: str, old: Oid, new: Oid) → None

    Update tips callback. Override with your own function to report reference updates.

    Parameters:

    refnamestr

      The name of the reference that’s being updated.

    oldOid

      The reference’s old value.

    newOid

      The reference’s new value.

## The TransferProgress type

This class contains the data which is available to us during a fetch.

class pygit2.remotes.TransferProgress(tp: Any)

  Progress downloading and indexing data during a fetch.

  indexed_deltas: int

    Deltas which have been indexed

  indexed_objects: int

    Objects which have been indexed

  local_objects: int

    Local objects which were used to fix the thin pack

  received_bytes: int

    “Number of bytes received up to now

  received_objects: int

    Objects which have been received up to now

  total_deltas: int

    Total number of deltas in the pack

  total_objects: int

    Total number of objects to download

## The RemoteHead type

Description of a reference advertised by a remote server, returned by `pygit2.Remote.list_heads()`.

class pygit2.remotes.RemoteHead(c_struct: Any)

  Description of a reference advertised by a remote server, given out on Remote.list_heads calls.

  local: bool

    Available locally

  symref_target: str | None

    If the server sent a symref mapping for this ref, this will point to the target.

## The PushUpdate type

Represents an update which will be performed on the remote during push. Passed to `pygit2.RemoteCallbacks.push_negotiation()`.

class pygit2.remotes.PushUpdate(c_struct: Any)

  Represents an update which will be performed on the remote during push.

  dst: Oid

    The new target for the reference

  dst_refname: str

    The name of the reference to update on the server

  src: Oid

    The current target of the reference

  src_refname: str

    The source name of the reference

## The Refspec type

Refspecs objects are not constructed directly, but returned by `pygit2.Remote.get_refspec()`. To create a new a refspec on a Remote, use `pygit2.Remote.add_fetch()` or `pygit2.Remote.add_push()`.

class pygit2.refspec.Refspec(owner, ptr)

  The constructor is for internal use only.

  property direction

    Direction of this refspec (fetch or push)

  property dst: str

    Destination or rhs of the refspec

  dst_matches(ref: str) → bool

    Return True if the given string matches the destination of this refspec, False otherwise.

  property force: bool

    Whether this refspeca llows non-fast-forward updates

  rtransform(ref: str) → str

    Transform a reference name according to this refspec from the lhs to the rhs. Return an string.

  property src: str

    Source or lhs of the refspec

  src_matches(ref: str) → bool

    Return True if the given string matches the source of this refspec, False otherwise.

  property string: str

    String which was used to create this refspec

  transform(ref: str) → str

    Transform a reference name according to this refspec from the lhs to the rhs. Return an string.

## Credentials

There are several types of credentials. All of them are callable objects, with the appropriate signature for the credentials callback.

They will ignore all the arguments and return themselves. This is useful for scripts where the credentials are known ahead of time. More complete interfaces would want to look up in their keychain or ask the user for the data to use in the credentials.

class pygit2.Username(username: str)

  Username credentials

  This is an object suitable for passing to a remote’s credentials callback and for returning from said callback.

class pygit2.UserPass(username: str, password: str)

  Username/Password credentials

  This is an object suitable for passing to a remote’s credentials callback and for returning from said callback.

class pygit2.Keypair(username: str, pubkey: str | Path | None, privkey: str | Path | None, passphrase: str | None)

  SSH key pair credentials.

  This is an object suitable for passing to a remote’s credentials callback and for returning from said callback.

  Parameters:

  usernamestr

    The username being used to authenticate with the remote server.

  pubkeystr

    The path to the user’s public key file.

  privkeystr

    The path to the user’s private key file.

  passphrasestr

    The password used to decrypt the private key file, or empty string if no passphrase is required.

class pygit2.KeypairFromAgent(username: str)

class pygit2.KeypairFromMemory(username: str, pubkey: str | Path | None, privkey: str | Path | None, passphrase: str | None)