Commands

M-x opens the command prompt. In Vim Normal or Visual, : opens that same vertical selector with the full shared catalog, matching, history and argument workflow. Type canonical names; colon adds no Ex aliases, ranges or argument parser. Reported Alt/Meta and compatible Escape input follow the terminal input policy. Command entry uses the same admitted command catalog and handlers as keyboard bindings.

Cancelling a selector entered from Visual preserves the native selection only while its view, point, mark, source revision and shape remain valid. A changed source or selected view retires it; cancellation never copies old source offsets back into the editor.

Matching and invocation

• Type a lowercase hyphenated name or part of it. Matching is case-sensitive. minibuffer.match selects prefix-then-substring (the default), prefix or substring. An exact name comes first. The default then ranks prefixes before other substrings; substring mode has one remaining rank, while prefix mode excludes other substrings. Within each rank, up to four distinct recent commands lead, followed by up to four other frequent commands, then the alphabetical remainder. Empty queries use that same four/four ordering across the full catalog. No command appears twice and unused names fill no usage slot.
• The query appears above a vertical list with one command per row. Up to minibuffer.candidate_limit rows are shown (default 8, admitted range 1..=32), clipped to geometry after complete editing minima. The selected command uses the selection palette roles, with reverse video under NO_COLOR. No matches display No matching commands in an unselected row.
• Up/Down or C-p/C-n selects the previous/next candidate, stopping at either end without changing the query. The selected row stays visible as the list scrolls. Tab fills the selected command name without executing or cycling it; the original matching set remains available for further navigation.
• Return invokes an explicitly selected candidate, otherwise an exact typed name or the first match for a nonempty query. Opening M-x and pressing Return with an empty query reports No command entered; explicit navigation or completion is required to choose from the unfiltered list. Unknown names report Unknown command and restore the workspace without changing document text. Tab or navigation with no matches retains command focus and reports No matching command.
• Editing the query resets selection and scroll origin. Cursor movement and refused edits preserve them. M-p recalls earlier commands; M-n moves toward newer commands and then restores the draft query. History recall starts a new matching set; navigation stops at the oldest entry. The session retains up to 128 distinct accepted command names, most recent first. Accepting a name records the invocation even if its handler later refuses it. Canceled or unknown input does not enter history; this M-p/M-n navigation history is not persisted.
• C-g cancels command entry. Text, cursor edits and single-line paste remain in the prompt. The existing 4096-character prompt bound and control rejection apply. Releases and repeated Return do not invoke a command twice.

Candidate space borrows presentation rows without scrolling the retained editing workspace. When no candidate rows fit, the query and cancellation remain usable. Resize preserves the draft and selection; growing restores a coherent list. Rendering reads only the admitted command catalog and the selector's captured usage snapshot and prepared shortcut hints; it cannot execute a command or observe the filesystem.

Candidate ranking counts the last 256 accepted M-x or modal colon invocations, including registered AI commands. Frequency counts repetitions in that window; ties prefer the most recent invocation, then the canonical name. Each selector captures usage when it opens, so drawing and resize preserve the chosen identity. Typing, Tab, history recall, cancellation and unknown names add no usage. Direct bindings and internal calls also add none. A named invocation counts once when accepted even if its handler fails or a later argument prompt is canceled. The executable loads and saves this window across editor starts. It is separate from the configurable distinct-name M-p/M-n history above. Each open selector keeps its snapshot while other instances or its own publisher update usage.

Argument-taking commands continue with their existing path, buffer or decision prompts. Named edits use the same read-only admission and history as bindings. Opening and editing M-x is transient input, so a named yank-pop can still use the current yank range; cancellation or an unrelated invoked command ends it. Names are literal registry entries, with no expression or language interpretation.

See Focused prompts for argument stages, in-prompt editing and save/close cancellation.

isearch-forward and isearch-backward open incremental search with the same handlers as C-s and C-r. query-replace opens the same literal replacement prompts as M-% and requires an explicit decision for each occurrence.

See Bindings for the complete key map and Scope and defaults for file, history and retained-text policies.

Effective keybinding hints

M-x and the modal colon selector show one effective shortcut beside a bound command. With the factory non-modal bindings, a row can look like:

save-buffer  [C-x C-s]

The hint describes the editing profile, modal state and input owner where you opened the selector. Configured overrides, inherited maps and local precedence apply. Opening from an Org view, Git view, file tree or live terminal can produce a different hint. Input consumed by that owner is not advertised as a source editing shortcut. The selector captures these hints before its prompt takes focus; reopening it observes the current valid origin and bindings.

When several reachable sequences invoke a command, the primary hint uses the fewest normalized chords, then lexical order of their formatted notation. Equivalent terminal spellings collapse: for example, ESC j and M-j describe one Meta chord. Other valid bindings remain available. An unbound command, including a registered AI command without a shortcut, leaves that field empty and remains invocable through M-x. The list does not invent a binding from a command's name or similar effects.

Names retain their left edge. Shortcuts appear in a nearby left-aligned column, with brackets and at least two blank cells after the name. An optional command description occupies a third column. Missing descriptions stay blank.

The visible candidate block determines shared column starts. Descriptions clip at complete terminal cells and disappear when their column cannot fit. Narrow rows can retain a complete shortcut immediately after their name; if name, gap and bracketed shortcut cannot fit, the hint disappears as a whole. Growing the terminal restores annotations when they fit. Selection covers the entire row; unselected command names use the function accent, palette.syntax.function, while shortcuts and descriptions use palette.status_text on the normal background. The selected row keeps palette.selection_text and palette.selection across all fields. Command-name color is independent of source syntax highlighting. Under NO_COLOR, spacing and full-row reverse-video selection remain readable.

Hints are presentation data. Queries match command names only, Tab inserts only the canonical name, and Return dispatches and records that identity once. Hints follow the command through filtering, ranking and scrolling; they neither add usage events nor enter saved history. A changed origin retires its hints under the existing input-owner rules. Rendering reuses the captured labels without command execution, binding mutation or filesystem reads.

Command usage state

The executable uses $XDG_STATE_HOME/rev/command-history.toml, falling back to $HOME/.local/state/rev/command-history.toml under the existing XDG root rules. The window is user-wide across files, directories and editing profiles. Loading or merely opening a selector creates no state file. After a named invocation, publication may create missing state parents and writes a complete user-only record. Ordinary shutdown makes a final bounded publication attempt; forced termination can lose unpublished events.

version = 1
commands = ["find-file", "undo", "find-file"]

Names are oldest first, with repetitions retained for frequency. The record accepts at most 256 names, each at most 128 ASCII bytes: a lowercase letter followed by lowercase letters, digits or hyphens. Input and output are bounded to 64 KiB. No arguments, paths, prompt drafts, document contents or timestamps enter this record. Unknown but well-formed historical names remain data and cannot introduce commands into the selector.

Concurrent publishers acquire a nonblocking sibling lock and append pending events to the latest valid disk window before atomic replacement. A busy lock defers publication until later owned work or shutdown; it adds no recurring idle polling. An unresolved replacement outcome suspends that instance's persistence so a retry cannot count a batch twice.

Missing state starts empty. Unreadable, malformed, oversized and unsupported records produce a non-modal Command usage: ... diagnostic, retain session ranking and preserve the existing file. Publication errors do not prevent editing or shutdown. Pure Input and Session::new/empty construction does not discover user history; embedding hosts explicitly supply a command::usage::History owner and drive publication and final flush.

Implemented catalog

The editor and Org command catalog together list every compiled M-x name once.

See Rectangles for display-column selection and copy boundaries. See File tree for root, layout and keyboard focus.

Line navigation

With wrapping enabled, Up/Down and C-n/C-p move through visual rows. C-a/C-e address the current visual row. Following Emacs, C-e stops on the character where a continued row wraps; at a source EOL it reaches the insertion boundary. C-k kills to that visual end, including wrap whitespace. At the visual end, the next kill consumes the wrap character or real source newline. Kills retain the ordinary kill ring, undo and read-only admission. Disabling wrapping restores logical-line motion and kills.

Paging and recentering use visual rows while wrapped. Goal columns follow terminal cells and are recalculated when pane width changes. Each split keeps its own point and viewport over the same source text.

M-g g, M-g M-g and M-x goto-line open Goto line: . Enter a signed 64-bit decimal integer and press Return. The configured minibuffer.input_limit bounds the draft (default 4096 Unicode scalars). Surrounding whitespace is ignored; malformed, fractional, nondecimal or overflowing values retain the draft with feedback so it can be edited and submitted again. Tab displays input guidance. C-g cancels and retains the original point, viewport and navigation state; normal region deactivation still applies.

Numbers refer to one-based logical lines. Existing lines go to their beginning; zero or negative numbers go to buffer start, and numbers past the final line go to exact buffer end. A final newline therefore admits a final empty logical line. Navigation reveals the destination in the selected view, preserves other views and uses the existing mark/region rules. Read-only text remains navigable; no edit, undo entry, dirty change or save occurs.

Whitespace conversion

M-x tabify and M-x untabify act on the marked region. Set mark with C-SPC, move to the other endpoint, then invoke the desired command. To select the whole document explicitly, use M-<, C-SPC, M-> in that order. Without an active region the command reports Region is not active; it never selects the document implicitly. An empty or already unchanged region reports No whitespace changed and creates no edit, undo entry or dirty-state change.

Untabify expands selected literal tabs to spaces using the buffer's effective editor.tab_width (1..=32), including language overrides. Tabify replaces eligible selected runs of spaces/tabs with a shorter representation at those same stops. A one-cell run cannot shorten. Both commands use actual display columns, including wide/combining text and any unselected prefix of the current line. Whitespace inside strings or comments participates when selected.

Only selected whitespace changes. Other text, BOM, LF/CRLF separators and final newline presence remain intact, and non-whitespace text keeps its display columns. A space can anchor an otherwise zero-width grapheme following an expanded tab, preserving its existing visible cell. Settings, the Tab key's insertion policy, other buffers and the kill ring remain separate from conversion.

Each conversion is one checked edit across all selected lines. One undo restores the original bytes and redo restores conversion; shared views use ordinary point and viewport mapping. Read-only buffers reject nonempty conversion. C-g while entering the M-x command cancels without editing and retains normal region cancellation. There are no factory shortcuts for these commands; an existing validated editor keymap may bind either name.

Supplied retention preferences

Library sessions supplied with an admitted snapshot use history.group_limit (1..=65536 complete groups, default 512) and history.payload_target_bytes (1..=1073741824 logical fragment bytes, default 67108864). At each completed edit, oldest whole groups evict until both targets hold, always retaining the newest coherent group even when it alone exceeds the payload target. This soft target is not a process-memory maximum. Applying a different buffer policy leaves published undo/redo records intact until the next edit; branching then discards redo and applies retention through the canonical history owner. Pruning never marks text saved or changes the logical saved-state identity.

kill_ring.capacity admits 1..=4096 linear entries (default 32). A new entry replaces the oldest when full; yank-pop wraps over the retained entries, including at capacity one. With kill_ring.coalesce = true (the default), consecutive compatible kills append forward or prepend backward. Setting it false retains separate entries. Copy and intervening commands still end continuity. Rectangular text retains its separate owner. These preferences retain only session memory.

Native task workflows

See Org native task workflows.

Named bookmarks

For a task sequence, see Save and revisit named locations.

C-x r m (bookmark-set) records the current file position under a name. Return with an empty draft uses the visited basename shown as the default; type a name to distinguish positions in the same file. Names are case-sensitive, retain spaces literally, and contain 1..256 UTF-8 bytes without control characters. Setting an existing name replaces its location. C-x r M (bookmark-set-no-overwrite) refuses an occupied name. C-x r b (bookmark-jump) visits a name; M-x bookmark-delete removes it.

These commands use a vertical name list with the configured minibuffer matching policy and row limit. Up/Down or C-p/C-n selects a candidate; Tab fills the highlighted name without accepting it. Return accepts an explicitly selected candidate or the exact typed name. The initial highlight alone does not select a name. C-g cancels; errors retain the draft for correction. Names are shared across files, with a configurable cap of 1024 records by default and 4096 encoded path bytes per record. Reaching the limit never evicts another name.

Modified, read-only and intended new file buffers are eligible. Unnamed and synthetic buffers cannot supply a bookmark. Commands do not save source text, change its modified flag, or add source undo steps. Aliases reuse the canonical live file buffer, including unsaved text, and visiting a bookmark preserves an explicit file-tree root. Rectangle bindings under C-x r remain available.

Checked source locations

The user-wide collection loads lazily on first bookmark use, enabled marker demand for a file-backed view, or canonical rename/save-as demand, so closed records can follow that path change. Live positions follow canonical edits, structural moves and source undo/redo. Insertions at the point use left affinity. Removing the original position makes it stale; source undo can restore it, or an explicit set can replace it. Undo does not recreate deleted names or replace a bookmark set after that source transaction.

Closing a buffer retains bounded context, and jumping rechecks that evidence against the reopened file. A changed position can relocate through one unique context match; ambiguous, missing or unavailable targets retain the original view and record. The factory limits capture 64 scalars on each side and search at most 262144 source scalars, in passes of at most 16384. C-g or new input cancels pending resolution; resize and key releases retain it. Checked context is location evidence, not proof of historical identity after duplicated edits.

An already open canonical buffer takes precedence, including its unsaved text. Discarded text is never recreated for a bookmark. Successful file or directory rename updates associated records, including closed targets; save-as follows the canonical buffer destination. Jumps reveal folded ancestors and wrapped fragments in the selected view without changing other splits' fold state.

Storage and recovery

M-x bookmark-save stores the collection without saving any source document. By default, quitting saves bookmarks after all source save/discard decisions. Set bookmarks.save = "on-change" to checkpoint explicit set/delete operations, rename and source-save boundaries; text edits only dirty evidence for the next checkpoint. "manual" saves only on explicit request and leaves unsaved bookmark changes unsaved on ordinary quit. A failed automatic quit checkpoint offers retry, discard or cancel in a name prompt; C-g also cancels. Discard permits that exit without changing source text or pretending the collection was stored.

M-x bookmark-reload validates disk before offering to discard dirty in-memory bookmarks. No or C-g retains both states; yes rechecks disk before replacement. The default destination is the existing XDG user data root's bookmarks.toml; bookmarks.file can select an absolute destination. Storage is independent of launch directory and tree root. Embedded library sessions retain host ownership and use persistence only with an explicit configured destination.

The strict version-1 TOML stores names, lossless native paths, scalar positions and bounded before/after context in lexical name order. Unknown fields/versions, duplicate names, malformed evidence, unreadable files, more than the configured entry cap or more than 16 MiB reject the complete candidate. Invalid stores and unsaved memory are retained; native in-memory operations remain available. After correcting storage, explicitly reload before replacing an unknown store.

A nonblocking sibling file lock serializes cooperating writers. Saves compare exact observed identity and bytes, stage and sync in the same directory, then atomically replace and verify publication. A conflicting or busy store requires retry or explicit reload; explicit save alone never authorizes an overwrite. A failure after publication remains unresolved until actual candidate bytes and sync completion reconcile. Newly owned data directories/files are private to the user. The stable sibling lock file may remain after the OS lock releases.

For a whole short file containing Notes and a final newline, a stored BOF record has this form:

version = 1

[[bookmarks]]
name = "notes-start"
path = "/work/notes.txt"
position = 0
before = ""
after = "Notes\n"
at_start = true
at_end = true

The example path is illustrative. Positions count source Unicode scalars, not bytes, screen columns or wrapped rows. Non-UTF-8 native paths use an encoded path_bytes array instead of path; exactly one is present. An empty store has only version = 1. View policy, transient IDs and lookup indexes are not stored.

Native list and ordered visits

C-x r l (list-bookmarks) opens a native read-only *Bookmarks* view in the selected pane. It lists names lexically with file paths and observed resolved, unresolved, stale or unavailable status; opening and painting do not read target sources. Up/Down, C-p/C-n or p/n moves between rows. Return visits the selected stable record through the checked jump owner. A failed or canceled visit retains the list and originating source.

Status is an observation, not a background filesystem poll. A failed context check can retain an unresolved record with its diagnostic until another visit.

In the list, bookmark-bmenu-delete (d) marks a record and advances; bookmark-bmenu-unmark (u) clears its mark and advances. bookmark-bmenu-execute-deletions (x) atomically removes marked records; bookmark-bmenu-this-window (Return) visits the selected record. q or C-g returns and discards unexecuted marks. Quit also discards those marks. The local keys are configurable in keys.bookmark_list. M-x retains ordinary prompt ownership; C-x o changes pane focus without editing the list's source.

Collection changes invalidate menu observations and clear staged marks before an action can affect a replacement row. The list refreshes and asks for a retry. Returning rechecks the original source revision; a changed or closed origin retains the current valid source view with a diagnostic. Source text, dirty state and undo history are independent of row navigation and bookmark deletion.

M-x bookmark-next and M-x bookmark-previous visit revision-current resolved bookmarks within the current canonical file, in scalar position order with lexical name ties, wrapping at each end. There are no factory shortcuts. The first command includes targets at point; repetition advances by stable record identity, so several names at one point are visited individually. Changing direction steps back through that same order. Point movement, source edits, pane changes and collection mutations reset the repetition observation. Unresolved, stale and unavailable records are retained but skipped; an empty eligible set reports a clear result and suggests a checked jump by name.

Bookmark markers

M-x bookmark-markers-mode toggles markers for the current editing view. Splits inherit its effective visibility; other views retain their policy. Enabled markers reserve one cell on gutter.side independently of number labels, after protecting available number geometry and at least three text columns. Only the first visual fragment of a resolved logical line receives the configured glyph. Multiple names on a line share that glyph and remain independently navigable. Hiding markers never deletes records. Storage admission occurs on first native marker demand for a file-backed view; painting never loads, relocates or saves.

Reload a visiting file

Run M-x revert-buffer or :revert-buffer to read a fresh checked disk image. A modified buffer requires confirmation to discard its unsaved contents; n or C-g retains the current text. Edits, file replacement or association changes invalidate pending work and consent. Missing, nonregular, invalid UTF-8, NUL or oversized sources leave the buffer intact. The configured reload byte limit applies, and the source file is never written by this command.

Reload is one undoable native change across shared panes and retains prior history. Undo restores the previous text as modified relative to disk; redo returns to the clean reload image. Read-only visiting buffers can refresh while remaining read-only. Same-byte observations update checked file evidence without an edit or cursor movement. Startup external-change policies and bounds are listed in defaults.

External file changes

Visiting files are observed through their parent directories, including hidden buffers. Atomic rename, direct writes, deletion and recreation remain observable. Shared panes use one subscription and one native reload. Idle observation waits for kernel events without scanning the project or polling file contents.

The default files.external_changes = "reload" refreshes clean visiting buffers. With "ask", a passive notice and disk: revert-buffer status retain the current text until explicit reload. Dirty buffers retain unsaved text under either policy, with a conflict notice and the existing save overwrite confirmation. Notices name the buffer and reload action without taking input focus; another external version can notify again after dismissing an earlier echo.

Missing, invalid or oversized images retain text and history. Recreation at the same admitted filename triggers fresh validation. Registration limits or failures report unavailable coverage while revert-buffer remains usable. Queue overflow schedules finite recheck batches. Successful save/reload observations coalesce, and undo of an automatic reload stays dirty instead of being immediately overwritten.

Selection explanations through Pi

Select a nonempty linear region and run M-x ai-explain or :ai-explain. This optional command starts a checked Pi 1.3.0 child only when invoked. Set ai.pi.command to the installed executable name/path and optionally set ai.pi.model; authenticate through Pi before retrying an authentication failure. The executable is trusted and receives literal adapter arguments without a shell.

The command sends the captured selection and its native source metadata. Its directory context starts at the explicit AI directory override, otherwise the opened tree root, otherwise the visiting file's parent, otherwise the editor's launch directory. It never climbs to an inferred repository root. Pi chooses which sources to inspect through the internal read, list and literal-search tools; shell, edit/write tools, automatic extensions, MCP, skills, templates and discovered instruction files are disabled. Directory operations reuse only compatible private history and an owned idle child, according to the settings below. Input-only operations always start with --no-session and close their child when finished. Ordinary editing starts no Pi process or AI state files.

A prompt acceptance notice is pending work. Completion waits for agent_settled and a valid final explanation. A native read-only *AI Explanation* buffer shows a source-named heading followed by the explanation in Org markup. The trailing REQUEST drawer holds editor-supplied backend, model, input/context policy, history, captured source revision/range and directory root when applicable. It starts folded; TAB on its opener toggles it. Native Org visibility remains independent per pane, including manual show-all. Setting org.enabled = false leaves the result readable as plain text, without Org coloring or folding. Disabling syntax coloring alone still permits the drawer to start folded. No Org file is created on disk.

Default explanation guidance uses a software engineering perspective for code, configuration, logs, diffs and technical documents. Clearly different material receives a relevant perspective without a persona announcement. The instruction asks for an overview for whole files and focused detail for short selections. Org format guidance is separate from the literal instruction; saved prompts and their requested perspective or length are preserved. Model compliance and wording remain probabilistic. rev supplies the surrounding title and request facts; they are not fields invented by the model. The source is never saved or changed by explanation. Editing may continue during generation; if source or focus changes, use switch-to-buffer to inspect the result. C-g or modal Escape owned by editing cancels and fences late results; a prompt's cancellation remains owned by that prompt. A stopping child keeps the sole operation slot until cleanup finishes. Errors retain the source and require an explicit retry.

The adapter admits LF records up to 2 MiB, protocol queues up to 4 MiB/256 records, a 64 KiB stderr tail and at most eight model turns. The configured input/result limits also apply. Cancellation sends clear_queue then abort, allows at most five seconds for acknowledgements/settlement, then closes stdin with a two-second stop grace and a two-second forced-reap deadline. No native API fallback is selected.

Guarded Pi directory reads

The packaged internal resource is extracted to a checked private cache only for an invoked directory operation. It requires Linux descriptor paths and Pi 1.3.0; no separate JavaScript installation or user plugin setup is needed. Admission checks the effective three-tool allowlist before starting model work.

Tool paths are relative to a canonical root. Every component is opened without following symbolic links, and root identity plus opened file/directory handles are checked around IO. Hard links, special files, invalid UTF-8, NUL-containing files and regular files over 1 MiB are rejected. Root replacement retires the grant. Missing sources report unavailability; an admitted native snapshot can still represent an unsaved file whose disk entry disappeared.

Discovery excludes .git, .pi, common credential paths such as .env, SSH keys and credential/key files, and resolved editor/Pi private directories. These path exclusions do not classify arbitrary source contents as safe to transmit. Select a root whose ordinary source files may be sent to the chosen Pi model. The configured executable and packaged adapter are trusted process code; cwd is not an operating-system sandbox.

Read ranges use Unicode scalar offsets, at most 32768 scalars per call. Listing supports an optional literal path substring and bounded recursion. Search is case-sensitive literal text, includes native snapshots and labels disk matches as disk observations. Results report completeness, skipped entries and source provenance. Each traversal visits at most 4096 entries and 16 nested directory levels. Search inspects at most 128 files/4 MiB and returns bounded excerpts.

One invocation admits at most 32 tool calls, eight model turns and 4 MiB of returned discovery text. Before source IO, a tool reserves 256 KiB of remaining return capacity; an insufficient remainder ends discovery conservatively. Compaction never resets these counters or the native request deadline. Discovery returns data only and cannot expand the original native editing target.

Reusable AI commands

After a successful operation, run ai-save-command and enter a new name without its ai- prefix. This saves the successful literal instruction and its input, context, output and optional model policy, never the generated text or a captured source/result. Saving requires a valid current configuration graph; a changed root/include or competing publisher rejects the transaction. Includes, comments, unrelated values and other definitions retain their existing representation. Existing names are refused; choose another name or edit the definition explicitly in configuration.

The chosen saved command becomes callable immediately through M-x or modal colon. Only that definition activates: other disk changes and newly persisted keybindings follow ordinary restart behavior. C-g cancels the name prompt without writing. No process starts merely because a definition is configured or saved.

Definitions use ai.commands.<name> in the existing user TOML graph. At most 64 names are admitted. Names contain 1..64 lowercase ASCII letters/digits/hyphens, start with a letter, and cannot collide with compiled command/action names. The callable identity is ai-<name>. Each complete record requires a nonempty literal prompt of at most 16384 UTF-8 bytes, input, context and output. An optional model selects Pi's provider/model without changing credentials. Shell substitutions, template interpolation and executable handlers do not run.

Input selection requires a nonempty linear region; point captures an insertion anchor; buffer explicitly captures the complete native buffer. Output explanation is read-only. Output insert requires point input; replace requires selection or buffer input. Every invocation captures fresh source and target identities. Application retains the same explicit acceptance and one-step undo as builtin proposals, including stale-target rejection.

Context input transmits only the selected input envelope, with no directory tools, peer snapshot map or retained history. It always starts a fresh ephemeral child, including after broader directory work. Context directory permits the existing guarded discovery/snapshot policy and compatible private history. Changing that boundary first closes an idle child; retry after owned cleanup. A definition's model overrides the session-local choice, then the configured Pi model; an absent model uses those existing choices.

[ai.commands.table-total]
prompt = "Add a totals row and preserve the table layout."
input = "selection"
context = "input"
output = "replace"

[keys.editor]
"M-j" = "ai-table-total"

[keys.vim_normal]
"g t" = "ai-table-total"

Complete records merge by name through normal include/root precedence; duplicate keys within one TOML source reject. Definition admission precedes final keymap reference validation, so included maps can refer to a root definition. Existing context, prefix and reserved cancellation/recovery rules still apply. The full compiled catalog remains available alongside admitted saved names.

Private Pi sessions and controls

ai-set-directory opens a native path prompt for a session-local AI root. Relative paths resolve against the current AI root. The chosen canonical directory does not change the file tree, visiting file or editing target. ai-select-model queries Pi and offers only its reported provider/model identifiers in the native name selector. The choice applies to this editor session; it does not write configuration or authentication data. Both commands are available through M-x and modal colon without a factory key prefix.

With ai.pi.persist_sessions = true, directory history lives under the XDG state root: rev/ai/pi/sessions.toml binds a canonical root, exact configuration/grant observations and resolved provider/model to a relative file under rev/ai/pi/sessions/. Pi owns that JSONL history and reconstruction. The native adapter stores bounded binding metadata, not a second transcript. New invocations capture fresh source revisions and grant counters; earlier source/tool messages remain historical and cannot replace the current native editing target.

The version-1 index admits at most 16 bindings and 64 KiB. Each history is limited to 32 MiB, including an OS file-size limit on the owned persistent Pi child. Private directories/files require modes 0700/0600 and current-user ownership. No-follow checks, identity observations and cooperating index/history locks reject unsafe paths, conflicting writes and simultaneous use of one history. Unknown schemas, corrupt/oversized records and unsafe histories are preserved and fail explicitly. Correct the owned store or set persistence false to use in-memory directory context; no automatic eviction or unknown-history overwrite occurs.

ai-reset-session stops the current child and makes the next explicit invocation under that directory/model start fresh owned history. Only its verified previous owned history can be removed after the replacement binding is published. ai-disconnect closes the owned child while preserving history and any completed result. ai-cancel cancels the active invocation or AI-owned prompt/result through its native owner. None of these commands changes source text or Pi credentials.

ai.pi.idle_timeout_ms keeps a compatible directory child available after a settled result (default 900000 ms); zero closes it immediately. The idle supervisor blocks on notification until a new explicit request, cancellation or its deadline; ordinary editor input has no AI idle polling timer. Idle expiry and editor exit close and reap the owned child. With persistence enabled, later explicit work restores compatible history in a new child. With persistence disabled, only that live directory child retains memory; input-only work remains fresh and ephemeral.

Changing root, model or admitted policy crosses an isolation boundary. A child that is active or stopping retains the single operation slot until cleanup finishes. Retry explicitly after the stopping notice; no hidden request queue starts another invocation. A new boundary never adopts the last arbitrary Pi session or widens an earlier input-only grant.

Generated text through Pi

Run M-x ai-prompt or :ai-prompt for a literal instruction. A nonempty linear selection chooses replacement; otherwise the command captures a point for insertion. ai-implement always captures point insertion, including when a selection is active. The instruction prompt names the source and chosen scalar range before execution. Missing required explain selections and rectangular replacement inputs fail without broadening the target.

Replacement includes its captured selection; point insertion supplies the instruction and native point metadata. Directory reads use complete snapshots of the current visiting source and up to 16 admitted current/dirty visiting buffers within that root, captured when the instruction is submitted and counted against max_input_bytes. These snapshots override disk for their paths. Another invocation refreshes them; later source edits still invalidate result acceptance. No whole-directory dump is sent. The instruction accepts at most 16384 UTF-8 bytes, also subject to native prompt and total AI input limits. No reusable command is saved by executing an instruction. Read-only editing targets reject before launch; a reload or association change during instruction input requires a new invocation.

A completed *AI Result* is a proposal in a native read-only Org buffer. A source-named heading precedes a source block for the captured language, or an example block for plain text. The same initially folded REQUEST drawer follows the proposal. Native Org block coloring applies; this does not add embedded language token highlighting. Source warnings and apply/discard actions remain outside the folded metadata. Run ai-apply-result while that result is selected to accept it, or ai-discard-result to close it and return to source. Explanations have no apply action. One pending result must be applied or discarded before a new invocation. C-g and editing-owned modal Escape also discard a selected result; canceling a separate command selector still cancels that selector alone.

Application checks the original buffer, revision, visiting association and live read-only state again. Focus changes cannot choose another insertion target. Local edits, undo back to identical text, external reloads and closed sources reject stale publication while keeping the proposal inspectable. An altered result cannot reuse its old payload revision. Explicit acceptance consumes its authority once and makes one ordinary native undo step, without saving the file. Shared views, source return positions and undo/redo use the native transaction. Generated bytes are preserved, including whitespace, line endings and fences; no model-supplied path, command or extra result field is accepted. The original generated payload is retained separately from the display. Org comma escaping, display line endings, titles, blocks and request metadata are never recovered by stripping markup and never enter accepted source text.

Interactive terminals

Open a shell with M-x terminal-open or modal :terminal-open. It starts in the lower panel; terminal-new-buffer opens directly in the main area. terminal-move-to-buffer and terminal-move-to-panel move the same live session. Use C-g to return to the editor and M-x for host commands while a terminal owns focus. Ordinary terminal bytes belong to its child in either startup profile.

Follow Use an Integrated Terminal for a shell/lazygit exercise, the task guide for common operations, or the terminal reference for the complete command, input, copy/paste, configuration and lifecycle contracts.

One-shot shell commands

Follow Run Shell Commands for a sort-and-undo exercise, or see the shell reference for exact commands, bounds and lifecycle.

Run M-x shell-command or :shell-command, then accept a literal command such as printf 'hello\n'. The selected shell receives the accepted command as one argument after shell.args, with stdin immediately closed and no source text.

The shell prompt retains the last 32 admitted command strings for this session; M-p/M-n recall them and restore the current draft. Cancelled or rejected input leaves history unchanged. In non-modal editing, M-! runs a command, M-\| sends the region, C-u M-! inserts output and C-u M-\| filters the region. These are exact sequences; modal Normal/Visual retain C-u motion. Linear Visual selections survive colon entry; blocks are rejected. Configured bindings use the same handlers.

Its directory is captured before the prompt: the visiting file's parent, the explicitly opened directory for unnamed buffers, or the editor launch directory. The shell inherits the editor environment. No source file is saved automatically.

One invocation runs at a time, within shell.timeout_seconds and the aggregate shell.max_output_bytes limit. Editing remains available; active-pane status shows the shell running or stopping. Completion is observed by native input polling or frame production, and a finished job leaves no shell worker or input deadline. Use shell-command-cancel or C-g in its originating editing context to cancel it; a prompt consumes its own cancellation first. Shutdown cleans up the owned process group after normal quit decisions succeed.

Completion retains exact valid UTF-8 stdout in a read-only plain-text buffer. shell-command-output visits the last retained result without automatic focus changes. Nonzero exit also retains stderr/status in *Shell Diagnostics*. Timeout, cancellation, invalid UTF-8, NUL and output overflow report diagnostics without exposing partial output as a successful result. Closed or changed output identities are unavailable; they are never recreated or overwritten by name.

Use shell-command-on-region to send the current nonempty linear selection as literal stdin data and show stdout. shell-filter-region sends the same bounded snapshot and replaces that region with complete successful stdout. shell-command-insert sends no source input and inserts at the point captured before its prompt. Select the complete document with the native mark and buffer motions for whole-buffer input. Empty, absent and rectangular regions are rejected.

Filters and insertion require the original buffer revision, file association and writable state before launch and publication. Pending file observation, reload, external disk changes and closed or edited sources reject automatic application while retaining valid stdout. Switching panes never redirects the target or takes focus. Successful replacement/insertion uses one ordinary undo step; empty replacement deletes the region, while empty insertion creates no history entry. No whitespace or newline normalization changes the stdout applied to source.

Native Git Status

C-x g opens native Status in both editing profiles, from the visiting file or selected directory and launch-directory fallback. The full canvas belongs to Git navigation while source buffers, layout and terminals remain retained. Status reads disk and Git state; it does not save an unsaved source buffer.

Tab on a path expands its exact comparison; Tab on a hunk expands its body. One path and one hunk body expand at a time. git-diff opens all retained patch lines in read-only detail, including explicit binary, rename, submodule, malformed and truncated results. g refreshes Status and the retained comparison; old detail is labeled stale until replacement succeeds. Return visits the real current file, preserving an existing modified source buffer. A deleted path or directory has no current source file to visit. q returns one presentation level.

From Refs, the native git-log command opens the exact selected ref's commit as the History root while retaining the checked current working branch. History P and V prepare cherry-pick and revert. With no ordered marks, the selected revision is the one target. a/U append/remove independent ordered marks; * keeps its separate range-base role. Each merge requires a parent number and final review shows that full parent object. y, C-Enter or C-c C-c confirms; Return does not submit. A stopped ordered request exposes the actual Git family and current revision with its retained original context and verified completed prefix.

b or y in Status opens Refs. Its independent keys.git_refs map keeps n for branch creation, S for switch, R for rename and D for non-forced deletion. Choose a ref or configured remote with Up/Down or C-p/C-n. Tab opens read-only full-name/object/type/upstream detail; Up/Down scroll and Tab or q returns to the list. Remote names remain reachable beyond the ref rows. Prompts collect new names; the explicit review shows the exact accepted name and full target. Only y accepts; Return is not acceptance, n or C-g cancels. Existing names, moved refs/HEAD, modified source buffers and dirty switch state reject. g refreshes compatible Status and Refs; failed observations retain confirmed facts. Tags show their actual object and peeled commit separately. Configured remote names are shown without exposing URL values. q returns to Status; started work retains its ownership. Changed disk files enter the existing automatic-or-ask reload policy. Retained history refreshes through the owned read worker: unchanged HEAD retains its pinned pages, while a changed HEAD starts current ancestry. Refresh failure keeps the preceding history stale and does not replay the ref mutation.

t in Refs creates a local tag. Enter a name, accept the default lightweight kind or explicitly select annotated, then accept or enter a full target object ID. Git checks the name, target and current signing policy before review. Lightweight review shows the name, kind and full target; y accepts, n or C-g cancels. A policy requiring signing rejects the lightweight choice without changing its kind or disabling signing. Select annotated explicitly to compose an annotation in the native message editor. Return inserts a newline; C-Enter or C-c C-c opens the scrollable exact review, and the same aliases explicitly accept it. q or C-g from review retains the draft. The existing keys.git_commit aliases own native message editing for both commits and annotated tags. Source publication and saving remain guarded while this transient message owner is active.

Git supplies tagger identity/date and performs configured signing. Signed annotation review includes its required final newline within the 65536-byte message limit, so the signature remains recognizable to Git. A failed tag creation preserves annotation text and actual process diagnostics. After g, start t with the retained name, explicitly choose annotated and accept the same target to recover its draft. T reviews the selected local tag's full ref object and peeled target before deletion. Creation and deletion do not publish tags; HEAD and index remain unchanged. An annotated tag retains its distinct tag object and target instead of treating both as a commit ID.

h or l l in Status opens History. keys.git_history keeps navigation separate from Status in both profiles. Tab inspects the exact selected revision; f admits one more finite ancestry page. g verifies current HEAD and preserves the pinned root, admitted pages and compatible selection; a changed HEAD requires Status refresh and explicit History reentry. Missing objects and page limits are explicit. Revision detail includes full parent IDs, raw commit metadata, exact old/new changed paths and a bounded read-only patch. Invoke git-show in detail to compare another listed full parent ID. Return on a parent compares it; Return on a changed path opens its immutable historical bytes. Deleted paths use the comparison's old object. q returns to History, then Status. A/F in History prepares amend of checked HEAD or fixup of the selected full revision; existing explicit commit review remains required. Inspection never checks out historical files or replaces current source text.

In History, * records one range base and Return compares that full base with the selected endpoint in their explicit order. a appends an exact revision and U removes it from the independent ordered set. Base changes retain revision order; sequence changes retain the base. Duplicate and excess marks reject; at most 256 ordered revisions remain retained. git-unmark removes the selected base and git-unmark-all clears both History roles. Incompatible repository/root marks remain explicit until cleared or their pages are admitted again.

l r opens Reflog; B b or B B in Status blames the selected exact path, with the visiting repository-backed source as the fallback. Blame uses checked HEAD, so unstaged or unsaved source text is not attributed as committed content. keys.git_inspect owns revision, reflog, blame and historical-file navigation: Return opens retained detail, v inspects the exact selected revision, and q returns to its originating list. Blame retains each original object, filename and line through renames; historical source visits read the exact blob without checkout or source publication. Historical bytes remain read-only and visibly bounded, including binary or truncated content. git-visit-file explicitly visits the current canonical source; existing modified buffers remain owned by the editor. A historical path with no current file reports that fact.

The keys.git map owns q, g, s/u, Tab, Return, ? and list navigation in both profiles. M-x and colon use the shared command catalog. Unmerged, Untracked, Unstaged and Staged sections appear in that order when nonempty. Clean, bare, unborn, detached, unavailable and truncated states remain explicit. Pointer selection uses a current frame and semantic path identity; display escaping never reconstructs a filesystem argument.

$ opens Processes and Return inspects the selected operation. Contextual C-g in Processes or process detail explicitly cancels that selected live operation; inside a menu or prompt it dismisses only that input owner. Escape dismisses input without cancelling a child. Each q returns one level and preserves work. Application exit identifies active Git work and requires a fresh decision before termination, alongside unsaved-source and terminal decisions. Accepted cleanup retains ownership until reaping; failure keeps the editor open. Stopping a process does not abort a Git sequence or claim repository rollback.

In Status, c opens normal commit composition directly. A following c is message text; plain Return inserts a newline. keys.git_commit inherits ordinary native editor keys in both profiles: C-Enter or C-c C-c submits, C-g or C-c C-k cancels and retains the draft. Git keeps identity, hooks and signing policy; rev never saves or stages source text implicitly. Failed or uncertain effects retain the message and actual child diagnostics in Processes. Drafts are session-only, limited to 65536 bytes per context, with bounded native undo history.

git-commit-amend prepares the observed HEAD and existing message. git-commit-fixup prompts for one revision, resolves a full immutable target and prepares its fixup! subject; retain that exact subject while editing the body. For these modes, the first C-Enter or C-c C-c opens a read-only exact review. The review shows the complete target, checked HEAD, message byte count and final-newline state; Up/Down scroll the wrapped content. Plain Return does not accept. C-Enter or C-c C-c explicitly accepts; q or C-g cancels and retains the draft. A moved HEAD or changed index rejects before the mutator. Amend preserves Git author/parent semantics; fixup creates one ordinary child commit with the standard message and does not run autosquash.

Native Git fetch

Select a configured remote row in Refs, then use & or M f, or invoke git-fetch through M-x or modal colon. M b reopens Refs. Missing selection reports its requirement instead of choosing an upstream or path. Fetch honors the selected remote's configured transport and refspecs, including the installed Git credential/helper policy. Configured pull policy does not trigger integration. The native request checks complete current refs, HEAD and its private effective configuration before launch. Changed configuration requires a new checked request.

Fetch uses git.transport_timeout_seconds and the existing aggregate output, metadata, record and session limits. Leaving Git retains owned work; cancellation and deadlines retain actual possible effects. Processes keeps safe argv, actual exit, outcome and checked local facts. Raw transport/helper and configuration output is withheld because it can contain credentials. A failed or unverifiable fetch is not automatically replayed. Refreshed tracking facts are local observations; they do not promise exclusive access against other Git clients.

Native Git push

In Refs select one local branch and invoke p / git-push, or mark it with * and navigate to a configured remote before M p. The remote selection constrains the configured upstream; it cannot replace it. The one push-source mark stays independent of index/path/hunk marks and History range/sequence marks. - clears it. A changed marked object requires clearing or marking its current object again.

Preparation requires exactly one branch.<name>.remote and full branch branch.<name>.merge, consistent with Git's observed upstream relation. Missing or contradictory tracking rejects. The native scrollable review shows the full source ref, full source object, configured remote name and full destination ref. Only y accepts; Return does not submit, and n or C-g cancels. Configuration and source facts are checked again before launch; an accepted review is used once.

Mirror push, automatic tag following, recursive submodule publication, multiple push URLs, conflicting push remotes or configured refspecs reject with a visible reason. A compatible explicit source/destination refspec is allowed. Git's push.default cannot broaden the explicit full-object refspec. The installed backend receives explicit no-force/no-expansion flags after compatible policy admission. Hooks, credentials, push signing and receiver protections remain Git-owned.

The result refreshes local facts and queries the privately captured effective push endpoint for the exact full destination. A successful child alone does not prove publication. Failed children, unavailable verification, differing remote objects and cancellation/timeout after possible effects remain distinct in Processes. Failure is never automatically retried. Recognized noninteractive credential/authentication failures get a fixed safe diagnosis. Transport/helper output and credential-bearing endpoints remain private; records retain safe argv, actual exit and checked outcomes under the existing finite transport/output limits.

Native Git integration

In Refs select one exact commit-bearing ref. = or m f chooses fast-forward-only merge; i or m m permits fast-forward or merge; I or m n requires a merge commit when Git has integration work. e or r r chooses ordinary rebase. Native review shows the selected full ref/commit, current branch/HEAD and explicit policy. y, C-Enter or C-c C-c accepts; Return does not accept. n or C-g cancels.

Integration requires complete current refs, a checked existing current branch, clean index/worktree and unchanged unmodified repository-backed source buffers. Stale HEAD/ref facts reject. Configured autostash, rebase updateRefs or branch mergeOptions which would alter the reviewed merge request require an explicit configuration revision. Requests do not save source or introduce autostash, interactive editors or executable todo actions. Git retains hooks/signing and its receiver-independent repository protections.

git-operation-status opens the read-only Git Operation view. A conflict stop shows its actual family, current/original/onto objects and available step, plus exact conflict paths. Processes reports InProgress separately from verified integration and retains the actual failed child exit. q returns to Status without aborting Git state; process cancellation also does not abort it. Changed source reconciles through the existing reload/ask policy.

Sequence metadata admits 64 ordinary files and 256 merge targets, within the existing detail, 1 MiB worker scratch and 32 MiB shared session limits. Symlinked or oversized state cannot authorize work. Snapshot publication checks sequence bytes and HEAD again. Integration uses git.operation_timeout_seconds; observation, output, record and cleanup bounds retain their existing meanings.

Conflict inspection retains full index object IDs, modes and bounded side bytes. For rebase, Current is the destination/onto side and Applied is the original commit being replayed. For revert, Base is the reverted commit and Applied is its selected parent. Missing, binary, non-text, structural and partial sides remain visible. The read-only view never replaces unsaved source text.

In Conflict, 1/2/3 prepares a complete compatible side replacement, K reviews exact deletion from disk and index, and x prepares staging of saved bytes or absence. y, C-Enter or C-c C-c accepts the exact review; n or C-g cancels it. An unsaved visiting result blocks these actions. Binary, non-text, type-change, submodule, incompatible-mode and partial observations remain inspection only. Changing the saved file, index stages, HEAD or sequence invalidates confirmation. Removing markers does not stage or continue; continue is always separate.

Conflict H uses the configured optional Pi owner with copied input only and no directory discovery or tools. Saved disk text and any visiting unsaved result remain distinct snapshots. Exact stage IDs, modes, roles and unavailable content are explicit; binary or partial content is not presented as complete text. Context exceeding the existing Git detail or AI input cap rejects as a whole. An unavailable provider leaves the manual conflict view usable. The normal read-only AI result and discard workflow preserve native source ownership. Index/file metadata and native revisions conservatively invalidate source currency; an explanation never replaces exact Git checks for changing actions.

Prepared clone and init arguments

Status C C, C s, C b and C m open regular, shallow, bare and mirror clone preparation. I I prepares init. Named clone/init commands also work from ordinary editing or a chosen file-tree directory without an existing Git repository. The native text draft contains one JSON array of literal Git arguments. Fill its empty source/destination parameters; keep its family, options and parameter positions. Shallow preparation uses depth one. Clone and init require an absent explicit destination with an existing canonical ordinary parent directory.

The shared native composer uses ordinary editor text keys in both profiles. C-Enter or C-c C-c first checks input, captures saved source state and opens exact review of the executable, literal argv, directory and destination. A second C-Enter or C-c C-c executes only that captured plan. Plain Return never accepts review. q or C-g cancels review; C-g cancels composition. No shell expansion, implicit source save, operation retry or destination deletion is performed. Status changes follow the existing observation/reload owners. Git process inspection retains bounded exit/cleanup facts; transport output is withheld to protect credentials. Failure after launch does not claim repository rollback.

Status i t and i p visit the actual .gitignore and common Git info/exclude files. Existing unsaved visiting identities stay owned; no pattern is invented.

Prepared submodule arguments

Status o a, o l, o u, o s and o d prepare submodule add, recursive status listing, update, URL sync and non-forced deinit. Fill the add metadata name, source URL and literal repository-relative path, or the selected path for update/sync/deinit. Update uses the indexed gitlink commit and explicit checkout mode. The captured path must stay inside the working tree through ordinary directory components.

The same two-step native composer opens exact executable/cwd/argv/target review. Preparation captures the parent sequence, index, saved bytes, configuration and selected child repository state. Changed evidence refuses execution. Update and deinit refuse dirty child state; unsaved repository-backed buffers protect all changing routes. Deinit also protects retained native visiting/directory owners. No force, hidden stash, save, commit or retry is implied. Listing retains its actual bounded output under git-processes; other raw configuration/transport output stays private. Successful changing results verify actual gitlinks, checkouts, URL registration or deinitialization. Relative sync URLs whose resolved value cannot be verified remain explicitly unverified after execution.

Prepared subtree arguments

Status O a/O m/O f/O p/O s prepare subtree add, merge, pull, push and split. Each route requires a checked working tree, complete refs, clean saved state, no active Git sequence and an explicit literal repository-relative prefix. Add requires an absent prefix with an existing ordinary parent. Other routes require an existing ordinary directory. Missing optional Git subtree support reports its installed availability before any changing child.

Add and pull name a source repository and one full refs/heads branch; read-only preparation pins its complete object ID. Merge names an exact local commit. Split names an explicit commit, such as HEAD, and retains its resulting full commit object and actual stdout under process inspection. Native composition, read-only preparation and exact review remain separate from execution.

Push requires an explicit repository URL or absolute path and one full refs/heads destination. Review shows that full branch and the exact argv operand used by Git subtree, which adds refs/heads itself. Configured remote names, active URL rewrites, implicit followTags and recursive publication are refused. The checked remote branch and captured effective configuration must remain unchanged through review. No force, inferred upstream or additional publication is requested.

Postchecks inspect actual branch/ref state, saved paths outside the prefix, imported and split tree objects, and the remote subtree object after push. Unsaved native sources remain protected. A real merge conflict retains Git's actual sequence and reports in-progress state; git-operation-status inspects it before a separately reviewed continuation or abort. Failures preserve uncertainty and never retry, clean up or claim rollback automatically.

Prepared notes arguments

Status T a/T r/T p prepare notes add, remove and prune. Fill one full refs/notes name and an explicit existing target object for add/remove. Add also requires a literal nonempty message; it refuses to overwrite an existing note. Preparation resolves the full target ID and captures the exact target-to-note map and Git configuration. Prune review lists the full missing-object targets returned by Git's read-only dry run. A changed ref, note map, prune set, saved source or configuration invalidates review before execution.

Execution verifies the exact resulting note map. Add checks the actual note blob against the reviewed message after Git's normal whitespace cleanup; remove and prune must preserve all other notes. HEAD, unrelated refs and saved index, working and untracked bytes stay checked. Bare repositories support the same notes operations through their actual Git context. Successful add reports the full note blob ID. Process inspection owns actual exit/cleanup facts; failed postchecks remain explicitly unverified.

Prepared sparse-checkout arguments

Status > e/> d/> r/> s/> a prepare enable, disable, reapply, set and add. The routes require a checked clean working tree, complete saved/index/ref state, no active sequence and no unsaved repository-backed buffers. Enable and set select cone mode without sparse index compression. Set/add accept one or more literal repository-relative directory arguments after --. Paths must use ordinary components outside .git. The reviewed --skip-checks option permits literal pattern metacharacters after native path checks. Git cone patterns cannot represent a newline directory, so that input refuses before execution. Raw supported path bytes remain exact at the Git owner; native JSON text supports ordinary Unicode paths without shell or glob expansion.

Review captures effective configuration, the selected worktree's private sparse patterns, complete index flags and actual materialization. Existing enabled non-cone patterns or inconsistent materialized excluded files refuse these prepared routes. Reapply/add require enabled cone mode. Parent selections absorb redundant child directories according to Git's cone selection.

After execution, checks inspect the actual cone configuration, selected directory list, index skip flags and tracked-file presence. HEAD, index objects, saved changes and unrelated configuration remain checked. Linked worktrees retain separate pattern and materialization state. No force, implicit save/stash, automatic cleanup, retry or rollback is performed. Plain Return and cancellation follow the same native argument composer contract as other prepared families.

Prepared patch and request output

Status W c/W s/W r prepare format-patch, saved diff and request-pull output. These drafts contain a JSON object with an arguments array and an explicit output path, for example {"arguments":["diff","--binary","--full-index", "--no-ext-diff","--no-textconv","--no-color","HEAD~1","HEAD","--"], "output":"review.diff"}. Relative output names resolve against the captured repository root. The destination must be absent, with an ordinary canonical parent outside Git metadata. Existing entries are never overwritten.

Format-patch requires one local BASE..END commit range; saved diff requires two local commit expressions. Preparation freezes full IDs and disables replacement objects. Binary/full-index output permits real Git mailbox/plain-patch consumers. Only saved commit state is exported; an unsaved native source stays owned and is not saved implicitly. A bare repository can supply the same checked commit range.

Request-pull requires an explicit repository URL or absolute path, a local start commit and one full remote refs/heads branch. Its end parameter can also use LOCAL:REMOTE to select a different local commit expression. The remote branch must already name the reviewed local end commit; this route does not publish it. Active endpoint URL rewrites refuse preparation. Request text is saved locally; no mail is sent.

The shared owner captures complete output during read-only preparation. Review shows the exact executable/mode/cwd/argv, destination, byte count and Git blob hash of the captured bytes. This hash does not write an object to the database. A separate acceptance regenerates the output and requires exact byte equality, unchanged source/configuration and the same published request-pull anchor. Output exceeding the existing detail/scratch or aggregate process limits rejects as a whole. No partial export file is presented as a complete result.

File publication reuses the existing owned staging lifecycle through a captured directory descriptor and an atomic hard link that cannot replace another entry. Postchecks read the actual saved bytes. find-file visits the explicit output; process inspection retains the actual producer's exit/cleanup facts. Changed review evidence refuses execution. Failed writes preserve uncertainty and never retry, delete the chosen destination or claim rollback.

Prepared local patch application

Status w p/w a prepare plain patch and mailbox application. Fill the final argument with one explicit local input file. Preparation captures complete ordinary file bytes, identity, effective configuration, HEAD and saved sources. Review shows the input path, byte count and blob hash alongside executable, cwd and literal argv. The actual child consumes the captured bytes through sealed stdin; input paths are never shell expressions. Symlinks, partial or oversized input, dirty tracked state and unsaved repository-backed buffers refuse the route. Existing untracked sources remain checked. A complete existing HEAD and no active Git sequence are required.

Plain application uses Git apply --index --binary against both index and saved files. After acceptance, Git independently applies the same bytes to a private index and derives an expected tree; the actual index tree and materialized files must match. Ordinary abbreviated patch headers and binary patches are supported. HEAD and other refs remain checked. There is no implicit commit.

Mailbox application uses explicit mboxrd decoding, UTF-8 messages, no three-way fallback, added signoff, message ID or scissors stripping. Git retains its configured signing policy; unavailable signing remains an actual failure. After acceptance, installed Git splits and decodes each message in an exclusively owned workspace. Sequential private-index application derives expected trees. Actual commits must form the exact single-parent chain from the captured HEAD, with those trees and decoded authors, author timestamps and messages. An input From commit label is not semantic proof. Hooks still run; changed hook results remain unverified even when Git exits zero.

Complete input and decoded files retain the existing detail/scratch admission; mailbox envelope count is at most min(max_refs, 256). The private workspace has only declared producer names and stays owned by active/retained child cleanup. Unknown entries or substituted paths are preserved. Existing process time, output, cancellation and cleanup limits apply. Private object derivation starts only after explicit acceptance and may write blob/tree objects before the real mutator. No repository index or saved-file rollback is attempted.

An actual stopped mailbox retains Git-owned progress and already-applied commits. git-operation-status inspects that state under the existing metadata bounds. No automatic continuation, abort, retry or provenance-based success is inferred. Return and cancellation follow the same prepared argument contract.

Direct Git and explicit shell commands

! in Git navigation opens git-run-command. Edit the JSON argument array, for example ["branch","topic","HEAD"]. Git receives those arguments directly, including empty operands and exact supported path bytes. The native composer accepts Unicode JSON text; engine callers retain raw OS arguments. No shell parsing, quoting removal, globbing or substitution is performed by the editor. Git retains its own option, alias and helper semantics.

M-x git-run-shell-command selects shell mode explicitly. Its JSON array has one item containing the complete shell string, for example ["printf 'one\\n' | tr a-z A-Z"]. It reuses the existing shell-command program selection: shell.program when configured, otherwise startup SHELL or /bin/sh; shell.args precede the accepted command unchanged. Pipes, redirection and substitution are shell behavior in this explicitly selected mode. No document or region text is sent to either direct route; stdin is closed.

Preparation observes only the captured directory and available checked Git context. It does not execute or classify the arbitrary input. Review shows executable, mode, canonical cwd, accepted argv/input and limits. C-Enter or C-c C-c first prepares this review and a separate acceptance starts execution. Return does not consent, and q or C-g cancels a review while retaining source windows. Named commands also work from ordinary editing and chosen directories. When Git is hidden, an existing compatible context for the source directory is retained; no repository identity is invented for an ordinary directory.

Direct input retains the 64 KiB native draft and final argv limits: 64 complete tokens including executable/prefix, at most 4096 bytes each and 64 KiB total. Shell text is one nonempty UTF-8 command within 4096 bytes. Shell execution uses the smaller existing Git-operation and shell time/output limits; configuration is startup-only. All file-backed buffers must have saved text before accepting an arbitrary command because its filesystem targets cannot be inferred. Captured source/index/HEAD/configuration or directory changes invalidate review.

Both routes use the existing Git operation, process-group, cancellation, diagnostic and retained-cleanup owner. They exclusively retain Git admission across known repositories until child cleanup finishes. Leaving a presentation does not cancel work; git-process-cancel selects the actual owned operation. git-processes remains invocable when Git is hidden. Its detail retains the real child argv, exit and bounded stdout/stderr through the existing escaped, credential-redacting presentation. Output is inspection data and cannot become another command or an automatic source edit.

Arbitrary Git postconditions stay unknown even after exit zero. Actual child failure, cancellation, timeout and output-limit facts remain visible. Compatible Status is refreshed after possible effects; an unavailable or changed repository identity preserves the last confirmed observation with failed freshness. No automatic retry, inferred safe effect, rollback or repository recreation occurs.