Struct Repository 

pub struct Repository { /* private fields */ }

An ergonomic handle to a git repository.

Construct one with Repository::open (when you already know the git directory), Repository::discover (to search upward from a working-tree path), or Repository::init / Repository::init_bare (to create a new repository). The handle is cheap to clone and shares a session-scoped object database (Repository::objects) whose read caches survive across calls until Repository::refresh_objects (automatic after fetch / pack copy).

Implementations

impl Repository

pub fn capabilities(&self) -> RepositoryCapabilities

Report what this repository and the linked engine support.

pub fn transport_capabilities(&self) -> TransportCapabilities

Transport capabilities when the remote feature is enabled.

impl Repository

pub fn config_with_sources(&self) -> Result<ConfigSnapshot, ConfigEditError>

Return the effective config as a source-attributed flat stream.

pub fn config_stack( &self, options: ConfigStackOptions, ) -> Result<ConfigStackView, ConfigEditError>

Build an effective Git config stack with editable-origin metadata.

pub fn remote_config_with_sources( &self, ) -> Result<RemoteConfigSnapshot, ConfigEditError>

Return configured remotes with physical source and editability metadata.

pub fn plan_config_edit( &self, key: &str, scope: ConfigEditScope, ) -> Result<ConfigEditPlan, ConfigEditError>

Plan the physical config file that should be edited for key and scope.

The returned plan has no operations; callers may add operations directly or use Repository::plan_config_set / Repository::plan_config_unset.

pub fn plan_config_set( &self, key: &str, value: impl Into<String>, scope: ConfigEditScope, ) -> Result<ConfigEditPlan, ConfigEditError>

Plan a set operation for key.

pub fn plan_config_unset( &self, key: &str, scope: ConfigEditScope, ) -> Result<ConfigEditPlan, ConfigEditError>

Plan an unset operation for key.

pub fn plan_remote_set( &self, set: RemoteConfigSet, scope: ConfigEditScope, ) -> Result<ConfigEditPlan, ConfigEditError>

Plan a whole-section replacement for [remote "<name>"].

The applied edit removes every matching remote section from the selected physical config file and appends one canonical replacement section.

pub fn plan_remote_remove( &self, remove: RemoteConfigRemove, scope: ConfigEditScope, ) -> Result<ConfigEditPlan, ConfigEditError>

Plan removal of all [remote "<name>"] sections in the selected file.

pub fn apply_config_edit_plan( &self, plan: ConfigEditPlan, ) -> Result<(), ConfigEditError>

Apply a config edit plan through <target>.lock and atomic rename.

impl Repository

pub fn diff_name_status( &self, left: &ObjectId, right: &ObjectId, ) -> Result<Vec<NameStatusEntry>>

Compare two tree objects and return name-status entries (git diff --name-status).

impl Repository

pub fn read_index(&self) -> Result<Index, IndexError>

Read this repository’s index (.git/index or $GIT_INDEX_FILE).

pub fn index_stat_probes(&self) -> Result<IndexStatProbeCache, IndexError>

Read this repository’s index once and return reusable stat probes.

This is the bulk form of IndexStatProbe::from_repository_index. Embedders that verify many worktree paths should prefer this method so .git/index is parsed once instead of once per path.

pub fn write_index( &self, index: &Index, options: IndexWriteOptions, ) -> Result<(), IndexWriteError>

Write this repository’s index through index.lock and an atomic rename.

pub fn write_index_with_result( &self, index: &Index, options: IndexWriteOptions, ) -> Result<IndexWriteResult, IndexWriteError>

Write this repository’s index through index.lock and an atomic rename, returning the post-write index metadata needed for racy-git probes.

impl Repository

pub fn notes_ref(&self, override_ref: Option<&str>) -> Result<NotesRef>

Resolve the active notes ref (honours GIT_NOTES_REF and core.notesRef).

pub fn list_notes(&self, notes_ref: &NotesRef) -> Result<Vec<Note>>

List every note on notes_ref.

pub fn iter_notes(&self, notes_ref: &NotesRef) -> Result<NotesIter>

Stream notes from notes_ref without loading the full list.

pub fn read_note_for( &self, notes_ref: &NotesRef, annotated: &ObjectId, ) -> Result<Option<ObjectId>>

Return the note blob oid for annotated, if any (fanout-aware lookup).

pub fn read_note( &self, notes_ref: &NotesRef, annotated: &ObjectId, ) -> Result<Option<ObjectId>>

Return the note blob oid for annotated, if any.

pub fn read_note_bytes( &self, notes_ref: &NotesRef, annotated: &ObjectId, ) -> Result<Option<Vec<u8>>>

Return decoded note bytes for annotated, if a note exists.

pub fn write_notes( &self, notes_ref: &NotesRef, notes: &[Note], message: &str, identity: &NotesCommitIdentity, ) -> Result<()>

Rewrite the notes tree and advance notes_ref to a new commit.

impl Repository

pub fn objects(&self) -> Arc<FileObjectDatabase>

Session-scoped object database handle (shared across clones of this repo).

pub fn objects_mut(&self) -> FileObjectDatabase

Writable object-store view sharing this session’s read caches.

pub fn blobs(&self) -> BlobStore<'_>

Blob reads with a single boundary for future lazy hydration support.

pub fn refresh_objects(&self)

Invalidate pack/decoded read caches after fetch, push, or pack install.

pub fn read_object_header( &self, oid: &ObjectId, ) -> Result<Option<(ObjectType, u64)>>

Object type and size without decoding the body (git cat-file --batch-check).

pub fn load_object(&self, oid: &ObjectId) -> Result<LoadedObject>

Load an object for zero-copy parsing via LoadedObject.

Keep the returned value alive while using LoadedObject::commit_ref.

impl Repository

pub fn reachable_pack_plan(&self) -> ReachablePackPlanBuilder<'_>

Start planning a reachable pack from this repository.

impl Repository

pub fn set_head_symref( &self, target: impl AsRef<str>, options: HeadUpdateOptions, ) -> RefChangeResult<()>

Attach HEAD to target through the ref backend.

target must be a valid symbolic ref target (for example refs/heads/main). Linked worktrees are handled by Repository::references, so a linked worktree’s own HEAD is updated while shared branch refs remain in the common directory.

pub fn delete_ref(&self, delete: DeleteRef) -> Result<(), RefDeleteError>

Delete a direct ref only if the optional old-oid precondition still holds.

The ref is locked before its current value is read, stale expected values leave the ref untouched, and packed refs are rewritten through packed-refs.lock.

pub fn apply_ref_changes( &self, changes: &[RefChange], ) -> Result<(), RefConflict>

Apply changes atomically via the on-disk ref transaction backend.

All updates succeed together or none take effect. A failed compare-and-swap returns RefConflict rather than a generic GitError::Transaction.

pub fn apply_ref_batch( &self, changes: &[RefBatchChange], ) -> Result<(), RefConflict>

Apply a mixed create/update/delete batch through the ref backend.

The public API is stable for callers that need exact ref plans. Duplicate names reject before opening the backend transaction; leases are enforced by the backend while refs are locked.

pub fn update_branch_checked_out_as_head( &self, branch: &str, new_oid: ObjectId, options: RefUpdateOptions, ) -> RefChangeResult<()>

Advance the currently checked-out branch and mirror Git porcelain’s direct HEAD reflog entry.

branch may be either a short branch name (main) or its full refs/heads/main name. HEAD must be symbolically attached to that branch. The branch update is checked against the object id read for the reflog entry, even when no explicit expect_old is supplied, so a race cannot leave a misleading old/new reflog pair behind.

impl Repository

pub fn load_repo_config(&self) -> Result<GitConfig>

Read the repository config file (<common_dir>/config).

Returns an empty GitConfig when the file is absent, matching Repository::config.

pub fn save_repo_config(&self, config: &GitConfig) -> Result<()>

Write config to <common_dir>/config using canonical serialization.

Comments and original whitespace are not preserved (see GitConfig::to_preserved_bytes when the config was loaded from disk; falls back to canonical form for programmatic configs).

pub fn add_remote(&self, name: &str, url: &str) -> Result<()>

Add [remote "<name>"] with url and the default fetch refspec.

pub fn remove_remote(&self, name: &str) -> Result<()>

Remove [remote "<name>"] and dependent branch configuration.

pub fn set_remote_url(&self, name: &str, url: &str) -> Result<()>

Set the sole fetch URL for [remote "<name>"] (git remote set-url).

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

Initialize a bare mirror repository at path.

The resulting repository matches git clone --mirror defaults for a bare destination: [remote "origin"] carries fetch = +refs/*:refs/* and mirror = true. No url is written; callers typically follow with Repository::set_remote_url or Repository::add_remote.

impl Repository

pub fn rev_graph(&self) -> RevGraph<'_>

Build a repository-scoped revision graph helper.

impl Repository

pub fn status_plan(&self) -> StatusPlanBuilder<'_>

Start a reusable status/index work plan.

impl Repository

pub fn remote(&self, remote: impl Into<String>) -> Result<RemoteContext>

Open a RemoteContext for remote using this repository’s config.

pub fn fetch( &self, remote: impl Into<String>, refspecs: &[String], options: FetchOptions, credentials: &mut dyn CredentialProvider, progress: &mut dyn ProgressSink, ) -> Result<FetchOutcome>

Fetch from remote (name or URL), installing objects and updating refs.

pub fn push( &self, remote: impl Into<String>, refspecs: &[String], options: PushOptions, credentials: &mut dyn CredentialProvider, progress: &mut dyn ProgressSink, ) -> Result<PushOutcome>

Push refspecs to remote (name or URL).

pub fn push_actions( &self, remote: impl Into<String>, plan: PushActionPlan, credentials: &mut dyn CredentialProvider, progress: &mut dyn ProgressSink, ) -> Result<PushOutcome>

Push a caller-authored exact old/new/delete plan to remote.

pub fn ls_remote( &self, remote: impl Into<String>, filter: LsRemoteFilter, matches: &dyn Fn(&str) -> bool, credentials: &mut dyn CredentialProvider, ) -> Result<Vec<LsRemoteRecord>>

List refs advertised by remote (name or URL).

impl Repository

pub fn open(git_dir: impl AsRef<Path>) -> Result<Self>

Open the repository whose git directory is exactly git_dir.

git_dir must be a git directory itself (the .git directory of a non-bare repo, or the top level of a bare repo), not a working tree. Use Repository::discover to search upward from a working-tree path.

The path may be a .git file (a gitlink, as used by linked worktrees and submodules); its gitdir: target is followed.

pub fn open_with(path: impl AsRef<Path>, options: OpenOptions) -> Result<Self>

Open a repository with explicit discovery and bare-worktree policy.

Use OpenOptions::new().exact_path(true).bare(true) for scratch bare directories where silently discovering a parent checkout would be wrong.

pub fn open_exact_bare(git_dir: impl AsRef<Path>) -> Result<Self>

Open exactly git_dir as a bare repository, never discovering a parent.

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

Discover the repository containing path by walking up the directory tree, mirroring git’s own discovery (.git directory, .git gitlink file, or a bare repository at an ancestor).

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

Initialize a new non-bare repository rooted at path (creating its .git directory) and return a handle to it. Re-initializing an existing repository is a no-op on already-present files, matching git init.

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

Initialize a new bare repository at path (the directory becomes the git directory itself) and return a handle to it.

pub fn init_with_format( path: impl AsRef<Path>, format: ObjectFormat, bare: bool, ) -> Result<Self>

Initialize a new repository at path with an explicit object format and bare-ness.

pub fn git_dir(&self) -> &Path

The repository’s git directory (the .git directory of a non-bare repo, or the top level of a bare repo).

pub fn common_dir(&self) -> &Path

The common directory shared between linked worktrees. For a single worktree this equals Repository::git_dir; for a linked worktree it is the main repository’s git directory (as recorded in commondir).

pub fn workdir(&self) -> Option<PathBuf>

The working-tree root, or None for a bare repository.

Resolution follows git’s repository-intrinsic rules: a core.worktree override, then a linked worktree’s recorded location, then the parent of the .git directory for an ordinary checkout. It does not consult the process-level GIT_WORK_TREE/GIT_DIR overrides (those belong to a CLI front-end, not a library handle). A working tree that is configured but cannot be resolved on disk (e.g. a core.worktree pointing at a missing path) is reported as None rather than erroring.

pub fn is_shallow(&self) -> bool

Whether this repository is shallow — created or fetched with a depth limit, so a shallow file records its grafted history boundaries.

pub fn short_status(&self) -> Result<Vec<ShortStatusEntry>>

Return short-status entries for this repository’s working tree using sley’s default status options.

Bare repositories have no working tree and return GitError::Unsupported.

pub fn stream_short_status<F>(&self, emit: F) -> Result<()>

where F: for<'a> FnMut(ShortStatusRow<'a>) -> Result<StreamControl>,

Stream short-status entries for this repository’s working tree using sley’s default status options.

Bare repositories have no working tree and return GitError::Unsupported.

pub fn short_status_with_options( &self, options: ShortStatusOptions, ) -> Result<Vec<ShortStatusEntry>>

Return short-status entries for this repository’s working tree.

This facade collects entries from sley_worktree::stream_short_status_with_options.

pub fn stream_short_status_with_options<F>( &self, options: ShortStatusOptions, emit: F, ) -> Result<()>

where F: for<'a> FnMut(ShortStatusRow<'a>) -> Result<StreamControl>,

Stream short-status entries for this repository’s working tree.

pub fn short_status_count_with_options( &self, options: ShortStatusOptions, ) -> Result<usize>

Count short-status entries for this repository’s working tree.

pub fn worktree_entry_state( &self, path: impl AsRef<Path>, expected_oid: &ObjectId, expected_mode: u32, index_probe: Option<&IndexStatProbe>, ) -> Result<WorktreeEntryState>

Compare one tracked entry to this repository’s worktree, using the same racy-clean/stat-cache rules as Repository::short_status_with_options.

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

The names of the configured remotes ([remote "<name>"] sections), sorted alphabetically with duplicates collapsed — the order git remote lists them in.

Remotes are read from the effective configuration (see Repository::config_snapshot), so a remote defined in an included file is included.

pub fn object_format(&self) -> ObjectFormat

The repository’s object format (sha1 or sha256), read from extensions.objectformat.

pub fn references(&self) -> FileRefStore

The reference store for this repository (loose refs, packed-refs, and reflogs), scoped to this worktree’s git directory.

pub fn config(&self) -> Result<GitConfig>

The repository-level configuration (<common_dir>/config).

Returns an empty GitConfig if the file is missing, matching the way git treats an absent repository config.

pub fn config_snapshot(&self) -> Result<GitConfig>

The effective configuration, merging the system, global, and repository config files in git’s precedence order (repository wins, then global, then system) with include/includeIf directives resolved.

Unlike Repository::config (repository file only), this is what a caller wanting git-equivalent lookups — e.g. resolving user.name from ~/.gitconfig — should use. File discovery honours $GIT_CONFIG_SYSTEM, $GIT_CONFIG_GLOBAL, $XDG_CONFIG_HOME, $HOME, and $GIT_CONFIG_NOSYSTEM exactly as git does; missing files are skipped.

This does not layer in -c/GIT_CONFIG_COUNT command-line overrides, which are process-level and higher precedence than any file.

pub fn config_string(&self, section: &str, key: &str) -> Result<Option<String>>

Look up section.key in the effective config (see Repository::config_snapshot), returning the highest-precedence value or None if unset. For a subsectioned key use Repository::config_string_subsection.

pub fn config_string_subsection( &self, section: &str, subsection: Option<&str>, key: &str, ) -> Result<Option<String>>

Look up section.subsection.key in the effective config, honouring subsections (e.g. remote.origin.url). subsection of None reads the bare section.

pub fn head(&self) -> Result<Head>

Resolve HEAD: its symbolic branch target (if any) and the commit it points at (if the branch exists).

pub fn head_state(&self) -> Result<HeadState>

Inspect HEAD without collapsing attached, detached, unborn, and missing states into Option fields.

pub fn find_reference(&self, name: &str) -> Result<Option<Reference>>

Look up a reference by full name (e.g. refs/heads/main, refs/tags/v1, or HEAD), returning None if it does not exist.

pub fn reference_exists(&self, name: &str) -> Result<bool>

Return whether name exists in the ref backend without resolving its target or reading the object it names.

pub fn require_reference(&self, name: &str) -> Result<Reference>

Look up a reference that must exist.

pub fn peel_to_object_oid(&self, oid: ObjectId) -> Result<ObjectId>

Peel annotated tags until the referenced non-tag object is reached.

This does not resolve symbolic refs. Use Reference::direct_target or Repository::head first so the call site is explicit about symbolic reference resolution versus object graph peeling.

pub fn peel_to_commit_oid(&self, oid: ObjectId) -> Result<ObjectId>

Peel an object id to the commit it ultimately names.

pub fn rev_parse(&self, spec: &str) -> Result<ObjectId>

Resolve a revision specification (anything git rev-parse accepts: branch/tag names, abbreviated or full object ids, HEAD~2, <rev>:<path>, @{u}, etc.) to a concrete ObjectId.

pub fn resolve_path(&self, rev: &str, path: &str) -> Result<ResolvedTreePath>

Resolve <rev>:<path> to the tree entry it names within <rev>’s tree.

rev is peeled to a tree (commit, tag, or tree ids all work) and path is walked component by component. An empty path resolves to the tree itself.

pub fn write_annotated_tag(&self, tag: TagCreate) -> Result<ObjectId>

Write an annotated tag object, returning its id.

This creates only the tag object; updating refs/tags/<name> is the caller’s responsibility (see Repository::apply_ref_changes).

pub fn copy_reachable_from( &self, other: &Repository, roots: &[ObjectId], ) -> Result<()>

Copy objects reachable from roots out of other into this repository.

Uses a pack-based transfer (sley_odb::build_reachable_pack on the source, [sley_odb::install_raw_pack] on the destination) for performance. Semantics:

• Only objects are copied; refs in other are not updated here.
• The transitive closure of each root is included (commits bring in their trees, blobs, tags, and parent commits).
• Objects already present in this repository are skipped by the pack installer (ids are unchanged).
• Both repositories must use the same ObjectFormat; mismatches error.
• When nothing new is reachable, this is a no-op (Ok(())).

pub fn read_object(&self, oid: &ObjectId) -> Result<Arc<EncodedObject>>

Read a raw object (any type) from the object database.

pub fn read_commit(&self, oid: &ObjectId) -> Result<Commit>

Read a commit object, parsing it into a Commit. Returns an error if oid does not name a commit.

pub fn read_tree(&self, oid: &ObjectId) -> Result<Tree>

Read a tree object, parsing it into a Tree. Returns an error if oid does not name a tree.

pub fn read_tag(&self, oid: &ObjectId) -> Result<Tag>

Read an annotated tag object, parsing it into a Tag. Returns an error if oid does not name a tag.

pub fn read_commit_author(&self, oid: &ObjectId) -> Result<Option<Signature>>

Read a commit and return the typed Signature parse-view of its author line, or None if the stored ident is malformed.

Convenience for repo.read_commit(oid)?.author_signature(): the raw author bytes are unchanged, and the returned signature re-serializes byte-identically to them (see Signature::to_ident_bytes).

pub fn read_commit_committer(&self, oid: &ObjectId) -> Result<Option<Signature>>

Read a commit and return the typed Signature parse-view of its committer line, or None if the stored ident is malformed. The raw bytes are untouched; see Repository::read_commit_author.

pub fn read_tag_tagger(&self, oid: &ObjectId) -> Result<Option<Signature>>

Read an annotated tag and return the typed Signature parse-view of its tagger line, or None if the tag has no tagger or the stored ident is malformed. The raw bytes are untouched; see Repository::read_commit_author.

pub fn write_object(&self, object: EncodedObject) -> Result<ObjectId>

Write a raw object (any type) to the object database as a loose object, returning its id. The bytes are stored verbatim, so writing an object that originated from another repository preserves its id exactly.

pub fn write_raw_object( &self, object_type: ObjectType, body: impl Into<Vec<u8>>, ) -> Result<ObjectId>

Write body as a raw object of object_type, preserving the bytes exactly and returning the resulting object id.

pub fn write_blob(&self, bytes: impl Into<Vec<u8>>) -> Result<ObjectId>

Write bytes as a blob, returning its id.

pub fn edit_tree(&self, base: &ObjectId) -> Result<TreeBuilder>

Start editing the tree base one level deep: returns a TreeBuilder seeded with base’s entries (empty when base is the null or empty tree). upsert entries on it, then write it with Repository::write_tree.

pub fn write_tree(&self, builder: TreeBuilder) -> Result<ObjectId>

Write the tree assembled in builder — entries emitted in Git’s canonical order — and return its id.

pub fn open_index(&self) -> Result<Option<Index>>

Read this repository’s index (.git/index), returning None when the index file does not exist yet.

pub fn index_from_tree(&self, tree_oid: &ObjectId) -> Result<Index>

Build a fresh index mirroring tree_oid (stage-0 entries with a zeroed stat), the way git read-tree <tree> would. Does not touch .git/index.

Trait Implementations

impl Clone for Repository

fn clone(&self) -> Repository

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Repository

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

Formats the value using the given formatter.

impl Eq for Repository

impl PartialEq for Repository

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.