Struct GitRepo 

pub struct GitRepo { /* private fields */ }

A Git repository handle providing async operations via CLI commands.

Implementations

impl GitRepo

pub fn new(path: impl AsRef<Path>) -> Self

Creates a new GitRepo instance for an existing local repository.

Arguments

• path - The filesystem path to the Git repository root directory

pub async fn clone(url: &str, target: impl AsRef<Path>) -> Result<Self>

Clones a Git repository from a remote URL to a local path.

Arguments

• url - The remote repository URL (HTTPS, SSH, or file://)
• target - The local directory where the repository will be cloned
• progress - Optional progress bar for user feedback

Errors

• The URL is invalid or unreachable
• Authentication fails
• The target directory already exists and is not empty
• Network connectivity issues
• Insufficient disk space

pub async fn fetch(&self, auth_url: Option<&str>) -> Result<()>

Fetches updates from the remote repository without modifying the working tree.

Arguments

• auth_url - Optional URL with authentication for private repositories
• progress - Optional progress bar for network operation feedback

Errors

• Network connectivity fails
• Authentication is rejected
• The remote repository is unavailable
• The local repository is in an invalid state

pub async fn checkout(&self, ref_name: &str) -> Result<()>

Checks out a specific Git reference (branch, tag, or commit hash).

Arguments

• ref_name - The Git reference to checkout (branch, tag, or commit)

Errors

• The reference doesn’t exist in the repository
• The repository is in an invalid state
• File system permissions prevent checkout
• The working directory is locked by another process

pub async fn list_tags(&self) -> Result<Vec<String>>

Lists all tags in the repository, sorted by Git’s default ordering.

Return Value

Errors

• The repository path doesn’t exist
• The directory is not a valid Git repository
• Git command execution fails
• File system permissions prevent access
• Lock conflicts persist after retry attempts

pub async fn get_remote_url(&self) -> Result<String>

Retrieves the URL of the remote ‘origin’ repository.

Return Value

• HTTPS: https://github.com/user/repo.git
• SSH: git@github.com:user/repo.git
• File: file:///path/to/repo.git

Errors

• No ‘origin’ remote is configured
• The repository is not a valid Git repository
• Git command execution fails
• File system access is denied

pub fn is_git_repo(&self) -> bool

Checks if the directory contains a valid Git repository.\n ///

pub fn path(&self) -> &Path

Returns the filesystem path to the Git repository.

Return Value

pub async fn verify_url(url: &str) -> Result<()>

Verifies that a Git repository URL is accessible without performing a full clone.

Arguments

• url - The repository URL to verify

Errors

• Network issues: DNS resolution, connectivity, timeouts
• Authentication failures: Invalid credentials, expired tokens
• Repository issues: Repository doesn’t exist, access denied
• Local path issues: File doesn’t exist (for file:// URLs)
• URL format issues: Malformed or unsupported URL schemes

pub async fn clone_bare(url: &str, target: impl AsRef<Path>) -> Result<Self>

Clone a repository as a bare repository (no working directory).

Arguments

• url - The remote repository URL
• target - The local directory where the bare repository will be stored
• progress - Optional progress bar for user feedback

Returns

pub async fn clone_bare_with_context( url: &str, target: impl AsRef<Path>, context: Option<&str>, ) -> Result<Self>

Clone a repository as a bare repository with logging context.

Arguments

• url - The remote repository URL
• target - The local directory where the bare repository will be stored
• progress - Optional progress bar for user feedback
• context - Optional context for logging (e.g., dependency name)

Returns

pub async fn create_worktree( &self, worktree_path: impl AsRef<Path>, reference: Option<&str>, ) -> Result<Self>

Create a new worktree from this repository.

Arguments

• worktree_path - The path where the worktree will be created
• reference - Optional Git reference (branch/tag/commit) to checkout

Returns

pub async fn create_worktree_with_context( &self, worktree_path: impl AsRef<Path>, reference: Option<&str>, context: Option<&str>, ) -> Result<Self>

Create a new worktree from this repository with logging context.

Arguments

• worktree_path - The path where the worktree will be created
• reference - Optional Git reference (branch/tag/commit) to checkout
• context - Optional context for logging (e.g., dependency name)

Returns

pub async fn remove_worktree( &self, worktree_path: impl AsRef<Path>, ) -> Result<()>

Remove a worktree associated with this repository.

Arguments

• worktree_path - The path to the worktree to remove

pub async fn list_worktrees(&self) -> Result<Vec<PathBuf>>

List all worktrees associated with this repository.

pub async fn prune_worktrees(&self) -> Result<()>

Prune stale worktree administrative files.

pub async fn is_bare(&self) -> Result<bool>

Check if this repository is a bare repository.

pub async fn get_current_commit(&self) -> Result<String>

Get the current commit SHA of the repository.

Returns

Errors

• The repository is not valid
• HEAD is not pointing to a valid commit
• Git command fails

pub async fn resolve_refs_batch( &self, refs: &[&str], ) -> Result<HashMap<String, Option<String>>>

Batch resolve multiple refs to SHAs in a single git process.

Uses git rev-parse <ref1> <ref2> ... to resolve all refs at once, reducing process spawn overhead from O(n) to O(1). This is significantly faster for Windows where process spawning has high overhead.

Arguments

• refs - Slice of ref specifications to resolve

Returns

HashMap mapping each input ref to its resolved SHA (or None if not found)

Performance

• Single process for all refs vs one per ref
• Reduces 100 refs from ~5-10 seconds to ~0.5 seconds on Windows

Examples

use agpm_cli::git::GitRepo;

let repo = GitRepo::new("/path/to/repo");
let refs = vec!["v1.0.0", "main", "abc1234"];
let results = repo.resolve_refs_batch(&refs).await?;

for (ref_name, sha) in results {
    if let Some(sha) = sha {
        println!("{} -> {}", ref_name, sha);
    } else {
        println!("{} not found", ref_name);
    }
}

pub async fn resolve_to_sha(&self, ref_spec: Option<&str>) -> Result<String>

Resolves a Git reference (tag, branch, commit) to its full SHA-1 hash.

Arguments

• ref_spec - The Git reference to resolve (tag, branch, short/full SHA, or None for HEAD)

Returns

Errors

• The reference doesn’t exist in the repository
• The repository is invalid or corrupted
• Git command execution fails

pub async fn get_current_branch(&self) -> Result<String>

pub async fn get_default_branch(&self) -> Result<String>

Gets the default branch name for the repository.

Returns

Errors

• Git commands fail with non-recoverable errors
• Lock conflicts occur (propagated for caller to retry)
• Default branch cannot be determined

Trait Implementations

impl Clone for GitRepo

fn clone(&self) -> GitRepo

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for GitRepo

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

Formats the value using the given formatter.