pub struct GitAuthenticator { /* private fields */ }
Expand description

Configurable authenticator to use with git2.

Implementations§

source§

impl GitAuthenticator

source

pub fn new() -> Self

Create a new authenticator with all supported options enabled.

This is equivalent to:

GitAuthenticator::new_empty()
    .try_cred_helper(true)
    .try_password_prompt(3)
    .add_default_username()
    .try_ssh_agent(true)
    .add_default_ssh_keys()
    .prompt_ssh_key_password(true)
source

pub fn new_empty() -> Self

Create a new authenticator with all authentication options disabled.

source

pub fn add_plaintext_credentials( self, domain: impl Into<String>, username: impl Into<String>, password: impl Into<String> ) -> Self

Set the username + password to use for a specific domain.

Use the special value “*” for the domain name to add fallback credentials when there is no exact match for the domain.

source

pub fn try_cred_helper(self, enable: bool) -> Self

Configure if the git credentials helper should be used.

See the git documentation of the credential.helper configuration options for more details.

source

pub fn try_password_prompt(self, max_count: u32) -> Self

Configure the number of times we should prompt the user for a username/password.

Setting this value to 0 disables password prompts.

By default, if an askpass helper is configured, it will be used for the prompts. Otherwise, the user will be prompted directly on the terminal of the current process. If there is also no terminal available, the prompt is skipped.

An askpass helper can be configured in the GIT_ASKPASS environment variable, the core.askPass configuration value or the SSH_ASKPASS environment variable.

You can override the prompt behaviour by calling Self::set_prompter().

source

pub fn set_prompter<P: Prompter + Clone + Send + 'static>( self, prompter: P ) -> Self

Use a custom Prompter to prompt the user for credentials and passphrases.

If you set a custom prompter, the authenticator will no longer try to use the askpass helper or prompt the user on the terminal. Instead, the provided prompter will be called.

Note that prompts must still be enabled with Self::try_password_prompt() and Self::prompt_ssh_key_password(). If prompts are disabled, your custom prompter will not be called.

You can use this function to integrate the prompts with your own user interface or simply to tweak the way the user is prompted on the terminal.

A unique clone of the prompter will be used for each git2::Credentials callback returned by Self::credentials().

source

pub fn add_username( self, domain: impl Into<String>, username: impl Into<String> ) -> Self

Add a username to try for authentication for a specific domain.

Some authentication mechanisms need a username, but not all valid git URLs specify one. You can add one or more usernames to try in that situation.

You can use the special domain name “*” to set a fallback username for domains that do not have a specific username set.

source

pub fn add_default_username(self) -> Self

Add the default username to try.

The default username if read from the USER or USERNAME environment variable.

source

pub fn try_ssh_agent(self, enable: bool) -> Self

Configure if the SSH agent should be used for public key authentication.

source

pub fn add_ssh_key_from_file( self, private_key: impl Into<PathBuf>, password: impl Into<Option<String>> ) -> Self

Add a private key to use for public key authentication.

The key will be read from disk by git2, so it must still exist when the authentication is performed.

You can provide a password for decryption of the private key. If no password is provided and the Self::prompt_ssh_key_password() is enabled, the user will be prompted for the passphrase of encrypted keys. Note that currently only the OpenSSH private key format is supported for detecting that a key is encrypted.

A matching .pub file will also be read if it exists. For example, if you add the private key "foo/my_ssh_id", then "foo/my_ssh_id.pub" will be used too, if it exists.

source

pub fn add_default_ssh_keys(self) -> Self

Add all default SSH keys for public key authentication.

This will add all of the following files, if they exist:

  • "$HOME/.ssh/id_rsa"
  • "$HOME/.ssh/id_ecdsa"
  • "$HOME/.ssh/id_ecdsa_sk"
  • "$HOME/.ssh/id_ed25519"
  • "$HOME/.ssh/id_ed25519_sk"
  • "$HOME/.ssh/id_dsa"
source

pub fn prompt_ssh_key_password(self, enable: bool) -> Self

Prompt for passwords for encrypted SSH keys if needed.

By default, if an askpass helper is configured, it will be used for the prompts. Otherwise, the user will be prompted directly on the terminal of the current process. If there is also no terminal available, the prompt is skipped.

An askpass helper can be configured in the GIT_ASKPASS environment variable, the core.askPass configuration value or the SSH_ASKPASS environment variable.

You can override the prompt behaviour by calling Self::set_prompter().

source

pub fn credentials<'a>( &'a self, git_config: &'a Config ) -> impl 'a + FnMut(&str, Option<&str>, CredentialType) -> Result<Cred, Error>

Get the credentials callback to use for git2::Credentials.

Example: Fetch from a remote with authentication
use auth_git2::GitAuthenticator;

let auth = GitAuthenticator::default();
let git_config = repo.config()?;
let mut fetch_options = git2::FetchOptions::new();
let mut remote_callbacks = git2::RemoteCallbacks::new();

remote_callbacks.credentials(auth.credentials(&git_config));
fetch_options.remote_callbacks(remote_callbacks);

repo.find_remote("origin")?
    .fetch(&["main"], Some(&mut fetch_options), None)?;
source

pub fn clone_repo( &self, url: impl AsRef<str>, into: impl AsRef<Path> ) -> Result<Repository, Error>

Clone a repository using the git authenticator.

If you need more control over the clone options, use Self::credentials() with a git2::build::RepoBuilder.

source

pub fn fetch( &self, repo: &Repository, remote: &mut Remote<'_>, refspecs: &[&str], reflog_msg: Option<&str> ) -> Result<(), Error>

Fetch from a remote using the git authenticator.

If you need more control over the fetch options, use Self::credentials() with a git2::Remote::fetch.

source

pub fn push( &self, repo: &Repository, remote: &mut Remote<'_>, refspecs: &[&str] ) -> Result<(), Error>

Push to a remote using the git authenticator.

If you need more control over the push options, use Self::credentials() with a git2::Remote::push.

Trait Implementations§

source§

impl Clone for GitAuthenticator

source§

fn clone(&self) -> GitAuthenticator

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for GitAuthenticator

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for GitAuthenticator

source§

fn default() -> Self

Create a new authenticator with all supported options enabled.

This is the same as GitAuthenticator::new().

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.