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

Set to 0 to disable.

If an askpass helper is configured, it will be used. Otherwise, the user will be prompted directly on the main terminal of the process.

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

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

Add a username to try for authentication.

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 the username for all domains without 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 user for public key authentication.

pub fn add_ssh_key_from_file( self, private_key: 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, a password prompt will be shown on the terminal if needed to ask for the encryption key. Note that we currently only support the OpenSSH private key format 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.

If an askpass helper is configured, it will be used. Otherwise, the user will be prompted directly on the main terminal of the process.

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

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

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

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

Returns the “default value” for a type.