Struct FilePickSource 

pub struct FilePickSource {
    pub spec: PickerSourceSpec,
}

:picker file-pick [root]. MG.53.e — the same walk as FilesSource, accepting to a value instead of to an open buffer.

The two differ only in what accept means, and that difference is the whole reason this exists: FilesSource hands its path to do_edit, i.e. it opens the file, where a caller asking “which file?” needs the path itself. magit’s File (repo-relative): argument was a free-text prompt because of that one mismatch — the listing was always reusable, the accept never was.

The path is emitted relative to the walk root, because the consumers are git commands and git addresses files repo-relatively. An absolute path would work by luck for the common case (the root is the repo) and break the moment it is not.

Registered in the host rather than in lattice-magit so every provider wanting “choose a file, then act” reaches it through the same PickerSourceSpec surface, including WASM ones. A magit-local copy would have put a second consumer of the repo file walk inside a feature crate and bought nothing but a smaller diff.

Fields

spec: PickerSourceSpec

Implementations

impl FilePickSource

pub fn new() -> FilePickSource

Trait Implementations

impl Default for FilePickSource

fn default() -> FilePickSource

Returns the “default value” for a type.

impl PickerSourceGenerator for FilePickSource

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], ) -> Result<PickerInitResult, String>

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, ) -> Result<PickerAcceptOutcome, String>

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 preview( &self, _ctx: &PickerContext<'_>, _routing: &RoutingPayload, ) -> Option<PickerPreviewOutcome>

T.12: live-preview hook — invoked as the picker SELECTION moves to a candidate (before accept). Default None = no preview. A source returns an outcome the host applies immediately for a live preview; the host restores prior state on .

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

MG.54: how long the selection must sit still before the host calls preview. None (the default) = call it inline on every selection move, which is right for a source whose preview is a cheap projection of data it already holds.

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

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