Scope and defaults

Runtime and invocation

The executable is rev. It runs in a terminal and accepts zero arguments or one file or directory path. With no path it opens an unnamed *scratch* buffer. A nonexistent file path opens an empty visiting buffer without creating disk entries. An explicit directory target opens its visible, first-level-expanded tree. Otherwise the tree starts hidden unless configured visible; file visits use their parent as the automatic root, or launch cwd under the explicit cwd preference. A chosen directory root takes precedence and survives later file visits.

Linux terminals are the primary target. Ordinary execution is offline and uses compiled-in defaults unless startup configuration supplies supported overrides. Terminal input states the keyboard reports and Escape behavior.

Editing views show absolute logical line numbers with current-line emphasis and a stable four-digit minimum field. Numbering does not change text columns, copied data or saved bytes. Narrow views preserve their text area.

Native mouse support starts enabled: primary text clicks focus/place point; tree entry clicks select and activate by default. Set mouse.tree_activate_on_click = false for selection/focus only. The wheel scrolls the pointed pane or tree without changing keyboard focus, and a primary drag selects canonical text with bounded source-edge autoscroll. Use M-x mouse-mode to toggle only this session. The startup step is three logical rows; terminal input documents supported reports, cleanup and terminal-owned selection bypass.

Editing profile

editor.interaction_profile = "non-modal" is the default, with Emacs-like editing: ordinary text inserts directly. Choose "modal" for Vim-like Normal, Insert, Replace and Visual editing. Restart after changing it; the profile is immutable for the session and has no command or language override. Modal editing starts in Normal. Use i/a/I/A/o/O to enter Insert and Escape/C-[ to return to Normal. The binding reference lists the currently implemented state commands. Invalid profile or keymap settings reject the whole candidate into complete non-modal defaults. Follow Choose Modal Editing for a small startup and editing exercise.

Shell command preferences

These global preferences are frozen at startup. Commands run only after explicit native invocation and accepted command input. The shell reference defines stdin/stdout, checked publication and cancellation; the User Guide shows a sort-and-undo exercise.

Git preferences

These global preferences are frozen at startup. Loading them does not discover a repository or launch Git. All values inherit by leaf through ordinary includes; an invalid source or complete candidate selects the complete built-in defaults.

All Git capacities, including temporary replacements and parser scratch, also share a fixed 32 MiB editor-wide admission budget. At most four repository contexts remain retained. Reached admission preserves existing observations and active ownership. Count preferences cannot override these hard limits.

Interactive terminal preferences

These global preferences are frozen at startup and separate from one-shot shell commands. Loading configuration does not launch a terminal process. Arguments remain structured values; no command string or implicit -c is added.

The terminal reference explains these startup fields, live-session admission and the separate shell-filter settings.

Startup configuration

The complete English reference sample contains every supported global default, all active RGB roles and the profile, state and local context maps. Its optional include, language and association examples are commented out. First startup installs these complete defaults; a customized file may retain only the overrides you need.

The executable reads $XDG_CONFIG_HOME/rev/config.toml once before creating buffers or input owners. An unset, empty or relative XDG_CONFIG_HOME uses $HOME/.config/rev/config.toml; HOME must be absolute for that fallback. Data, state and cache locations resolve independently through their XDG variables with HOME defaults .local/share/rev, .local/state/rev and .cache/rev. When no entry exists at the configuration path, normal editor startup creates only its missing parents and the complete packaged sample, then validates it through the ordinary loader. It does not need installed reference files or a checkout. Data, state and cache directories remain absent.

Command ranking loads the existing user-wide state window without creating a file or directory. After a named invocation it may create the state root and save the latest 256 invocations to command-history.toml. This fixed usage window is separate from the configured distinct-name M-p/M-n history below. See Command usage state for the versioned format, 64 KiB bound, concurrent publication and nonfatal failure behavior.

Publication exposes a complete synchronized file without replacing a concurrent winner. Every existing entry is preserved, including empty/invalid files, directories and dangling symbolic links. Pure location, parsing, loading and preparation helpers remain read-only. A provisioning failure shows its operation and source in Configuration: ... and retains complete usable built-ins.

A present unreadable or invalid source shows Configuration: ... in the echo area and uses complete built-ins, including palette, formats and bindings. Diagnostics identify the source and key, with a line/column when available. Fix the source and start a new session to apply it. No settings from a rejected candidate become active.

For example, this TOML overrides indentation, literal-tab display and one editor binding; all omitted settings and independent aliases retain their defaults:

[editor]
indent_style = "spaces"
indent_width = 2
tab_width = 8

[keys.editor]
"M-j" = "next-line"

Sources use TOML 1.1, schema version 1 (also when omitted). Optional top-level include = ["editing.toml", "colors.toml"] loads paths relative to their declaring source in order, before the parent's leaves. Only explicit includes participate; project-local files and variable-looking paths receive no implicit discovery or shell expansion. Every source and the merged candidate validate before use.

The session retains one immutable snapshot, including policies for buffers opened later. Editing or deleting a source does not change the running session; restart to read it again. Existing files retain their observed BOM/newlines, while new buffers use configured format defaults. Bindings, syntax, prompts and tree preferences describe the existing configurable owners.

Source precedence and limits

Settings resolve in this order:

1. Compiled built-in defaults.
2. Explicit includes, depth-first in declaration order. Each child's includes apply before that child. A later sibling source overrides an earlier sibling.
3. The declaring source's own leaves, with the selected user root last.
4. The selected language's editing leaves, after all global layers.

Only explicitly present leaves override earlier values. False, zero and empty arrays are values; an omitted leaf or empty concern table inherits siblings. Arrays replace rather than append. Maps merge by key, and keymap layers replace an earlier spelling by normalized sequence identity. Includes are source-local traversal metadata, not a merged list used for another discovery pass.

Relative include paths resolve against the declaring source's selected path; absolute local paths are also accepted. Tilde, variables and shell expressions are not expanded. A source can be included more than once outside the active stack; each occurrence counts toward the limits. Symlink/hard-link aliases on the active stack are cycles and reject. Limits are fixed, not configurable:

Sources must be regular files. Explicit read-only loading of an absent optional root is silent; native startup first attempts provisioning as described above. A missing explicit include, directory, unreadable file, invalid UTF-8, malformed/duplicate TOML key, unknown option, wrong type, invalid bound/color/enum or conflicting keymap rejects the complete candidate. A bad included value cannot be hidden by a later valid override. The editor remains usable with complete built-ins and one source/key diagnostic. No settings source is executed or repaired; creation is confined to the absent implicit root during normal startup.

See Native Org controls for capability, command, context, preference and palette coverage.

Configuration value catalog

The tables below and the Org configuration catalog together describe every accepted schema leaf or map. All settings are read once at startup. Global values apply throughout that session; the four language.<id> leaves are the only language overrides. Integers and finite floats have distinct types; use 0.5, not 0, for a float share. Widths describe terminal display columns/cells, never bytes or Unicode scalar positions.

Org heading presentation

Source positions and the original separator/title remain canonical. With org.indent=true, pretty presentation preserves source-prefix cells within the added visual margin. With org.indent=false and hidden leading stars, it collapses those cells so all heading markers start at the left margin; showing source stars restores their literal width and can change wrapping. The org.indent preference adds visual margins to headings and their body text; see Org configuration. Use org-indent-mode, org-indent-enable or org-indent-disable to override it for one live buffer without writing TOML. All its views share that choice; closing discards it. Literal or unverified prefixes remain source. Heading recognition remains active with syntax coloring disabled, but respects org.enabled. The terminal owns font coverage and shaping; use pretty = false or simpler one-cell markers when a symbol is unavailable. rev installs no fonts and does not rewrite programming operators to imitate ligatures. Use org-pretty-headings-mode to override only the active view's pretty flag; org-reset-heading-presentation returns to its immutable startup value. Both use M-x or modal colon and leave this configuration unchanged.

Source metadata and maps

Only the fixed implemented commands and context actions are accepted as keymap values. No value unbinds a key or supplies code or consent. Sequences contain 1..=8 normalized chords. The conservative terminal aliases, reserved C-g, prefix conflicts and stage admission rules apply to every layer. The sample declares the complete default targets explicitly; omit its key tables to inherit native stage-specific distinctions, or copy only desired overrides.

Line numbers

Startup values initialize each editing view. Runtime gutter commands change only that view's overrides and never reload or write this snapshot.

The gutter reference describes fixed bookmark symbols and outside placement. Its migration guidance covers ignored legacy bookmarks.marker strings and explicit old palette colors.

Mouse controls

Optional Pi transport

Optional server transport

Each lsp.servers.<name> entry declares languages (nonempty language array), command (nonempty executable), args (literal string array), root_markers (relative marker paths without traversal), initialization_options and settings (finite JSON-compatible TOML data). New entries need command and languages after source inheritance. Empty argument/marker arrays explicitly replace earlier values. env is a literal string map, empty by default, merged by key across includes. It overrides the inherited process environment only for that server. Admit at most 64 entries, 128-byte nonempty names without NUL or =, 8 KiB per value without NUL, and 64 KiB total name/value bytes. Diagnostics omit values. An explicit lsp.preferred.<language> selects one compatible server or false for native-only. Otherwise the first matching server name in lexical order wins. No grammar allowlist, download, environment expansion or shell evaluation applies.

Root lookup chooses the nearest configured ancestor marker. An explicitly opened containing tree bounds lookup and supplies the fallback; files outside that tree fall back to their own containing directory. Empty marker arrays use that directory. Canonical roots share a single process across file aliases. Queues retain at most 64 messages and 16 MiB per direction; stderr retains a separate 64 KiB tail. The transport negotiates UTF-8/UTF-16 and requires document open/close plus full or incremental sync to admit an unsaved document. Eligible visiting buffers publish unsaved text through didOpen/didChange and retire it through didClose; synchronization never saves a file. Successful saves send only the negotiated save notification. Wire columns count encoding units, with canonical transaction ranges used before each incremental mutation. Split views and canonical file aliases share one document. Documents admit at most 8 MiB each and 32 MiB total; larger buffers stay editable and retain native fallback within its own source limits.

lsp-disconnect excludes the current canonical buffer across all its views until lsp-connect restores eligibility or the buffer closes. Other attachments retain their connection. Restore never enables globally disabled LSP. Reopening or restoring advances document generation; undo and equal bytes with a new revision cannot reuse old synchronization evidence. Missing or failed servers remain unavailable until lsp-restart or disable/enable. Restart replaces the eligible current root while preserving other roots and exclusions. lsp-status reports transport readiness. Admitted semantic results use the native popup; empty, unsupported or unavailable results use native fallback. Selected resolve and same-document imports publish with the primary as one undo transaction. See Language servers for the protocol profile, edit limits and finite lifecycle.

Editing, presentation and retention

Indentation, tab display, syntax and retained history use each buffer's policy across shared windows. Startup source changes do not update existing or later buffers in that session. A successful rename or published write-file reassociation re-evaluates language preferences from the same snapshot; a failed or canceled path change retains the old policy. Reassociation never converts text or resets history, revision or saved-state identity. Rectangles retain copy versus kill tab semantics across source/destination policies.

Language rules

Association keys are literal basenames or a leading *.suffix, including compound suffixes. Other wildcards, separators and controls reject. Matching is case-sensitive: any user match precedes all built-ins; within each class, exact basename wins, then the longest suffix. Recognition uses the visiting basename, retaining the first alias when canonical reuse finds an existing buffer; unique buffer-label suffixes do not participate. No language table is required for an identity. Unmatched or unnamed text is plain; Rust, C, Go, HTML, CSS, JavaScript, TypeScript, TSX, JSON and TOML identities default to their bundled grammars. A complete external table replaces its registration as a unit when layers override it. Assets are optional and user supplied; see external grammar assets for admission, query captures, trust and restart requirements. .tsx retains the typescript preference identity while selecting its TSX parser. Other identities can use indentation without a parser, or explicitly select an admitted grammar.

Palette roles

Every value is a string of exactly #RRGGBB with six ASCII hexadecimal digits; hexadecimal letter case is accepted. Each present leaf overrides only that role. All palette roles are global, with no language-scoped color override.

Selection takes precedence over search, which takes precedence over syntax; row boundaries reset colors/attributes. Unknown syntax groups inherit document foreground. A nonempty NO_COLOR suppresses RGB and retains selection reverse video/search underlining. Terminal true-color fidelity, intercepted key reports and cursor OSC support remain terminal capabilities. Cursor color is untouched for unknown terminal families or NO_COLOR; normal/error/unwind cleanup resets an attempted cursor color to the terminal default. It does not reconstruct a previous application's cursor color. See Terminal input.

Command, panel and file-completion flows

• M-x keeps a query above a bounded vertical command list, with selection, Tab completion and separate M-p/M-n session history. Return invokes the selected or exact/nonempty matching command once; C-g cancels.
• Editing panes, tree and completion rows share composition rules. The tree has no editing-window identity, so C-x o cycles editing panes only. Candidate rows borrow space without scrolling retained document views; tiny/zero geometry retains prompts, selection and view identities. No panes are created by completion.
• Find-file starts at the visiting file's parent, otherwise a chosen directory or launch cwd. Tab completes the highlighted full path, initially the first suggestion, and keeps the prompt open. Return accepts a directory as its expanded tree context. Return uses an explicit selection, otherwise the freely typed filename, including a new name. Canonical aliases reuse dirty buffers; new names remain in memory until save. Errors retain the draft and original buffer. Observation is bounded to 4096 entries/512 KiB per component and never creates files or traverses child symlinks recursively. Rendering/filtering reuse the retained snapshot.

The sample and consistency checks establish schema/default agreement. Parsing a sample does not prove rendered colors, physical key availability, interaction geometry or runtime acceptance; those have separate native and terminal checks.

Text and files

Each editing window retains its own point and viewport and references shared buffer text. Closing a window retains buffers; closing a modified buffer asks for save/discard/cancel. Closing the final buffer creates a fresh empty buffer.

History and retained text

Undo/redo belongs to each buffer. Adjacent ordinary typing groups until another command or save; paste, accepted replacement, region kill and rectangle edits form coherent units. A new edit after undo discards redo. Saving retains history and records the current logical clean state; undo/redo can return to it. History retains up to 512 groups with a soft 64-MiB fragment budget, always retaining the newest complete group. Pruning must not make different text clean.

The linear ring keeps 32 entries. Consecutive directional kills append/prepend in document order; intervening commands break coalescing. A yank-pop applies only to the current yank sequence and its owning view. Resize alone preserves that sequence. Rectangle rows use a separate store. Copying short source lines adds no absent trailing text; insertion adds only required prefixes and rows.

Search is literal and does not wrap implicitly. A query without uppercase characters ignores Unicode case; uppercase queries match case-sensitively. Search cancellation restores its starting view. Accepted query-replace occurrences are independent undo steps. See Search and replacement.

Explicit tabify/untabify commands convert only the admitted marked region. Loading settings and changing Tab insertion policy never retabulate existing text.

Interaction bounds

Prompt input is bounded at 4096 Unicode scalars, with whole-payload rejection instead of truncation. Command history retains up to 128 distinct accepted names in session memory. File/buffer arguments and decisions own input until accepted or canceled. Return and pasted text cannot grant save/delete consent.

A separately reported Escape has a 100-ms Meta deadline; C-g cancels the active interaction. Tiny or zero geometry retains text, views, pending input and history while suspending/clipping presentation. Normal editing panes need three text columns and a text/status row pair. Each split reserves one shared separator cell on its split axis; nested splits use their combined minimum. Separators use continuous Unicode lines and connected junctions, without an outer frame around each pane. The tree hides below 32 terminal columns and uses at most 24 columns or one third of the frame when shown.

Product boundary

Native mode activation includes .org and .org_archive files, with native Org source coloring. Rust, C, Go, HTML, CSS, JavaScript, TypeScript/TSX, JSON and TOML use ten bundled parsers and native completion. Org uses its native structural contexts. Explicit external grammar assets can admit another language or replace bundled syntax. Failed admission retains bundled syntax when available; unsupported identities and syntax failures retain editable plain presentation. TOML startup preferences configure existing actions. This version has no plugins, macros, package runtime, LSP, automatic indentation, OS clipboard bridge, regex/project search or session persistence. The command catalog describes the implemented editing subset.

Use Bindings, Focused prompts, Failure recovery and File tree for exact behavior.