1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
|
// 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", <words>,
[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 <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("Term"), 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.],
[a PDF], [#key("Esc"): clears the selection and the search highlights, and with none shown goes back to the previous pane. #key("Shift-Esc"): back at once.],
)
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. #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 <mouse>
#pairs(
btn("B1"), [select; a click puts the cursor there and gives the pane the keyboard. In a tag it puts the tag's cursor there, in normal mode: #key("i") types there, #key("Enter") or #key("Tab") runs the word under it. 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.
In the SDL window on macOS, including a remote session, two or three fingers
click #btn("B2") (#word("Exec")); a force click is #btn("B3") (#word("Look")).
Two-finger scrolling follows the trackpad with macOS momentum. A deliberate
pinch changes the window's font size at reduced gain; small pinch noise during
a twist is ignored. Rotation in normal mode steps through search matches,
with a haptic notch for each step. Horizontal page swipes, as configured in
macOS, run #word("Back") and #word("Forward") through the jump history, with a
haptic cue approaching the short swipe threshold and another pulse when
navigation is triggered. Shift or Option keeps horizontal
scrolling instead of history swipes.
#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 <tags>
#tag("Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Fonts Config History Debug Exit")
#tag("New Term Find Grep Joincol Delcol")
#tag("Save Term Collapse Follow 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 <command-panes>
#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 (#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)
A file longer than its pane can go on in the next column, as Emacs's
follow-mode shows it: #word("Follow") (#key("SPC c f")) adds a page right of
it, and each page starts where the one before ends; scrolling any of them, or
moving the cursor past a page's edge, moves through all of them as one.
#word("Unfollow") on a page's tag takes it out of the chain.
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 <looking>
#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],
addr("https://ziglang.org"), [the browser, through `xdg-open` (`open` on macOS); #word("Plumb") adds rules of your own],
)
#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 <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 eight 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"). A PDF's
and a terminal's #key("/") still ask on the message row and list a
`+Search`.
#clip("search")
= Unsaved panes <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 <terminals>
#tag("Term+bash Save Mode Filter Collapse Del", path: "/home/me/src")
- #word("Term") opens a terminal in the pane's directory, #key("Alt-n") one in
the session's directory; #word("Term+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 <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.
= Call hierarchy <callstack>
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 static call
hierarchy of the project's `index.scip` (each caller the function whose
definition holds the call), else the language server's; 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 bigger than one answer holds (about
100,000 rows, the memory one query may use) stops there, its last row
saying so: run #word("Callstack") on a function above to go on.
At each level, callers whose function or file name contains "test" come
after the rest. Each signature and call snippet sits below its location,
aligned with the location text.
#word("CallstackDepth") reports the current caller depth;
`CallstackDepth 16` changes it for subsequent queries. The default is 8
levels, the accepted range is 1–64, and #word("Dump") / #word("Restore")
keep it.
= `pardes FILE` and `--wait` <editor>
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 <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>)[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 <sessions>
```
pardes --detach=work & a session with no screen of its own
pardes --attach=work show it here
pardes-gui --attach=work a window session's window again
pardes --ps every session the daemon keeps, and its shells
pardes --kill=work end it and its shells (--kill-all: every one)
```
#word("Detach") (#key("SPC s D")) lets the terminal or the window go and
leaves the session running, its panes, shells and files kept; so does a
terminal that closes. `pardes --attach` takes it back in any terminal,
`pardes-gui --attach` a window session's window: a terminal session takes
a terminal, a window session a window. Attached already, it takes another
view: each terminal or window has its own columns, focus, cursors and
scroll over the same panes, texts and registers, and a terminal shown in
two takes the size of the one that last typed into it. #word("Detach") in
one lets only that one go. A session is named by `--9p=` or
`--detach=`, else its pid. A session killed outright leaves its shells
running; #word("Adopt") in another takes them in as terminal panes, what
they showed gone. One `pardes --daemon` per user keeps all of it, and
leaves once nothing is kept. After a rebuild, #word("Upgrade")
(#key("SPC s U")) moves a running session onto the pardes now installed
where it was started from, in place: its text and undo, its views, its
terminals with their running shells, and its terminals and windows come
along, and the daemon moves too. A build that cannot read the session
hands it back to the one that ran it.
= Config <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
```
#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 <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]).
|