Struct Repo 

pub struct Repo { /* private fields */ }

A discovered git repository.

Implementations

impl Repo

pub fn discover(path: &Path) -> Result<Self, GitError>

Discover the repository containing path (walking upwards to the .git).

Errors

Returns GitError::Git if no repository is found or it cannot be opened.

pub fn common_dir(&self) -> &Path

The repository’s common git directory. The cache lives under here so it is shared across linked worktrees (which each have their own git dir).

pub fn git_dir(&self) -> &Path

This worktree’s git directory (per-worktree; the graph DB lives here).

pub fn hooks_dir(&self) -> PathBuf

The directory git actually looks in for hooks. Honours core.hooksPath (absolute, or relative to the working-tree root — else the git dir); when unset it is <common git dir>/hooks, so managed hooks are shared across linked worktrees. roteiro init installs into this so its hooks run wherever git expects them.

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

The working directory, if this is not a bare repository. The dirty overlay reads uncommitted file contents from here.

pub fn blob_oid(&self, bytes: &[u8]) -> Result<String, GitError>

The hex git blob object id that bytes would have, without writing anything. Used to detect whether a working-copy file differs from the committed blob (same content ⇒ same id).

Errors

Returns GitError::Git if hashing fails.

pub fn head_tree_id(&self) -> Result<String, GitError>

Hex object id of the tree at HEAD.

Errors

Returns GitError::Git if HEAD cannot be resolved to a tree.

pub fn head_commit_id(&self) -> Result<String, GitError>

Hex object id of the commit at HEAD — a stable permalink ref for the tree the graph was built from (used to build source links).

Errors

Returns GitError::Git if HEAD cannot be resolved to a commit.

pub fn head_commit_time(&self) -> Result<i64, GitError>

Seconds since the Unix epoch of the HEAD commit’s commit time, in UTC.

Added for analyzer-asset provisioning: an advisory database that is a git checkout has no publication date of its own, and cargo audit reports none at all when it is pointed at a database with --db rather than resolving one itself. The commit time is the publication date, and it is what lets a result be labelled possibly stale with a number attached (ADR-0012).

Errors

Returns GitError::Git if HEAD cannot be resolved to a commit or the commit carries no readable time.

pub fn origin_url(&self) -> Option<String>

The origin remote’s fetch URL, if one is configured — e.g. to derive a web “blob” base for source links. None when there is no origin remote.

pub fn walk_blobs(&self) -> Result<Vec<BlobRef>, GitError>

Every blob reachable from the HEAD tree, with full paths.

Errors

Returns GitError if the tree cannot be traversed or a path is not valid UTF-8.

pub fn blobs_at(&self, rev: &str) -> Result<Vec<BlobRef>, GitError>

Every blob reachable from an arbitrary commit-or-tree rev (a hex oid), with full paths — like Repo::walk_blobs but for any point in history, not just HEAD. A commit oid is peeled to its tree, so a submodule pin (a commit sha) works directly. The primitive for extracting a repo’s graph at the version a spoke pins (ADR-0009 step 8 — version-pin resolution).

Errors

Returns GitError if rev cannot be resolved to a tree, the tree cannot be traversed, or a path is not valid UTF-8.

pub fn tree_id_at(&self, rev: &str) -> Result<String, GitError>

The hex tree id an arbitrary revspec resolves to (a commit peels to its tree) — an O(1) resolution that does not walk the tree, so it doubles as a cheap “does this ref exist?” check (ADR-0009 step 8b/8c).

Errors

Returns GitError if rev cannot be resolved to a tree.

pub fn submodules(&self) -> Result<Vec<Submodule>, GitError>

Every git submodule pinned in the HEAD tree, sorted by path: a gitlink (commit) entry gives the path and the commit it points at, enriched with its .gitmodules URL when declared. The pinned commit is the version a deployment repo ships (ADR-0009 derived facts). Empty when there are none.

Errors

Returns GitError if the tree cannot be traversed, .gitmodules cannot be read, or a path is not valid UTF-8.

pub fn submodules_at(&self, rev: &str) -> Result<Vec<Submodule>, GitError>

Every git submodule pinned at an arbitrary commit/tree rev, sorted by path — like Repo::submodules but for a historical point, so a hub graph extracted at a pinned version (ADR-0009 step 8) carries its own submodules as they were then.

Errors

As Repo::submodules, plus if rev cannot be resolved to a tree.

pub fn index_submodules(&self) -> Result<Vec<Submodule>, GitError>

Every git submodule pinned in the staged index (the tree a commit would record), sorted by path. Same shape as Repo::submodules but reads the gitlinks (and .gitmodules) from the index, so the index-aware sync — the pre-commit gate — reflects a staged submodule bump, not the HEAD pin.

Errors

As Repo::submodules, plus index-load failure.

pub fn changed_between(&self, base: &str) -> Result<Vec<ChangedFile>, GitError>

The tracked files that differ between base (any revspec — a branch, HEAD~3, a sha) and the current HEAD, sorted by path. Used for change-scoped tooling over a commit range (e.g. roteiro review --base main), distinct from Repo::changed_files, which compares the working tree to HEAD. A path only in HEAD is added, only in base is deleted.

Errors

Returns GitError if base cannot be resolved to a tree, a tree cannot be traversed, or a path is not valid UTF-8.

pub fn read_blob(&self, oid: &str) -> Result<Vec<u8>, GitError>

Read the bytes of the blob with hex object id oid.

Errors

Returns GitError::Git if the id is malformed or the object is absent.

pub fn read_source( &self, blob: &BlobRef, source: GraphSource, ) -> Result<Option<Vec<u8>>, GitError>

The bytes of a tracked file’s authored source, from the tree named by source: the committed HEAD blob, the staged blob, or the file as it stands on disk (unstaged edits included, and not the git index).

The Worktree reading matches crate::sync_worktree, which the derived graph is built from, so the authored and derived layers stay consistent — see GraphSource for why that pairing is one type rather than two independent choices.

Returns Ok(None) when a worktree file has been deleted, so the caller drops it.

Errors

Returns GitError::Git if the blob cannot be read, or if reading the working-tree copy fails for any reason other than the file being absent.

pub fn changed_files(&self) -> Result<Vec<ChangedFile>, GitError>

Tracked files whose working-tree content differs from HEAD — the change about to be committed. A file is changed when its working-copy bytes hash to a different blob id than the committed one (content, not mtime), and deleted when it is absent from the working tree. Untracked new files are not reported (they are not in the HEAD tree). Same detection as crate::sync_worktree, surfaced for change-scoped tooling.

Errors

Returns GitError on a git failure. In a bare repo (no working tree) the change set is empty.

pub fn index_files(&self) -> Result<Vec<BlobRef>, GitError>

The staged files: each regular blob in the git index with its staged object id, sorted by path. This is the tree that a commit would record — unlike Repo::changed_files (the working tree) — so it lets tooling gate exactly what is about to be committed (the pre-commit index-aware check). Conflict (unmerged) entries, directories, submodules and symlinks are skipped.

Errors

Returns GitError if the index cannot be loaded or a path is not valid UTF-8.

pub fn untracked_files(&self) -> Result<Vec<String>, GitError>

Untracked, non-ignored regular files in the working tree — brand-new files that are in neither HEAD nor the index, so Repo::walk_blobs and Repo::changed_files (both HEAD-tree based) miss them. The working-tree sync/check/review overlay these so a new-but-unstaged file is seen.

Respects .gitignore / .git/info/exclude / global excludes, skips nested repositories and non-regular files (symlinks, dirs, submodules), and returns repository-relative, unix-separated paths, sorted. Empty in a bare repo.

Errors

Returns GitError on a git failure or a non-UTF-8 path.

impl Repo

pub fn diff_trees(&self, old: &str, new: &str) -> Result<TreeDiff, GitError>

The blob-level diff between two tree object ids (old → new), pruning unchanged subtrees: gix descends only into subtrees whose oid differs, so the cost is proportional to the change, not the tree size. Renames are reported as a delete plus an add (rewrite tracking is off), which is what the path-scoped extractor wants. Results are sorted by path for determinism.

This is the incremental-sync counterpart to Repo::walk_blobs: given the last-synced tree and HEAD, it yields exactly the paths that changed.

Errors

Returns GitError if either id is not a tree, the diff fails, or a path is not valid UTF-8.