# Remotes

`Repository.``remotes`

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

`Repository.``create_remote`(name, url)

  Create a new remote. Return a <Remote> object.

  This method is deprecated, please use Remote.remotes.create()

## The remote collection

class `pygit2.remote.``RemoteCollection`(repo)

  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, refspec)

    Add a fetch refspec (str) to the remote

  `add_push`(name, refspec)

    Add a push refspec (str) to the remote

  `create`(name, url, fetch=None)

    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

  `delete`(name)

    Remove a remote from the configuration

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

  `rename`(name, new_name)

    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, url)

    Set the push-URL for a remote

  `set_url`(name, url)

    Set the URL for a remote

## The Remote type

class `pygit2.``Remote`(repo, ptr)
  `fetch`(refspecs=None, message=None, callbacks=None, prune=0)

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

    Parameters:

    prune : enum
      Either <GIT_FETCH_PRUNE_UNSPECIFIED>, <GIT_FETCH_PRUNE>, or <GIT_FETCH_NO_PRUNE>. The first uses the configuration from the repo, the second will remove any remote branch in the local repository that does not exist in the remote and the last will always keep the remote branches
  `fetch_refspecs`

    Refspecs that will be used for fetching

  `get_refspec`(n)

    Return the <Refspec> object at the given position.

  `name`

    Name of the remote

  `push`(specs, callbacks=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 stronly recommended to install a callback, that implements `RemoteCallbacks.push_update_reference()` and check the passed parameters for successfull operations.

    Parameters:

    specs : [str]
      Push refspecs to use.
  `push_refspecs`

    Refspecs that will be used for pushing

  `push_url`

    Push url of the remote

  `refspec_count`

    Total number of refspecs in this remote

  `save`()

    Save a remote to its repository’s configuration.

  `url`

    Url of the remote

## The RemoteCallbacks type

class `pygit2.``RemoteCallbacks`(credentials=None, certificate=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.

  `certificate_check`(certificate, valid, host)

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

    Returns: True to connect, False to abort.

    Parameters:

    certificate : None
      The certificate. It is currently always None while we figure out how to represent it cross-platform.
    valid : bool
      Whether the TLS/SSH library thinks the certificate is valid.
    host : str
      The hostname we want to connect to.
  `credentials`(url, username_from_url, allowed_types)

    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:

    url : str
      The url of the remote.
    username_from_url : str or None
      Username extracted from the url, if any.
    allowed_types : int
      Credential types supported by the remote.
  `push_update_reference`(refname, message)

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

    refname : str
      The name of the reference (on the remote).
    messsage : str
      Rejection message from the remote. If None, the update was accepted.
  `sideband_progress`(string)

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

    Parameters:

    string : str
      Progress output from the remote.
  `transfer_progress`(stats)

    Transfer progress callback. Override with your own function to report transfer progress.

    Parameters:

    stats : TransferProgress
      The progress up to now.
  `update_tips`(refname, old, new)

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

    Parameters:

    refname : str
      The name of the reference that’s being updated.
    old : Oid
      The reference’s old value.
    new : Oid
      The reference’s new value.

## The TransferProgress type

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

class `pygit2.remote.``TransferProgress`(tp)

  Progress downloading and indexing data during a fetch

  `indexed_deltas` = None

    Deltas which have been indexed

  `indexed_objects` = None

    Objects which have been indexed

  `local_objects` = None

    Local objects which were used to fix the thin pack

  `received_bytes` = None

    “Number of bytes received up to now

  `received_objects` = None

    Objects which have been received up to now

  `total_deltas` = None

    Total number of deltas in the pack

  `total_objects` = None

    Total number of objects to download

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

  `direction`

    Direction of this refspec (fetch or push)

  `dst`

    Destinaton or rhs of the refspec

  `dst_matches`(ref)

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

  `force`

    Whether this refspeca llows non-fast-forward updates

  `rtransform`(ref)

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

  `src`

    Source or lhs of the refspec

  `src_matches`(ref)

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

  `string`

    String which was used to create this refspec

  `transform`(ref)

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

## Credentials

There are two types of credentials: username/password and SSH key pairs. Both `pygit2.UserPass` and `pygit2.Keypair` 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.``UserPass`(username, password)

  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, pubkey, privkey, passphrase)

  SSH key pair credentials.

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

  Parameters:

  username : str
    The username being used to authenticate with the remote server.
  pubkey : str
    The path to the user’s public key file.
  privkey : str
    The path to the user’s private key file.
  passphrase : str
    The password used to decrypt the private key file, or empty string if no passphrase is required.