Callbacks

Many pygit2 operations accept callback objects. The callbacks module provides base classes that you can subclass to customize behavior such as progress reporting, credential lookup, or checkout notifications.

Remote callbacks

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.

Checkout callbacks

class pygit2.CheckoutCallbacks

Base class for pygit2 checkout callbacks.

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

checkout_notify(why: CheckoutNotify, path: str, baseline: DiffFile | None, target: DiffFile | None, workdir: DiffFile | None) → None

Checkout will invoke an optional notification callback for certain cases - you pick which ones via checkout_notify_flags.

Raising an exception from this callback will cancel the checkout. The exception will be propagated back and raised by the Repository.checkout_... call.

Notification callbacks are made prior to modifying any files on disk, so canceling on any notification will still happen prior to any files being modified.

checkout_notify_flags() → CheckoutNotify

Returns a bit mask of the notifications to receive from a checkout (a combination of enums.CheckoutNotify constants).

By default, if you override checkout_notify, all notifications will be enabled. You can fine tune the notification types to enable by overriding checkout_notify_flags.

Please note that the flags are only sampled once when checkout begins. You cannot change the flags while a checkout is in progress.

checkout_progress(path: str, completed_steps: int, total_steps: int) → None

Optional callback to notify the consumer of checkout progress.

Stash apply callbacks

class pygit2.StashApplyCallbacks

Base class for pygit2 stash apply callbacks.

Inherit from this class and override the callbacks that you want to use in your class, which you can then pass to stash apply or pop operations.

stash_apply_progress(progress: StashApplyProgress) → None

Stash application progress notification function.

progress is a StashApplyProgress constant.

Raising an exception from this callback will abort the stash application.

Passthrough

Callbacks may raise pygit2.Passthrough to tell libgit2 to behave as if the callback had not been set. This is useful when a callback only wants to handle some cases and let libgit2 use its default behavior for the rest. See General for the exception reference.