Struct RefPickSource 

pub struct RefPickSource { /* private fields */ }

MG.53.d/e: the tag, remote and ref pickers.

Three ids, one implementation, because they differ only in what they list. Reference::list already returns branches, remotes and tags in one for-each-ref walk tagged with a [RefKind], so a tag picker is that walk filtered — building a separate git tag call beside it would be a second way to ask the same question.

Parameterised by the ex-command that receives the pick, exactly as BranchPickSource and CommitPickSource are, and for the same reason: a picked candidate reaches an operation only as an ex line.

Implementations

impl RefPickSource

pub fn new(repo: RepoLens, which: RefScope) -> Self

pub fn with_config( repo: RepoLens, which: RefScope, config: Option<Arc<ConfigRegistry>>, ) -> Self

Trait Implementations

impl PickerSourceGenerator for RefPickSource

fn preview( &self, ctx: &PickerContext<'_>, routing: &RoutingPayload, ) -> Option<PickerPreviewOutcome>

MG.54: C-c f v used to show nothing until you accepted, so choosing between two revisions meant accepting one, looking, going back, and accepting the other. This answers the question the picker is asking.

Synchronous git show, which is only sound because the host does not call this while the selection is moving — see Self::preview_debounce. The blob fetch itself is guarded (size, binary, line count) by preview_blob.

The preview buffer takes the name magit-find-file would give the real one, so what the pane says while you are choosing is what the buffer is called once you accept.

fn preview_debounce(&self) -> Option<Duration>

MG.54: never while the user is still moving.

git show on every arrow key would be a subprocess per keystroke on the actor thread. Declaring the window means a scroll through fifty revisions spawns nothing at all, and the one fetch that does run is for the revision the user stopped on — so there is nothing to cancel and no stale result to discard.

None when the feature is off, so a user who turns it off pays for no timers either. The other scopes never previewed.

fn spec(&self) -> &PickerSourceSpec

Generator metadata. Returned by reference so the registry can stamp it into :describe-picker / :picker <Tab> listings without cloning.

fn init( &self, ctx: &PickerContext<'_>, args: &[String], ) -> SourceResult<PickerInitResult>

Build the candidate set. Sync prelude: read what’s needed from ctx, clone into async captures if necessary, return the appropriate PickerInitResult variant. Synchronous errors (no active buffer when one was required, args validation failure) return Err; the host echoes the error and leaves the picker closed.

fn accept( &self, _ctx: &PickerContext<'_>, routing: &RoutingPayload, ) -> SourceResult<PickerAcceptOutcome>

Translate the user’s chosen routing payload into a typed PickerAcceptOutcome the host applies. The generator owns the mapping from its emitted routing-payload variant(s) to outcome(s); mismatch returns Err, which the host echoes.

fn accept_async( &self, _ctx: &PickerContext<'_>, _routing: &RoutingPayload, ) -> Option<Pin<Box<dyn Future<Output = Result<PickerAcceptOutcome, String>> + Send>>>

Async-accept hook. Default None means “this source resolves accept synchronously” — every native source takes this path and is unchanged.

fn on_query_changed( &self, _ctx: &PickerContext<'_>, _query: &str, ) -> Option<Result<PickerInitResult, String>>

Live-source hook: re-fetch candidates when the user’s query changes. Default None means “static source – host uses fuzzy refilter over the candidate set returned by init”. Returning Some(result) from a source whose spec().live == true replaces the picker’s candidate set wholesale; the host wires up debouncing and cancels any in-flight invocation when a fresh query arrives.

fn descend( &self, _ctx: &PickerContext<'_>, _candidate: &RawCandidate, ) -> Option<String>

PC.10: <C-l> — refine the query from the selected candidate instead of accepting it.

fn ascend(&self, _query: &str) -> Option<String>

PC.10: <C-w> (<C-h> until PH.1) — descend’s peer, one level out.

fn accept_navigates( &self, _ctx: &PickerContext<'_>, _candidate: &RawCandidate, ) -> Option<String>

PP.3: <CR> on a row that is a SIGNPOST rather than a destination.

fn initial_query(&self, _args: &[String]) -> Option<String>

PP.1: the query the picker opens WITH.

fn owner_plugin(&self) -> Option<u64>

PH.1: the host-issued id of the plugin that contributed this source, None for a native one.