pub struct RepositoryHandle<'a> { /* private fields */ }Expand description
Handle to a tracked repository
Provides git-native operations on a repository tracked in the registry. This handle borrows from the Git2DB registry and provides a scoped interface.
Implementations§
Source§impl<'a> RepositoryHandle<'a>
impl<'a> RepositoryHandle<'a>
Sourcepub fn metadata(&self) -> Git2DBResult<&TrackedRepository>
pub fn metadata(&self) -> Git2DBResult<&TrackedRepository>
Get the repository metadata
Sourcepub fn name(&self) -> Git2DBResult<Option<&str>>
pub fn name(&self) -> Git2DBResult<Option<&str>>
Get the repository name (if set)
Sourcepub fn worktree(&self) -> Git2DBResult<&Path>
pub fn worktree(&self) -> Git2DBResult<&Path>
Get the worktree path where files are checked out
Sourcepub fn url(&self) -> Git2DBResult<&str>
pub fn url(&self) -> Git2DBResult<&str>
Get the primary URL
Sourcepub fn tracking_ref(&self) -> Git2DBResult<&GitRef>
pub fn tracking_ref(&self) -> Git2DBResult<&GitRef>
Get the tracking ref (branch, tag, or commit)
Sourcepub async fn resolve_worktree_path(&self) -> Git2DBResult<PathBuf>
pub async fn resolve_worktree_path(&self) -> Git2DBResult<PathBuf>
Resolve a working tree path suitable for git operations.
For bare repositories (e.g. cloned models stored as name.git),
worktree() returns the bare repo path, which cannot be used for
operations requiring a working tree (status, staging, etc.).
This method finds the actual worktree for the tracking ref.
Sourcepub fn current_oid(&self) -> Git2DBResult<Option<Oid>>
pub fn current_oid(&self) -> Git2DBResult<Option<Oid>>
Get the current OID (commit hash)
Sourcepub fn open_repo(&self) -> Git2DBResult<Repository>
pub fn open_repo(&self) -> Git2DBResult<Repository>
Open the underlying git repository
Sourcepub fn remote(&self) -> RemoteManager<'a>
pub fn remote(&self) -> RemoteManager<'a>
Checkout a specific reference (branch, tag, or commit)
Accepts strings, GitRef enums, or direct Oids for type safety.
§Examples
// String reference
repo.checkout("main").await?;
// Explicit GitRef
repo.checkout(git2db::GitRef::Branch("develop".into())).await?;
// Direct Oid (type-safe)
let oid = git2::Oid::from_str("abc123...")?;
repo.checkout(oid).await?;Get remote manager for this repository
Provides git-native remote operations like git remote.
§Examples
// Add remotes
repo.remote().add("origin", "https://github.com/user/repo.git").await?;
repo.remote().add("p2p", "gittorrent://peer/repo").await?;
// List remotes
for remote in repo.remote().list().await? {
println!("{}: {}", remote.name, remote.url);
}Sourcepub fn branch(&self) -> BranchManager<'a>
pub fn branch(&self) -> BranchManager<'a>
Get branch manager for this repository
Provides git-native branch operations like git branch.
§Examples
// List branches
for branch in repo.branch().list().await? {
println!("{} {}", if branch.is_head { "*" } else { " " }, branch.name);
}
// Get current branch
if let Some(current) = repo.branch().current().await? {
println!("On branch: {}", current.name);
}
// Create and checkout
repo.branch().create("feature", Some("main")).await?;
repo.branch().checkout("feature").await?;Sourcepub fn staging(&self) -> StageManager<'a>
pub fn staging(&self) -> StageManager<'a>
Get staging area manager for this repository
Provides git-native staging operations like git add and git rm.
§Examples
// Add files to staging area
repo.staging().add("src/main.rs").await?;
repo.staging().add_all().await?;
// Check staged files
for file in repo.staging().staged_files().await? {
println!("Staged: {:?}", file.path);
}Sourcepub async fn commit(&self, message: &str) -> Git2DBResult<Oid>
pub async fn commit(&self, message: &str) -> Git2DBResult<Oid>
Commit staged changes with default signature
Similar to git commit -m "<message>"
This method commits all staged changes using the default signature from GitManager configuration. The signature is created from git config or the Git2DB configuration.
§Examples
// Stage changes
repo.staging().add_all().await?;
// Commit with default signature
let oid = repo.commit("Update documentation").await?;
println!("Committed: {}", oid);§Errors
This method will return an error if:
- There are no staged changes
- The repository cannot be opened
- The signature cannot be created (check git config)
- The commit cannot be created
Sourcepub async fn commit_as(
&self,
signature: &Signature<'_>,
message: &str,
) -> Git2DBResult<Oid>
pub async fn commit_as( &self, signature: &Signature<'_>, message: &str, ) -> Git2DBResult<Oid>
Commit staged changes with a specific author/committer
Similar to git commit -m "<message>" --author="<name> <email>"
This method commits all staged changes using the provided signature. Both author and committer will be set to the provided signature.
§Examples
use git2::Signature;
// Stage changes
repo.staging().add("README.md").await?;
// Create custom signature
let sig = Signature::now("Alice", "alice@example.com")?;
// Commit as specific user
let oid = repo.commit_as(&sig, "Update docs").await?;§Errors
This method will return an error if:
- There are no staged changes
- The repository cannot be opened
- The commit cannot be created
Sourcepub async fn status(&self) -> Git2DBResult<RepositoryStatus>
pub async fn status(&self) -> Git2DBResult<RepositoryStatus>
Get repository status (branch, dirty files, etc.)
Similar to git status but returns structured data instead of printing.
§Examples
let status = repo.status().await?;
println!("Branch: {:?}", status.branch);
println!("Clean: {}", status.is_clean);
if !status.is_clean {
for file in &status.modified_files {
println!("Modified: {}", file.display());
}
}§Errors
This method will return an error if:
- The repository cannot be opened
- The status cannot be retrieved
Sourcepub async fn merge(
&self,
source: &str,
message: Option<&str>,
) -> Git2DBResult<Oid>
pub async fn merge( &self, source: &str, message: Option<&str>, ) -> Git2DBResult<Oid>
Merge a branch or reference into the current HEAD
Similar to git merge <source>
§Arguments
source- The branch or ref to merge (e.g., “feature-branch”, “refs/tags/v1.0”)message- Optional commit message (defaults to “Merge branch ‘source’”)
§Examples
// Merge a branch
let merge_oid = repo.merge("feature-branch", None).await?;
// Merge with custom message
let merge_oid = repo.merge("feature-branch", Some("Merge feature-branch")).await?;§Errors
This method will return an error if:
- The repository cannot be opened
- The source ref cannot be found
- Merge conflicts are detected
- The merge commit cannot be created
Sourcepub fn list_refs(&self) -> Git2DBResult<Vec<(String, Oid)>>
pub fn list_refs(&self) -> Git2DBResult<Vec<(String, Oid)>>
List all references (branches and tags) with their OIDs
Similar to git show-ref
§Examples
for (name, oid) in repo.list_refs()? {
println!("{}: {}", name, oid);
}Sourcepub fn default_branch(&self) -> Git2DBResult<String>
pub fn default_branch(&self) -> Git2DBResult<String>
Get the default branch name
Similar to git symbolic-ref --short HEAD or detecting main/master
§Examples
let default_branch = repo.default_branch()?;
println!("Default branch: {}", default_branch);Sourcepub async fn resolve_git_ref(&self, git_ref: &GitRef) -> Git2DBResult<Oid>
pub async fn resolve_git_ref(&self, git_ref: &GitRef) -> Git2DBResult<Oid>
Resolve a GitRef to an OID
This is a general-purpose method that can resolve any type of git reference to its commit OID.
§Examples
use git2db::GitRef;
// Resolve branch
let oid = repo.resolve_git_ref(&GitRef::Branch("main".into())).await?;
// Resolve tag
let oid = repo.resolve_git_ref(&GitRef::Tag("v1.0.0".into())).await?;
// Resolve commit (returns same OID)
let oid = repo.resolve_git_ref(&GitRef::Commit(oid)).await?;Sourcepub fn ref_info(&self, ref_name: &str) -> Git2DBResult<Option<(String, Oid)>>
pub fn ref_info(&self, ref_name: &str) -> Git2DBResult<Option<(String, Oid)>>
Get information about a specific reference
Returns the reference name and target OID if it exists.
§Examples
if let Some((name, oid)) = repo.ref_info("main")? {
println!("Branch {}: {}", name, oid);
}Sourcepub async fn resolve_revspec(&self, spec: &str) -> Git2DBResult<Oid>
pub async fn resolve_revspec(&self, spec: &str) -> Git2DBResult<Oid>
Resolve a revspec string to an OID
Similar to git rev-parse
§Examples
// Resolve complex revspecs
let oid = repo.resolve_revspec("HEAD~3").await?;
let oid = repo.resolve_revspec("main@{yesterday}").await?;Sourcepub async fn get_worktrees(&self) -> Git2DBResult<Vec<WorktreeHandle>>
pub async fn get_worktrees(&self) -> Git2DBResult<Vec<WorktreeHandle>>
Get all worktrees managed by the storage driver for this repository
Returns all worktrees that were created using storage drivers for this repository. This is useful for discovering existing worktrees managed by overlay2, vfs, etc.
§Examples
// List all worktrees for this repository
for worktree in repo.get_worktrees().await? {
println!("Worktree: {} (driver: {})", worktree.path().display(), worktree.driver_name());
}Sourcepub async fn get_worktree(
&self,
branch: &str,
) -> Git2DBResult<Option<WorktreeHandle>>
pub async fn get_worktree( &self, branch: &str, ) -> Git2DBResult<Option<WorktreeHandle>>
Get a specific worktree by branch name
Returns the worktree if it exists and is managed by the storage driver. This is useful for checking if a specific branch worktree exists.
§Examples
// Check if a worktree for a specific branch exists
if let Some(worktree) = repo.get_worktree("feature-branch").await? {
println!("Found worktree at: {}", worktree.path().display());
}Sourcepub async fn fetch_lfs_files(repo_path: &Path) -> Git2DBResult<()>
pub async fn fetch_lfs_files(repo_path: &Path) -> Git2DBResult<()>
Create a new worktree using the configured storage driver
This creates a new worktree using the storage driver selected in the configuration. On Linux, this will typically use overlay2 for ~80% space savings, while on other platforms it will use vfs (plain git worktrees).
The worktree will be created at the specified path and checked out to the given branch/ref.
§Examples
// Create a worktree for a feature branch with overlay2 optimization
let worktree = repo.create_worktree("/tmp/feature-branch", "feature-branch").await?;
println!("Created worktree at: {}", worktree.path().display());
// Create worktree at custom path
let worktree = repo.create_worktree("/tmp/custom-path", "main").await?;Fetch LFS files for the worktree
This function tries XET first if initialized (faster for XET-enabled repos),
then falls back to git lfs pull if XET fails or isn’t available.
Sourcepub async fn fetch_lfs_files_with_progress(
repo_path: &Path,
progress: Option<Arc<dyn ProgressReporter>>,
) -> Git2DBResult<()>
pub async fn fetch_lfs_files_with_progress( repo_path: &Path, progress: Option<Arc<dyn ProgressReporter>>, ) -> Git2DBResult<()>
Fetch LFS files for a worktree with progress reporting
Sourcepub async fn create_filtered_worktree(
&self,
worktree_path: &Path,
branch: &str,
checkout_paths: Vec<String>,
) -> Git2DBResult<WorktreeHandle>
pub async fn create_filtered_worktree( &self, worktree_path: &Path, branch: &str, checkout_paths: Vec<String>, ) -> Git2DBResult<WorktreeHandle>
Create a worktree with pathspec-filtered checkout.
Only files matching checkout_paths prefixes are materialized.
Excluded entries get skip-worktree index bits to prevent re-materialization.
§Arguments
worktree_path- Where to create the worktree (empty = auto-derive)branch- Git ref to checkoutcheckout_paths- Path prefixes to materialize (e.g.,["backends/cuda130/", "manifest.toml"])
pub async fn create_worktree( &self, worktree_path: &Path, branch: &str, ) -> Git2DBResult<WorktreeHandle>
Auto Trait Implementations§
impl<'a> Freeze for RepositoryHandle<'a>
impl<'a> !RefUnwindSafe for RepositoryHandle<'a>
impl<'a> Send for RepositoryHandle<'a>
impl<'a> Sync for RepositoryHandle<'a>
impl<'a> Unpin for RepositoryHandle<'a>
impl<'a> UnsafeUnpin for RepositoryHandle<'a>
impl<'a> !UnwindSafe for RepositoryHandle<'a>
Blanket Implementations§
§impl<T> AnySync for T
impl<T> AnySync for T
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Identity for Twhere
T: ?Sized,
impl<T> Identity for Twhere
T: ?Sized,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more