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