Struct GitRepo

Source

pub struct GitRepo { /* private fields */ }

Expand description

A Git repository handle providing async operations via CLI commands.

Implementations§

Source §

impl GitRepo

Source

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

Source

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

Source

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

Source

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

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

Source

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

Source

pub fn is_git_repo(&self) -> bool

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

Source

pub fn path(&self) -> &Path

Returns the filesystem path to the Git repository.

§Return Value

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

List all worktrees associated with this repository.

Source

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

Prune stale worktree administrative files.

Source

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

Check if this repository is a bare repository.

Source

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

Source

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