Trait Revision

pub trait Revision {
    // Required methods
    fn find_ref(&mut self, name: &BStr) -> Option<()>;
    fn disambiguate_prefix(
        &mut self,
        prefix: Prefix,
        hint: Option<PrefixHint<'_>>,
    ) -> Option<()>;
    fn reflog(&mut self, query: ReflogLookup) -> Option<()>;
    fn nth_checked_out_branch(&mut self, branch_no: usize) -> Option<()>;
    fn sibling_branch(&mut self, kind: SiblingBranch) -> Option<()>;
}

Usually the first methods to call when parsing a rev-spec to set an anchoring revision (which is typically a Commit object). Methods can be called multiple time to either try input or to parse another rev-spec that is part of a range.

In one case they will not be called at all, e.g. @{[-]n} indicates the current branch (what HEAD dereferences to), without ever naming it, and so does @{upstream} or @{<date>}.

Note that when dereferencing HEAD implicitly, a revision must be set for later navigation.

Required Methods

fn find_ref(&mut self, name: &BStr) -> Option<()>

Resolve name as reference which might not be a valid reference name. The name may be partial like main or full like refs/heads/main solely depending on the users input. Symbolic referenced should be followed till their object, but objects must not yet be peeled.

fn disambiguate_prefix( &mut self, prefix: Prefix, hint: Option<PrefixHint<'_>>, ) -> Option<()>

An object prefix to disambiguate, returning None if it is ambiguous or wasn’t found at all.

If hint is set, it should be used to disambiguate multiple objects with the same prefix.

fn reflog(&mut self, query: ReflogLookup) -> Option<()>

Lookup the reflog of the previously set reference, or dereference HEAD to its reference to obtain the ref name (as opposed to HEAD itself). If there is no such reflog entry, return None.

fn nth_checked_out_branch(&mut self, branch_no: usize) -> Option<()>

When looking at HEAD, branch_no is the non-null checkout in the path, e.g. 1 means the last branch checked out, 2 is the one before that. Return None if there is no branch as the checkout history (via the reflog) isn’t long enough.

fn sibling_branch(&mut self, kind: SiblingBranch) -> Option<()>

Lookup the previously set branch or dereference HEAD to its reference to use its name to lookup the sibling branch of kind in the configuration (typically in refs/remotes/…). The sibling branches are always local tracking branches. Return None of no such configuration exists and no sibling could be found, which is also the case for all reference outside of refs/heads/. Note that the caller isn’t aware if the previously set reference is a branch or not and might call this method even though no reference is known.

Implementors