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, 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.
- create_anonymous(url)
Create a new anonymous (in-memory only) remote with the given URL. Returns a <Remote> object.
- delete(name)
Remove a remote from the configuration
All remote-tracking branches and configuration settings for the remote will be removed.
- names()
An iterator over the names of the available remotes.
- 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: BaseRepository, ptr)
- connect(callbacks=None, direction=0, proxy=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=None, message=None, callbacks=None, prune: FetchPrune = FetchPrune.UNSPECIFIED, proxy=None, depth=0)
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
Refspecs that will be used for fetching
- get_refspec(n)
Return the <Refspec> object at the given position.
- ls_remotes(callbacks=None, proxy=None)
Return a list of dicts that maps to git_remote_head from a ls_remotes call.
Parameters:
callbacks : Passed to connect()
proxy : Passed to connect()
- property name
Name of the remote
- prune(callbacks=None)
Perform a prune against this remote.
- push(specs, callbacks=None, proxy=None, push_options=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 successfull operations.Parameters:
- specs[str]
Push refspecs to use.
- 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.
- property push_refspecs
Refspecs that will be used for pushing
- property push_url
Push url of the remote
- property refspec_count
Total number of refspecs in this remote
- property url
Url of the remote
The RemoteCallbacks type
- class pygit2.RemoteCallbacks(credentials=None, certificate_check=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, valid, host)
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)
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_update_reference(refname, message)
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)
Progress output callback. Override this function with your own progress reporting function
Parameters:
- stringstr
Progress output from the remote.
- transfer_progress(stats)
Transfer progress callback. Override with your own function to report transfer progress.
Parameters:
- statsTransferProgress
The progress up to now.
- update_tips(refname, old, new)
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)
Progress downloading and indexing data during a fetch.
- indexed_deltas
Deltas which have been indexed
- indexed_objects
Objects which have been indexed
- local_objects
Local objects which were used to fix the thin pack
- received_bytes
“Number of bytes received up to now
- received_objects
Objects which have been received up to now
- total_deltas
Total number of deltas in the pack
- total_objects
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.
- property direction
Direction of this refspec (fetch or push)
- property dst
Destinaton or rhs of the refspec
- dst_matches(ref)
Return True if the given string matches the destination of this refspec, False otherwise.
- property 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.
- property src
Source or lhs of the refspec
- src_matches(ref)
Return True if the given string matches the source of this refspec, False otherwise.
- property 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 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)
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, 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:
- 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)
- class pygit2.KeypairFromMemory(username, pubkey, privkey, passphrase)