Skip to main content

RepositoryHandle

Struct RepositoryHandle 

Source
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>

Source

pub fn id(&self) -> &RepoId

Get the repository ID

Source

pub fn metadata(&self) -> Git2DBResult<&TrackedRepository>

Get the repository metadata

Source

pub fn name(&self) -> Git2DBResult<Option<&str>>

Get the repository name (if set)

Source

pub fn worktree(&self) -> Git2DBResult<&Path>

Get the worktree path where files are checked out

Source

pub fn url(&self) -> Git2DBResult<&str>

Get the primary URL

Source

pub fn tracking_ref(&self) -> Git2DBResult<&GitRef>

Get the tracking ref (branch, tag, or commit)

Source

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.

Source

pub fn current_oid(&self) -> Git2DBResult<Option<Oid>>

Get the current OID (commit hash)

Source

pub fn open_repo(&self) -> Git2DBResult<Repository>

Open the underlying git repository

Source

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

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?;
Source

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

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
Source

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
Source

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
Source

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
Source

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

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

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?;
Source

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

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?;
Source

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

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

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.

Source

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

Source

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 checkout
  • checkout_paths - Path prefixes to materialize (e.g., ["backends/cuda130/", "manifest.toml"])
Source

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§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T> Any for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

§

fn type_name(&self) -> &'static str

§

impl<T> AnySync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send> ⓘ

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T, W> HasTypeWitness<W> for T
where W: MakeTypeWitness<Arg = T>, T: ?Sized,

§

const WITNESS: W = W::MAKE

A constant of the type witness
§

impl<T> Identity for T
where T: ?Sized,

§

const TYPE_EQ: TypeEq<T, <T as Identity>::Type> = TypeEq::NEW

Proof that Self is the same type as Self::Type, provides methods for casting between Self and Self::Type.
§

type Type = T

The same type as Self, used to emulate type equality bounds (T == U) with associated type equality constraints (T: Identity<Type = U>).
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,