summaryrefslogtreecommitdiff
path: root/docs/helix-keys.md
Commit message (Collapse)AuthorAge
* The guide walks a newcomer through pardes day to day, and the cheatsheet ↵Gabriel Schneider27 hours
| | | | | | says what Esc and Shift-Esc really do Co-Authored-By: Claude Opus 5.5 <[email protected]>
* ThemeSel is Themes and FontSel is Fonts; the old words still work in init ↵Gabriel Schneider27 hours
| | | | | | | | | | | | files and dumps The user asked for the plainer words. Every use is renamed: the builtins, leader paths, /commands, the docs and tutor, tests, and the themesel golden, re-recorded. An init file's ThemeSel or FontSel runs the new word and says `ThemeSel: renamed to Themes`, as ColumnTags is said; a dump naming an output pane by the old word restores it. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Recent lists the files opened lately, closed ones too, and a jump back to a ↵Gabriel Schneider27 hours
| | | | | | | | | | | | | | | | closed file reopens it A file closed by accident, its path forgotten, could not be found again: the jumplist dropped closed panes. Every file opened (a look, a Save of a scratch, a Restore, a rename) goes first in a list of 200, kept once, its dot noted when it closes, kept across sessions in $XDG_STATE_HOME/pardes/ recent. `Recent` (SPC f r) shows it in a reused +Recent, each row `path:line:col open|closed` a look reopens; /recent reads `open|closed <path>`. The jumplist keeps a closed file's entries, +Jumps marks them `(closed)`, and Back to one opens the file at its place. acme has no such thing; its dump and Load are the nearest. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* A column can be empty, as acme's can; new panes go where acme's ↵Gabriel Schneider27 hours
| | | | | | | | | | | | | | makenewwindow puts them Newcol makes an empty column; closing a column's last pane leaves it empty with the keyboard on its tag; Delcol and Joincol alone take a column away; the session's last pane closing quits. The +New stand-in and replaceStillborn / stillborn_joiner are gone. Every new pane goes through exec.placeNew, which follows acme's makenewwindow (active column, empty column whole, blank space, halving the biggest) or, with Placement pardes, the old rules. ColumnTags is gone: column tags are always shown. A grip drag shows acme's box cursor. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Zig has textobjects: helix's query, ported to the zig grammar pardes buildsGabriel Schneider27 hours
| | | | | | | | | | | | | | | pardes builds maxxnino/tree-sitter-zig, whose node names are not those of the grammar helix's query targets, so the query is ported by hand (vendor/queries/zig, its MPL header saying it is modified and how): a function is a Decl holding an FnProto and a Block with pub beside it, struct/enum/union one ContainerDecl, parameters and arguments ParamDeclList and FnCallArguments, and comments come in three kinds. That grammar's comments take their line's newline, and a node ending in a newline is now taken without it, as helix's grammars have it. The replay test gains fifteen Zig cases from the installed hx; none walks call arguments, which the reference helix counts as parameters and 25.07.1's query does not. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* ]f, mif and the other textobject keys use helix's own queriesGabriel Schneider27 hours
| | | | | | | | | | | | | | | helix's textobjects.scm for pardes's grammars are vendored in vendor/queries under MPL-2.0, each with a header naming its source and what it inherits, inlined; a README says what is there and what is not. syntax.objectAt and objectNext run them over the file's kept parse, with their #eq? and #match? predicates, for ]f [f ]t [t ]a [a ]c [c ]T [T ]e [e ]x [x and mi/ma with f t a c T e x. erlang's and zig's queries do not compile against the grammar versions pardes builds and are left out; fortran, markdown and powershell have none in helix. A test replays sixteen Python and JSON cases whose results were taken from the installed hx, and another holds that every vendored query compiles. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* A selection's other ranges live out of line, made at the second range and ↵Gabriel Schneider27 hours
| | | | | | | | | | | | | | freed at one The ranges beside the primary were an inline array in every Text, which at 1024 grew each pane by about 60 KiB. They are now allocated when a second range appears (Text.reserveSels) and given back when the selection is one range again (Text.dropSels); a column's or the workspace's tag allocates from Text.gpa, any other text from its pane's. A refused tag edit restores them by copy. The Pane size budget is back to 128 KiB, and a test holds that a single cursor allocates nothing for them. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* The git change jumps are marked deferredGabriel Schneider27 hours
| | | | | | | ]g/[g/]G/[G need a diff base per file that pardes does not keep; the design is agreed to wait, and section C says so. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* The keys doc's skipped list says what is still open and whyGabriel Schneider27 hours
| | | | | | | The two rows left for design, the tree-sitter textobject jumps and the git change jumps, now say what each is waiting on. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* gw labels the words in view and jumps to the one whose label is typedGabriel Schneider27 hours
| | | | | | | | | | | | helix goto_word: the words of two or more word characters between the view's first and last lines get two-letter labels, nearest the cursor first, one forward and one back in turn (modal.jumpWords). The next two keys choose one and select it, stretching the selection to it in select mode; any other key takes the labels away. The words live on Pane.jump, and renderBody paints their labels over the body's cells in the selection colours, the one change on the render side. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Z arms the view keys until Esc, and zm puts the cursor's column mid-viewGabriel Schneider27 hours
| | | | | | | | | Z is helix's sticky view mode: the z keys stay armed after each until Esc, which leaves the mode and does nothing else (no pane hop). zm is align_view_middle: an unwrapped view scrolls sideways so the cursor's column is in its middle. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Tab after text leaves the syntax node in insert mode; Shift-Tab indentsGabriel Schneider27 hours
| | | | | | | | | | | helix smart_tab: in insert mode, Tab where text precedes the cursor on its line moves past the end of the node the cursor is in, the parent-node end of Alt-e; in leading blanks it indents. Only where the file has a grammar: the reference pins smart tab off, which a file without a grammar agrees with, so there Tab still indents. Shift-Tab is insert_tab, and the differential harness now reads the S- modifier. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Insert Ctrl-s commits an undo checkpoint mid-sessionGabriel Schneider27 hours
| | | | | | | | helix commit_undo_checkpoint: u after the insert session goes back to the text as it was at Ctrl-s, a second u to before the session. It pushes an undo snapshot where the session stands. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Alt-u and Alt-U undo and redoGabriel Schneider27 hours
| | | | | | | helix's earlier/later walk its history tree by time; pardes's history is a line, where earlier and later are undo and redo, so the keys are aliases. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* g. goes to where the last edit endedGabriel Schneider27 hours
| | | | | | | | | | helix goto_last_modification: every range moves to the end of the last change (the start of a deletion, the end of an insertion), extending in select mode. The position is kept on the Text in surface rows, set where setEditText hands a body its new text, so a terminal's typed text has one too and moves with its scrollback. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Alt-o, Alt-i and the other tree-sitter keys walk the file's syntax treeGabriel Schneider27 hours
| | | | | | | | | | | | | | helix's expand/shrink, previous/next sibling, all siblings, all children and parent-node end/start (Alt-o/up, Alt-i/down, Alt-p/left, Alt-right, Alt-a, Alt-I, Alt-e, Alt-b; Alt-n stays the new terminal) walk a whole-file parse the file keeps (File.node_tree), made on the first such key after an edit and reused until the next, never per key. syntax.walkNodes follows helix's TreeCursor over every node, anonymous ones included, and Alt-i goes back to what Alt-o grew from while the selection still holds it. The harness runs without grammars, so the cases prove the plain-text no-op; a test replays eleven JSON walks whose results were taken from the installed hx. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* K and Alt-K keep or drop the ranges a regex matches in; Alt-: turns every ↵Gabriel Schneider27 hours
| | | | | | | | | | | range forward K and Alt-K share the s/S prompt, which now carries a mode rather than a split flag: a range stays when a match starts inside it (K) or when none does (Alt-K), the primary becomes the first, and keeping none leaves the selection as it was (helix keep_or_remove_matches). Alt-: is ensure_selections_forward. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* A selection holds up to 1024 ranges on the desktop, 64 on the boardGabriel Schneider27 hours
| | | | | | | | | | | The limit was 64 everywhere, which helix-golf's enumerate_and_align outgrows (%s |\d+ makes 121 ranges). It is now memory.limits.selections, per platform, and the counts that hold it are u16. The ranges stay inline in each Text, so a pane grows by about 80 KiB on the desktop (three texts and the regex prompt's snapshot); the Pane size budget in Terminal.zig moves from 128 to 160 KiB and says why. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Q records keys into a register and q types them again; . repeats the last insertGabriel Schneider27 hours
| | | | | | | | | | | | | Macro.zig keeps keys to be typed again. Q records into @ (or "<reg>) in helix's key notation until the next Q; q replays a register's keys count times through the modal handling, where Esc does not hop panes and Enter, Tab and Space neither look, execute nor open the leader. . replays the normal command that entered the last insert session once and what was typed in it count times (helix repeat_last_insert). a at the end of the text now adds the newline helix's append_mode does, which a terminal's text does not. helix-golf's invert_dictionary passes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* $ keeps the selections a shell command exits 0 on, and line end is glGabriel Schneider27 hours
| | | | | | | | | | | | | $ was a second key for line end, which helix never meant: in helix it is shell_keep_pipe. It now arms the pipe prompt with a $ marker, runs the command once per range with that range's text on stdin, and keeps the ranges it exits 0 on; the primary stays if kept, else the last kept range takes over, and keeping none changes nothing. The runner's answer is all or nothing, so the command runs in a subshell whose status is echoed as its output. Line end stays on helix's own gl and End; the snapshots, tutor and docs that pressed $ for it press gl. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* The helix-golf steps that walk search hits are waived, so hxgolf can passGabriel Schneider27 hours
| | | | | | | | reverse_golf_example from ""N on needs *, N and n to walk the search register; in pardes those keys are the acme look ring, by decision. The seven steps are pinned in golf-waivers.jsonl, so a new mismatch stands out. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Every range lives through insert mode, carried through each editGabriel Schneider27 hours
| | | | | | | | | | | | | | Insert mode dropped the selection on the first key and restored only the primary's appended-over span on Esc. Now each insert-mode edit is made at the bare cursor as before, and the range is then carried through it with helix's Range::map rules: typing slides an i range and stretches an a range, Enter (which now also drops the blanks before the cursor, as helix does) slides or stretches by what the cursor moved, and an arrow collapses. The replay gives every other range the same. Esc after a pulls each range's end back by one (helix restore_cursor), which replaces Text.append_at. The wiX-edit-drops-sel and msel-append waivers are gone. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Registers hold a value per range, and "<reg> names oneGabriel Schneider27 hours
| | | | | | | | | | | | | Registers.zig replaces the one yank buffer: every register keeps a value per range, y fills them in document order, and p, P, R and insert Ctrl-r put value i at range i, repeating the last (helix paste_impl). "<reg> names the register for the next command; _ swallows, # numbers the ranges, . is each range's text, % the file's name, / the last s/S pattern, and + and * are the system clipboard through the ClipYank and ClipPaste paths. SPC y now writes + alone, as helix's does. The acme chords and a paste into a terminal take the default register joined by newlines. The msel-yank-paste waiver is gone. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* The two regex waivers are gone: s and S already match helix thereGabriel Schneider27 hours
| | | | | | | | | s and S search each line as its own haystack, so ^ and $ hold at every line and . never takes a newline, which is helix's multi_line regex. The waivers for the old difference, sel-regex-caret and sel-regex-dot-newline, had gone stale, and --strict stopped on the first before printing its summary. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* & aligns the selections into columnsGabriel Schneider27 hours
| | | | | | | | | | | helix-golf's enumerate_and_align ends on %s |\d+<ret>&. align_selections treats the k-th range of each line as column k and puts spaces before each range until its head reaches the widest head of its column, measured in display cells, which File.rawDisplayCol already gives. A range over several lines refuses, as in helix. The example itself still needs more than 64 ranges, which the selection model does not hold. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Backspace in a line's leading blanks goes back to the previous indent stopGabriel Schneider27 hours
| | | | | | | | | | helix's delete_char_backward dedents: when everything before the cursor on its line is blank, it deletes back to the previous multiple of the indent width, a whole unit when already on one (a tab before the cursor still goes alone). pardes deleted one space, so O<backspace> under an indented line left three of four, which is where helix-golf's function_into_class ended up. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Alt-( and Alt-) rotate the text of the selectionsGabriel Schneider27 hours
| | | | | | | | | | | helix-golf swaps keys and values with rotate_selection_contents (webS_to_ <ret><A-(>, then per line). Each range's text moves to the next range (the previous one for Alt-(), in one edit; a count rotates by that many ranges, each range comes back over the text it now holds in its own direction, and the primary follows its text. That is the harness's helix; 25.07.1 read the count as a group size and left the primary alone. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Alt-J joins lines and selects the spaces it put inGabriel Schneider27 hours
| | | | | | | | | | helix-golf's text_into_array turns lines into an array with %<A-s>ms"<A-J>i,: join_selections_space joins like J and leaves one cursor on each space it inserted. J and Alt-J now make one edit over every range, as helix does, rather than J being replayed per range; that is what lets Alt-J hand back all the spaces as the new selection. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Blank lines open above a selection's first line and below its lastGabriel Schneider27 hours
| | | | | | | | | [<space> and ]<space> measured from the cursor's line, so over a selection of several lines whose head was at the bottom, [<space> opened a line INSIDE the selection. helix takes the range's line_range: above its start, below its end. helix-golf's export_from_mod (yp[<space>) is where it showed. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Replacing a selection with the register keeps its directionGabriel Schneider27 hours
| | | | | | | | | R always left the head on the pasted text's last char. helix maps the replaced range through the change, so a backward selection comes back backward, its head on the first char: helix-golf's reverse_golf_example (xbR) is where it showed. SPC R shares the path. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Surround keeps the direction of the selection it wrapsGabriel Schneider27 hours
| | | | | | | | | ms<ch> always left the wrapped range pointing forward. helix gives each range back with_direction(range.direction()), so a selection made backward (b, or v moving up) keeps its head on the open, which is where the next motion starts from. helix-golf's csv_to_sql (bms`) is where it showed. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Every helix-golf example is a differential case, one per step of its walkthroughGabriel Schneider27 hours
| | | | | | | | | | | The ten examples on helix-golf are imported as 118 cases: each numbered step of an example's walkthrough is the case whose keys are the command up to and including that step, so the first mismatch names the step where pardes and helix part. Six more restart at a step that begins with %, from helix's own text there, so a later step is tested even when an earlier one misses. zig build hxgolf compares all 124 with goldens from hx-harness. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* A regular expression search is bounded by a step budget patched into mvzr, ↵Gabriel Schneider27 hours
| | | | | | | | | | | | | | | | | | not windows and a repeat cap The windows returned wrong matches: a candidate reaching a window's edge was left to the next window, half a window on, which could answer a match starting mid-token rather than the leftmost, and addr then pointed data's next write at the wrong bytes. The repeat cap missed mvzr's own worst case, a chain of a?, and alternation under a repeat, each exponential inside one mvzr call the deadline could not interrupt; and it refused ordinary s/S patterns. build.zig now patches the fetched mvzr at build time with a step counter on its backtracking recursion (matchPattern), so a fresh fetch keeps it and a moved anchor stops the build; regexp.zig gives each compiled pattern a budget, about 300 ms here, and a search that spends it fails as taking too long. Windows, the cap and their special cases are gone, and matches are exact again. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* A regular expression search comes back: costly patterns refused, long lines ↵Gabriel Schneider27 hours
| | | | | | | | | | | | | | | windowed, 300 ms deadline mvzr backtracks with no bound on its work (a*a*a*a*x over a hundred a's takes a second, each repeat multiplying by the haystack length), and a search runs holding the editor's turn, so one pasted pattern froze the editor. pardes does not write or vendor a regex engine, so regexp.zig bounds what it hands mvzr: more than four repeats is refused, a line longer than a window sized from measured worst cases is searched in half-overlapping windows, and a deadline stops the search. addr names each failure; normal s/S keeps what it found. The prescan also stops reading an escaped backslash before n as a newline, and ends a class where mvzr does. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Exit quits and Kill stops commands, as in acmeGabriel Schneider27 hours
| | | | | | | | | | | | | | | | Kill quit the editor, which in acme is Exit; acme's Kill stops the commands it started. Exit now quits as acme's does (exec.c, rowclean): it refuses once, naming each pane with unsaved text, and quits when asked again with nothing edited since (a small scratch is not asked about). Kill, bare or with names, stops the commands pardes typed into a terminal (an exec, a middle click, a pty/run) while their shell's marks say they run, by SIGTERM to the terminal's foreground job, never to the shell (acme posts the kill note, which terminates). Both are session builtins; the topbar's Kill becomes Exit, same width, and every golden's topbar row changed by exactly that word (checked line by line); the builtins script scrolls one more row for the index's new line. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Normal mode's s and S search as addr does, through one shared regexp.zigGabriel Schneider27 hours
| | | | | | | | | | | | The sam-style calling convention for mvzr (a line per haystack, . made [^\\n] only when a pattern names \\n) lived in addr.zig; normal mode's s and S called mvzr over the raw selection, where ^ meant the selection's start and . crossed lines. src/regexp.zig now holds the one Regex (compile, find) both call, and fs.zig and pardes.zig drop an unused mvzr import. hxdiff and hxparity stay at their known 17 and 6 mismatches, none of them regex cases. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Let the keyboard reach a tag's path, read-onlyGabriel Schneider27 hours
| | | | | | | | | | | | | | The tag's computed path, dirty marker and page were out of the keyboard's reach: its cursor lived in the text after them. It now lives in the tag as shown, as in acme where the name is ordinary text at the start of the tag, so `0` goes to the line's start and motions select and yank the path. The path stays read-only: an edit that would change it is refused and leaves the cursor where it was, and typing into a file's path drafts a new name as a click on it does. Sync moves the tag's positions when the prefix changes length, so a rename or the dirty marker still never moves the cursor off the text after it. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Let s, S and | pressed in a tag answer for the tag's own textGabriel Schneider27 hours
| | | | | | | | | | A tag is a text like the body, so selecting on a regex and piping act on the text they are pressed in: a prompt records the text it answers for, the tag keeps the keyboard while it is typed, and a header's prompt goes on the active pane's band. `/` still searches the body from anywhere, as acme's Look from a tag searches the body. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Run the word under the cursor when Enter is pressed in a headerGabriel Schneider27 hours
| | | | | | | | | | The workspace and column tags hold nothing but commands, and before they became texts Enter on one of them ran it: Enter on Newcol made a column. Since then Enter looked the word up, as it does in a pane's tag, which only searched for it. It runs it again, and the header lets go of the keyboard first as a pane tag does. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* File the tag code into tagline.zig and draw tags beside bodiesGabriel Schneider27 hours
| | | | | | | | | | | With tags reduced to Texts, what is left of them is the computed prefix, the default and saved tails, entering and leaving a tag and the headers: that goes to tagline.zig, as acme keeps the tag half of a window in wind.c. Tag and header drawing moves next to body drawing in body_layer.zig, and the tag hit helpers go to tag_layer.zig with the Hit they read, where sameCell now also tells the lines of a taller tag apart. The docs describe the tag as a Text. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Give prompts their own line to type into instead of the tag's tailGabriel Schneider27 hours
| | | | | | | | | | | A search, pipe or Save prompt wrote its marker and answer onto the end of the tag, so the tag's cursor, its selection, its 9P writes and a prompt abandoned by a click all shared one buffer: the abandoned text stayed in the tag and a 9P write landed inside the prompt. The answer is now its own Text on the pane, typed in insert mode and shown on the notice band where it was already drawn, and the tag never holds any of it. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Point docs and comments at the files code moved toGabriel Schneider27 hours
| | | | | | | | | | | | | Documentation only, no code change: README's reading order and layout, docs/design.typ's paragraph on where pane kinds and editor parts live, docs/helix-keys.md's code map (normalInput and the executors now in normal.zig and edit.zig, insertTab in edit.zig), docs/open-questions.md (execute and ttyForDir in exec.zig), and the comments that named pardes.zig for fold, Cell, takesCommandLine and runBuiltin (tools/gen_themes.zig, themes/helix.zig, detached/wire.zig, host_io.zig, lsp_zls.zig). docs/design.pdf is a retained fixture and is not regenerated. Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Clear selections when navigating Back and ForwardGabriel Schneider27 hours
|
* Cycle pane input modes with Mode and retain terminal tag accessGabriel Schneider2026-09-15
|
* Remember tag cursors and reserve uppercase pane navigationGabriel Schneider2026-09-15
|
* Mirror raw terminal mouse selections for text transferGabriel Schneider2026-09-15
|
* Align file clicks and insertion cursorsGabriel Schneider2026-09-15
|
* Route mouse thumb buttons to jump historyGabriel Schneider2026-09-15
|
* Preserve selections when navigating jump historyGabriel Schneider2026-09-15
|
* Add Linux Tty9p mounted terminals and forward raw TTY keysGabriel Schneider2026-09-15
|