Struct auth_git2::GitAuthenticator

pub struct GitAuthenticator { /* private fields */ }

Configurable authenticator to use with git2.

Implementations

impl GitAuthenticator

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)

pub fn new_empty() -> Self

Create a new authenticator with all authentication options disabled.

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.

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.

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().

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().

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.

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.

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

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

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.

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"

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().

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)?;

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.

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 git2::Remote::fetch().

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

Download and index the packfile from a remote using the git authenticator.

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

This function does not update the remote tracking branches. Consider using Self::fetch() if that is what you want.

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 git2::Remote::push().

Trait Implementations

impl Clone for GitAuthenticator

fn clone(&self) -> GitAuthenticator

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for GitAuthenticator

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

Formats the value using the given formatter.

impl Default for GitAuthenticator

fn default() -> Self

Create a new authenticator with all supported options enabled.

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