auth-git2

Easy authentication for git2.

Authentication with git2 can be quite difficult to implement correctly. This crate aims to make it easy.

Features

• Has a small dependency tree.
• Can query the SSH agent for private key authentication.
• Can get SSH keys from files.
• Can prompt the user for passwords for encrypted SSH keys.
  • Only supported for OpenSSH private keys.
• Can query the git credential helper for usernames and passwords.
• Can use pre-provided plain usernames and passwords.
• Can prompt the user for credentials as a last resort.
• Allows you to fully customize all user prompts.

The default user prompts will:

• Use the git askpass helper if it is configured.
• Fall back to prompting the user on the terminal if there is no askpass program configured.
• Skip the prompt if there is also no terminal available for the process.

Creating an authenticator and enabling authentication mechanisms

You can create use GitAuthenticator::new() (or default()) to create a ready-to-use authenticator. Using one of these constructors will enable all supported authentication mechanisms. You can still add more private key files from non-default locations to try if desired.

You can also use GitAuthenticator::new_empty() to create an authenticator without any authentication mechanism enabled. Then you can selectively enable authentication mechanisms and add custom private key files.

Using the authenticator

For the most flexibility, you can get a git2::Credentials callback using the GitAuthenticator::credentials() function. You can use it with any git operation that requires authentication. Doing this gives you full control to set other options and callbacks for the git operation.

If you don't need to set other options or callbacks, you can also use the convenience functions on GitAuthenticator. They wrap git operations with the credentials callback set:

• GitAuthenticator::clone_repo()
• GitAuthenticator::fetch()
• GitAuthenticator::download()
• GitAuthenticator::push()

Customizing user prompts

All user prompts can be fully customized by calling GitAuthenticator::set_prompter(). This allows you to override the way that the user is prompted for credentials or passphrases.

If you have a fancy user interface, you can use a custom prompter to integrate the prompts with your user interface.

Example: Clone a repository

use auth_git2::GitAuthenticator;
use std::path::Path;

let url = "https://github.com/de-vri-es/auth-git2-rs";
let into = Path::new("/tmp/dyfhxoaj/auth-git2-rs");

let auth = GitAuthenticator::default();
let mut repo = auth.clone_repo(url, into);

Example: Clone a repository with full control over fetch options

use auth_git2::GitAuthenticator;
use std::path::Path;

let auth = GitAuthenticator::default();
let git_config = git2::Config::open_default()?;
let mut repo_builder = git2::build::RepoBuilder::new();
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_builder.fetch_options(fetch_options);

let url = "https://github.com/de-vri-es/auth-git2-rs";
let into = Path::new("/tmp/dyfhxoaj/auth-git2-rs");
let mut repo = repo_builder.clone(url, into);