// The guide: pardes day to day, the path a newcomer reads once. Edge cases // live in the reference, the pager and the language servers in setup, the // keys on the cheatsheet. #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary, annotated, clip, mode-box #word("Look") (right-click) opens `src/bar.c:12`; #word("Exec") (middle-click) runs `make`. #annotated("/docs/site/media/themes/orchard.png", (640, 513), alt: "a pardes window: workspace tag, column tag, a file pane, a terminal and a diff", ([the workspace tag: words for the whole session], -22, 11), ([a column's tag], 400, 34), ([a pane's tag: its path, then its words], 560, 58), ([the box: the pane's mode, and the handle to drag it], 8, 58), ([the body: here a file, below it a terminal], 200, 104), ([the scrollbar: how much of the body is in view], 8, 160), ) #glossary("Words you'll see", , [the pane with the keyboard], [where your keys go; one pane at a time], [the session's directory], [where pardes started, or the directory `pardes DIR` named; workspace and column tags run there], [active column], [where the next new pane goes (below)], [command pane], [a terminal that runs one command line and shows its output], [`+` names], [panes pardes makes, named in their directory: `+New` a scratch (text with no file yet), `+Search` a query pane or a listing of places, `+Pager` paged text, `+Errors` output, `+Unsaved` the panes holding unsaved text], [serial], [a pane's number, never reused: the `3` in `@p3:12` and in 9P paths], [message row], [the line where pardes says what happened, and asks: answer a prompt (#key("s")'s regex, #word("Save")'s path) with #key("Enter"), cancel it with #key("Esc")], ) = Modes Each pane keeps its own mode. The box left of its tag shows it. #pairs( [#mode-box(" ") normal], [keys move and select; an edit acts on the selection. File and PDF panes start here, and so does a terminal from #key("Alt-n").], [#mode-box("^") insert], [keys type. #keys("i", "a", "o") and the rest enter it.], [#mode-box("$") raw, terminals only], [keys go to the program. A terminal from #word("Tty"), the shell a bare `pardes` starts with, and a command pane start here.], ) #key("Ctrl-b") switches a terminal between raw and normal. In normal, its text is a page to move over and copy from. #word("Mode") in the tag steps raw, normal, insert. #pairs( [#mode-box(" ") normal], [#key("Esc"): back to the previous pane (#word("Last")), unlike helix. #key("Shift-Esc"): the same.], [#mode-box("^") insert], [#key("Esc"): back to normal. #key("Shift-Esc"): out of insert and back to the previous pane.], [#mode-box("$") raw], [#key("Esc"): back to the previous pane. #key("Shift-Esc"): an Esc to the program. Either way the terminal stays raw. #word("ProgramEsc") `on` swaps them back: #key("Esc") goes to the program, except at a shell prompt with nothing typed on it, and #key("Shift-Esc") always goes back.], [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.], ) In acme, Esc selects the text typed since the last click; here it leaves insert mode, or goes back a pane. #key("Shift-Esc") needs the kitty keyboard protocol or the GUI. Elsewhere it is a plain Esc. The previous pane is the last one you jumped from, else the next pane down the column. #pairs( [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag. #key("d") is #word("Del") on the outlined pane (between two panes it waits for #key("k") or #key("j"), as #key("SPC d") does) and the outline moves to the pane that took its rows; #key("c") is #word("Collapse"). The mode stays on for the next key], [#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list), this file's first: another file's only once it has none left that way (#word("JumpScope") `all`: every place in order). #key("Ctrl-i") needs the kitty keyboard protocol or the GUI, being #key("Tab") elsewhere: there use #key("SPC j i") and #key("SPC j o"), or the mouse's side buttons], ) Raw mode sends almost every key to the program. Leave it (#key("Ctrl-b")) before #key("Ctrl-w") or #key("Alt-n"). = The mouse #pairs( btn("B1"), [select; a click puts the cursor there and gives the pane the keyboard. In a tag it starts typing, in insert mode. A double click selects the word; at a line's start or end, the line; just inside a bracket or quote, up to its match.], btn("B2"), [#word("Exec"): a builtin word runs, anything else is a shell line.], btn("B3"), [#word("Look"): open the file, address, directory or URL, else find the word's next place.], chord("B1", "B2"), [cut the selection], chord("B1", "B3"), [paste over it], chord("B1", "B2", "B3"), [copy], [Alt-click (Option)], [#btn("B2"), sweeps too, for one button or a trackpad; in a terminal too], [Super-click (Cmd)], [#btn("B3"); not in a terminal, which never passes Super], [Ctrl-click], [the language server's definition], ) #clip("chords") A program that takes the mouse gets the plain click. #btn("B3") on `src/bar.c:12:5:` in a compiler's error opens `src/bar.c` at line 12, column 5. A click takes the word under it: letters, digits and `. - + / : @ _ ~`, less a trailing `:`. Drag to take exactly what you swept. In normal mode #key("Enter") is #word("Look") and #key("Tab") is #word("Exec"). A builtin's argument: sweep `Find conf` with #btn("B2"), or select `conf`, then #chord("B2", "B1") on `Find`. #key("x") #key("y") then #key("p") copies a line below. Every pane shares the registers. #key("SPC y") and #key("SPC p") use the system clipboard. = Tags #tag("Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Config Debug Exit") #tag("New Tty Find Grep Joincol Delcol") #tag("Save Tty Collapse Del", path: "/home/me/notes.txt") A tag is text with undo. Type `make` into one and #word("Exec") it, or delete the words you never use. Any word runs from any tag: #word("Exit") in a pane's tag quits too. #pairs( [#key(":")], [the keyboard to the tag, on #word("Save") the first time; #key("Tab") runs it, #key(":") comes back], [edit the path, #key("Enter")], [renames: the next #word("Save") writes there; the typed path survives #key("Esc"), pending, and a second #key("Esc") drops it], [#word("Collapse")], [folds the pane to its tag], [drag the box], [up or down resizes; onto another column moves the pane], ) = Where commands run and panes go #btn("B2") on `make` runs it with the #word("Shell") setting's `-c`. Where it runs depends on where you clicked: #clip("where-commands-run") #pairs( [a terminal's text or tag, at a prompt with nothing typed], [typed into that shell, in its current directory], [any other pane's text or tag], [a command pane in that pane's directory, in the last column], [a column's tag], [a command pane in the session's directory, in that column], [the workspace tag], [a command pane in the session's directory, in the last column], ) A file's text and tag run in its directory: `make` from `README` at the project root is right, from `src/main.c` it is not. The keyboard stays where it was. The command pane's tag ends in `running`, then `exit N`: #tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0") Click into the command pane: #key("n") selects the next `file:line`, #key("Enter") opens it, and #key("n") from there goes on to the next error. A finished command pane is in normal mode, so #key("x") #key("y") copy from it at once. The next command for that directory reuses it. #word("Kill") `make` stops the commands pardes started with `make`. #word("Save") or #word("Del") in a column tag acts on that column's pane with the keyboard, else its first. Every other new pane goes into the *active column*: where you last typed or left-clicked, or where the last new pane went. The new pane takes the keyboard. A listing is the exception: it opens below the pane that asked, which keeps the keyboard, so #keys("n", "N") walk the listing. #btn("B3") on a file open in another column jumps there, but the next new pane still lands in the old column. #word("Placement") `pardes` picks other rules (#doc("reference", section: "placement")). To open beside: #word("Newcol"), then #word("Look") a file name typed in its tag opens it there; #key("Alt-c") moves a pane into a new column. #clip("columns", wide: true) Closing a column's last pane leaves it empty; #word("Delcol") and #word("Joincol") take columns away. Closing the session's last pane quits pardes. = Look #pairs( addr("notes.txt"), [opens it, or goes to the pane already showing it], addr("notes.txt:12"), [line 12], addr("notes.txt:/TODO/"), [the next match of `TODO`], addr("src/"), [a pane listing it, as acme's directory window: a #word("Look") at an entry opens it, `..` goes up, `Get` reads it again (#word("DirLook") `terminal`: `ls` in a terminal there)], addr("https://ziglang.org"), [the browser, through `xdg-open` (`open` on macOS); there is no plumber], ) #key("Enter") does the same from the keyboard; the other address forms are on the cheatsheet. A relative path is found in the directory of the pane the #word("Look") came from, then of each pane on the jump list, most recent first. = Search #key("/") opens a query pane under the pane: a `+Search` whose first line is the query, typed into, and whose rows are what it finds, made again at each key. It takes its rows from the pane it searches and from no other, is born #word("SearchRows") rows tall and never resizes itself; nothing found is a count of `0` in its tag, not an exit. #pairs( [#key("/") `vw`], [every match in the text tinted and ticked on its scroll rail, the first after the cursor selected; the rows under line 1 are the lines holding it, each its place as text first (`file:line:col`, the shortest path a #word("Look") from the pane resolves), then the line coloured as the file is, under the declaration it is in], [#keys("Ctrl-n", "Ctrl-p")], [the next or previous match, typing; the text follows it], [#key("Enter")], [the keyboard on the match, the pattern in `/`, the rows kept as text (#word("Save") keeps them as a file)], [#keys("n", "N")], [the next or previous match in the text, round the end without a word], [#key("Esc")], [typing: the text as it was, the query pane closed], [#key("*")], [the selection as line 1, the keyboard staying in the text], ) Line 1's first word names what it searches, and editing the word changes it: #pairs( [`/pat`], [the pane's own text: a regex, any case unless it has a capital (#key("/"))], [`Find name`], [the files below the pane's directory, by a fuzzy match of their names (#key("SPC f f"), #word("Find"))], [`Grep text`], [the lines of those files holding `text`, literally (#key("SPC f g"), #word("Grep")); past 2000 lines #word("More") goes on], [`Recent name`], [the files opened lately, in any window (#key("SPC f r"), #word("Recent"))], [`Panes name`], [the open panes, then the ones closed this session, `(closed)` and dimmer: #key("Enter") (or a #word("Look") at its `@pN`) brings one back where it was, its text with it (#key("SPC b b"), #word("Panes"))], [`Symbols name`], [the text's declarations (#key("SPC s s"))], [`All pat`], [every open pane's text, its rows under each pane (#key("SPC /"))], [`Refs`, `Def`, `Impl`, `Diagnostics`], [the language server's lists (#key("g r"), #key("g d"), #key("g i"), #key("SPC l d")): one answer is a jump, none a message; several open the list with the keyboard on its current row in normal mode (#keys("j", "k", "n", "N") step it, #key("Enter") lands, #key("Esc") goes back), the diagnostics' keeping it in the text for `]d`; their places in the text tinted as a `/`'s are], ) A row in a file no pane shows is shown in a `+Preview` under the query pane. The current row follows the keyboard only (#keys("Ctrl-n", "Ctrl-p") typing, #keys("n", "N") and #keys("j", "k") in the pane's normal mode); #btn("B1") on the rows places the caret and selects, as in any pane, and moves nothing else. #key("Enter") lands the current row, making the preview that file's pane where it stands. The preview colours the file as its own pane does, and the query's hits in it are its places, tinted and ticked, the current one selected. #btn("B3") on a row's place goes there, as on any address; the rows kept as text (#word("Save")) are a list of places that still work. #btn("B2") on line 1 runs it again. The next search from the same pane reuses its query pane, its kept rows back on #key("Esc") (#word("SearchPane") `new`: a pane each; #word("SearchPlace") `column`: in a finder column at the right). A PDF's and a terminal's #key("/") still ask on the message row and list a `+Search`. #clip("search") = Unsaved panes #word("Del") on a pane with unsaved text, its box filled (#mode-box(" ", unsaved: true); a `*` in a terminal), refuses once, saying `1 unsaved pane — Del again to discard`, and lists the pane in `+Unsaved`; #word("Del") again discards it. #word("Exit") (or #key("SPC q")), #word("Restore") and #word("Delcol") refuse once the same way. #key("SPC d") between two panes also asks which takes the rows: #key("k") above, #key("j") below. Typed straight on, #key("SPC d") then #key("j") just closes the pane; the question shows on its notice band only if no answer has come after a moment, a hint for a Del that seemed to do nothing. = Terminals #tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src") - #word("Tty") opens a terminal in the pane's directory, #key("Alt-n") one in the session's directory; #word("Tty+bash") picks the shell. - #word("Del") closes a terminal and its shell at once, running or not, and a shell that exits closes its pane. - #word("Save") writes the scrollback to a path it asks for. - #word("Filter") maps the program's colours through the theme. - #word("Petscii") draws a program's images as glyph art instead of pixels. - In raw mode Ctrl-V types what you yanked, Ctrl-Shift-V the clipboard. - In normal mode, editing a terminal's text edits a copy, and the first edit says so: #key("Tab") or #btn("B2") runs it, and the program's next drawing replaces it. - A program that tracks the mouse gets #btn("B1") and the wheel; #btn("B2") and #btn("B3") stay pardes's. Hold Shift to swap. - #word("Repl") `python` in its tag makes #btn("B2") on a `.py` pane send the text to that REPL. - `git log` and `man` open in a `+Pager` pane (#doc("setup", section: "pager")). = Reviewing diffs `git diff` run as a command, or a `.diff` or `.patch` shown as text (below), is drawn as a diff, each hunk in its file's language. #btn("B3") on: #pairs( [`diff --git`, `---`, `+++`], [the file], [`@@ -3,7 +3,8 @@`], [the hunk's first new line], [a line's `+`, `-` or space], [that line in the new file], ) A `.diff` or `.patch` looked at, and a diff paged (`git show`), opens as a `+Diff`, stacked as delta shows one: each hunk under its `path:line` (`Space j n`/`Space j p` step through them, #btn("B3") opens it) and the declarations around it, a `+`/`-` before each line, the words a changed line changed tinted and a line added or removed whole faintly. A mailed patch keeps its message and diffstat above. The files are found from the diff's directory or one above it. #word("Diff") on a `+Diff` shows the diff itself as text (a paged one's `+Pager` is closed once stacked), and on the text stacks it again; #word("DiffLook") `text` in the startup file opens the text first. = Call hierarchy Put the cursor on a function and run #word("Callstack") (#key("g c") or #key("SPC l b")). `+Callstack` starts at the outermost callers and follows calls down toward the selected function, with shared callers grouped and vertical guides joining the levels with rounded corners. Each caller has a clickable location and its function signature, extracted by the same tree-sitter context mechanism as other location results. Signatures and call-site snippets use source syntax colors; only calls to the selected function receive background emphasis. Guides continue alongside every line of a multiline signature and through screen wrapping. Cross-directory Look paths are shortened when possible. #btn("B3") or #key("Enter") on a location opens and reveals that source pane. #word("LookNext") / #word("LookPrev") (#keys("SPC j n", "SPC j p")) select locations without opening them. The view follows the language server's static call hierarchy; recursive paths are marked `↻`, and a hierarchy deeper than the limit invites continuing from another function. Every caller is listed: the walk runs as long as the server keeps answering, says how many callers it has found on the message row once it takes more than a second, and shows what it found if the server stops answering. Asking anything else stops it. A tree too big for one page (about 100,000 rows, the memory one query may use) ends in a row saying so: running #word("Callstack") in `+Callstack` shows the next page, from where this one stopped, with that caller's own callers above it again. At each level, callers whose function or file name contains "test" come after the rest. #word("CallstackDepth") reports the current caller depth; `CallstackDepth 16` changes it for subsequent queries. The default is 8 levels, and the accepted range is 1–64. `CallstackLayout stacked` (the default) puts each signature and call snippet below its location, aligned with the location text; `CallstackLayout inline` puts it beside the location again. A bare #word("CallstackLayout") switches modes. `CallstackCorners rounded` (the default) uses rounded tree guides; `CallstackCorners square` restores sharp corners. Bare #word("CallstackCorners") switches styles. Layout and corner changes apply to the next query. These settings are retained by #word("Dump") / #word("Restore"). = `pardes FILE` and `--wait` In a pane's shell: ``` pardes notes.txt open it here and return at once (acme's B) pardes --wait notes.txt return when that pane closes (acme's E) ``` A file not there yet opens empty, and #word("Save") creates it. `--wait` makes pardes an `EDITOR` (#doc("setup", section: "editor-setup")); refusals and `--nested` are in the reference. = Keys #pairs( [#key("w") #key("d")], [select a word, delete it: motions select, edits act on the selection], [#key("x"), #key("v"), #key(";")], [select the line; extend; collapse to the cursor], [#key("s")], [a cursor per regex match; every edit acts at each], [#key("/"), #keys("n", "N")], [search the text in a query pane (#link()[Search]); step its matches, round the ends], [#keys("SPC j n", "SPC j p")], [#word("LookNext") / #word("LookPrev"): select locations across panes; #key("Enter") opens one], [#key("g l")], [line end], [`12G`], [line 12; a bare #key("G") does nothing], [#key("SPC ?")], [#word("Help"): every builtin, with its leader path and keys; `SPC w ?` only the paths under `SPC w`; #word("Tutor") (#key("SPC h t")) practises them], [#keys("g d", "g r"), `SPC l`], [the language keys, once a server is installed (#doc("setup", section: "language-servers"))], ) The keys are helix's, and helix's #link("https://docs.helix-editor.com/keymap.html")[keymap] is their full reference. Where pardes differs (#key("Esc") leaving the pane, the #key("SPC") paths, #key("Ctrl-w"), #key("Ctrl-b")), this guide and the cheatsheet (#doc("cheatsheet")) say so. = Sessions ``` pardes --detach=work & a session with no screen of its own pardes --attach=work show it here ``` The session owns the panes, shells and files; frontends come and go, and all of them see the same screen. #word("Attach") `work` (#key("SPC s a")) switches this window to it; #word("Detach") (#key("SPC s D")) leaves it running. = Config #word("Config") (#key("SPC f c")) opens the startup file, `~/.config/pardes/init`: one builtin a line, run at start, `#` a comment. ``` Theme atelier Shell zsh # Placement acme is the default; Placement pardes picks the other rules ``` #word("DumpConfig") opens every live setting as the line that sets it. #word("Dump") saves the workspace and #word("Restore") brings it back (what a dump keeps is in the reference). Keys are compile-time, in `src/config.zig`. = Questions / Why not helix and tmux, or acme?: helix and tmux edit and run shells well, but their text is inert. acme makes text the interface and is modeless by design, with win for shells and page and the plumber for documents. pardes keeps acme's text as the interface and trades the rest for helix's modal keys, a VT terminal and PDFs in a pane. What changes for acme users and scripts is in #doc("reference", section: "from-acme"). / Does it run inside tmux?: Yes, as in any terminal. Where tmux does not pass kitty's protocols, #key("Shift-Esc") is a plain Esc and images draw as glyph art. / Does my helix config carry over?: No. The keys are compiled in (`src/config.zig`); `~/.config/helix` is not read. / How do I quit?: #key("SPC q"), or #word("Exit") in any tag. / What does "pardes" mean?: The name of the four levels of reading a text in rabbinical exegesis (#link("https://en.wikipedia.org/wiki/Pardes_(exegesis)")[Wikipedia]).