pub struct PerFunctionBlame { /* private fields */ }vcs-git only.Expand description
A blame engine bound to one repository, reusable across the per-file metrics walk.
Holds a gix::ThreadSafeRepository (so the field can be shared
read-only across the CLI’s worker threads — a plain
gix::Repository is not Sync). Construct once per invocation with
open, then open one BlameSession per worker thread with
session: the session carries the thread-local handle, its object
cache, the mailmap, and the resolved-commit memo, none of which
survive a per-file handle.
Implementations§
Source§impl PerFunctionBlame
impl PerFunctionBlame
Sourcepub fn open(root: &Path, options: Options) -> Result<Self, Error>
pub fn open(root: &Path, options: Options) -> Result<Self, Error>
Open the repository enclosing root, resolve the target ref, and
build a reusable blame engine.
§Errors
Returns Error::NotARepository when root is not inside a git
working tree, Error::ResolveRef when the configured reference
cannot be peeled to a commit, Error::InvalidBotPattern for a
bad bot regex, or Error::OpenRepository for a bare repository
(per-function blame needs a working tree to map files).
Sourcepub fn session(self: &Arc<Self>) -> BlameSession
pub fn session(self: &Arc<Self>) -> BlameSession
Open a reusable BlameSession on the calling thread.
Every cost that BlameSession::per_function would otherwise pay
per file — the thread-local repository handle, its object cache,
the parsed .mailmap, and the resolved-commit memo — lives on the
session instead, so a caller that blames many files in one repository
pays each once. Sessions are !Sync by construction (they hold a
gix::Repository); a worker pool wants one per thread, not one
shared.
Holding a handle for a whole thread rather than a single file does
not widen the issue-#579 staleness window. The
ThreadSafeRepository — and the gix_odb::Store behind it — is
already fixed for the engine’s lifetime, so a handle’s age adds no
config or pack staleness of its own; and a handle refreshes its own
pack-index snapshot on a miss before reporting one, so the retry in
per_function re-reads exactly what a fresh
handle would. gix::Repository::reload (a full re-open from disk)
is therefore the wrong tool inside that retry: the miss it guards
is an internal gix index-load race, not an external write we need
to observe.
Sourcepub fn per_function(
&self,
absolute: &Path,
spans: &[LineSpan],
) -> Result<Vec<Stats>, Error>
pub fn per_function( &self, absolute: &Path, spans: &[LineSpan], ) -> Result<Vec<Stats>, Error>
Blame the file at absolute once and return one Stats per
entry in spans, in the same order.
A span with no surviving in-window lines yields a zero-valued
Stats (the per-function analogue of a tracked file with no
recent activity), so the caller can attach a block to every
function space uniformly.
This is the one-shot form: it builds and discards a
BlameSession per call. Callers blaming more than one file
should hold a session (session) instead.
§Errors
Returns Error::Blame when the path lies outside the working
tree, is not valid UTF-8, or the blame itself fails (e.g. the
file does not exist at the target ref).