diff options
| author | user <user@clank> | 2026-08-27 16:04:37 +0200 |
|---|---|---|
| committer | user <user@clank> | 2026-08-27 16:04:37 +0200 |
| commit | 5151e42f22b404cf41dc8b409bcdfcd4b39444ea (patch) | |
| tree | da8424903e12bf41a6144b065e06529df4f8e947 /docs/workspaces.md | |
| parent | docs: the landing page stops arguing (diff) | |
| download | slosh-5151e42f22b404cf41dc8b409bcdfcd4b39444ea.tar.gz slosh-5151e42f22b404cf41dc8b409bcdfcd4b39444ea.tar.xz slosh-5151e42f22b404cf41dc8b409bcdfcd4b39444ea.zip | |
README/docs: spell the dash --, as the rest of the tree does
Every C comment, commit message and generated config in this repo
writes the aside dash as a spaced double hyphen; the Markdown alone
used U+2014, some 220 of them. One spelling, and the ASCII one -- the
prose now matches the code it documents.
Mechanical (every occurrence was the spaced form, checked including
the one inside a code fence, where it was comment text), so the words
themselves are untouched.
Diffstat (limited to 'docs/workspaces.md')
| -rw-r--r-- | docs/workspaces.md | 56 |
1 files changed, 28 insertions, 28 deletions
diff --git a/docs/workspaces.md b/docs/workspaces.md index b90c145..e91140d 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -5,7 +5,7 @@ session. Two words rather than one because the two have different lifetimes: the project outlives every session and is checked into git, the workspace lasts until you close the tab. -[Finding a pane](panes.md#finding-a-pane) starts from the complaint this answers — +[Finding a pane](panes.md#finding-a-pane) starts from the complaint this answers -- tabs stop being navigation somewhere around six projects. The finder answers *where is that pane*; this answers the question before it: which of the things you work on is this tab about, and what does opening one mean. `C-a w`, a name, enter, @@ -17,20 +17,20 @@ A subdirectory of a configured root with one of two markers in it: | marker | what it is | |---|---| -| `slosh.layout` | a *declared* project — it says what it needs open | -| `.git` | an *inferred* one — you work here, but you have not said how | +| `slosh.layout` | a *declared* project -- it says what it needs open | +| `.git` | an *inferred* one -- you work here, but you have not said how | Anything else is not a project, and nothing is guessed from what is inside it. **`.git` counts because otherwise the list is empty on the day you configure the feature.** A picker that only knows declared projects shows nothing until you have -written a layout, and there is nowhere to write one from — you would need the +written a layout, and there is nowhere to write one from -- you would need the picker to get there. The inferred half is also the invitation: such a project reads `.git · no layout` in the picker, and `C-a W` is how it stops being one. **A directory that is a project is never descended into.** That is what keeps the scan out of `node_modules`, a vendored checkout or a submodule without a rule about -any of their names — they are under a project, so the walk stops above them. A skip +any of their names -- they are under a project, so the walk stops above them. A skip list is a list of the directories that were fashionable when it was written; this holds for the ones nobody has invented yet. @@ -43,28 +43,28 @@ project_roots "~/dev" "~/work" depth=2 project_layout "~/.config/slosh/project.layout" ``` -`project_roots` takes more than one directory because people have more than one — -work in one tree, everything else in another — and `depth` is how many levels below +`project_roots` takes more than one directory because people have more than one -- +work in one tree, everything else in another -- and `depth` is how many levels below each root to look, 2 by default, 1 to 8. Two is `~/dev/thing` and `~/dev/org/thing`, which is where checkouts actually sit. **No roots configured and the feature is dormant.** Nothing is scanned, `C-a w` says which setting is missing rather than opening an empty picker, and `workspaces` -answers `roots: false` — because "you have no projects" and "you never said where +answers `roots: false` -- because "you have no projects" and "you never said where they are" are different facts, and a tool that cannot tell them apart reports the wrong one. `project_layout` is what a project with no file of its own opens as. **Relative paths in it bind to the project being opened, not to the directory the file lives -in** — deliberately the opposite of the rule for a layout you name yourself, where +in** -- deliberately the opposite of the rule for a layout you name yourself, where a relative `cwd=` is relative to that file ([layouts](layouts.md#the-shape)). The whole point of one shared layout is that `cwd="."` means *this* project; bound to itself it would open every project in `~/.config/slosh`. Unset, a project opens as one pane running your shell in it. **Nothing sniffs `package.json` or `Cargo.toml` to guess what to run.** A table -mapping manifests to commands is wrong for somebody the day it ships — the repo -with two package managers, the one whose dev server is behind a make target — and +mapping manifests to commands is wrong for somebody the day it ships -- the repo +with two package managers, the one whose dev server is behind a make target -- and stale for everybody a year later. `project_layout` is that table with your name on it, covering the projects you have rather than the ones a heuristic imagined, and a project that disagrees with it carries its own file. @@ -80,10 +80,10 @@ project that disagrees with it carries its own file. `w` and `W` are the same shifted pair as `p`/`P`: go to one, write one down. All three are bindable as `workspaces`, `save-workspace` and `set-purpose`, and all three are in the palette under `projects`, so they work before you have rebound -anything — see [keys](keys.md#defaults) and [every action](keys.md#every-action). +anything -- see [keys](keys.md#defaults) and [every action](keys.md#every-action). The picker narrows on a project's name, its path and which marker it has, so typing -`.git` gives you the projects with no layout yet — which is the list you want when +`.git` gives you the projects with no layout yet -- which is the list you want when you are about to write one. A project that is already open shows its purpose instead, and a dot marks the workspace you are in. @@ -101,7 +101,7 @@ Tomorrow, `C-a w Enter` rebuilds that tab with the dev server in the pane you pu it in and not running. A tab with no name of its own takes the project's, because a strip reading `1 2 3` is the thing workspaces are for. -**Closing one is `C-a X`**, which closes the tab and the workspace with it — +**Closing one is `C-a X`**, which closes the tab and the workspace with it -- membership *is* the tab's purpose, so there is nothing else to put away and no second key to learn ([keys](keys.md#defaults)). `close-workspace` over the socket is the same thing for a workspace whose layout opened several tabs: it closes @@ -117,7 +117,7 @@ and the toast says what happened: the same act as arranging one: split the tab, start the dev server, start the log tailer, tag the ones that matter, `C-a W`. A pane's terminal has a foreground process group and that group is the job running in it, so nothing has to be -declared up front for it to be recorded — see +declared up front for it to be recorded -- see [writing one back out](layouts.md#writing-one-back-out) for what is deliberately *not* counted as a command (a shell at a prompt, a background job, an ephemeral pane). @@ -127,16 +127,16 @@ where the two part company. It takes one of four values: | `suspend` | writes `suspended=true` on | |---|---| -| `as-is` | whatever is suspended right now — the default for `dump-layout` | +| `as-is` | whatever is suspended right now -- the default for `dump-layout` | | `none` | nothing | -| `commands` | every pane that has a command — the default for `save-workspace` | +| `commands` | every pane that has a command -- the default for `save-workspace` | | `all` | every pane | The defaults differ because the two verbs answer different questions. [`dump-layout`](layouts.md#writing-one-back-out) is *put this session back*, so it reports the state it found. `save-workspace` is *this is what this project needs open*, and the pane running this morning's dev server is a pane that should be laid -out tomorrow rather than started — twelve checked-out projects are not twelve +out tomorrow rather than started -- twelve checked-out projects are not twelve running dev servers ([layouts](layouts.md#the-shape)). A suspended pane still shows what it would run, so the layout stays readable as a record of the commands. @@ -148,8 +148,8 @@ otherwise: a shell's history and an editor's buffers are not in it. That asymmetry is not an oversight in either direction. A key cannot pass a flag, and the operator pressing it is looking at the tab being written; the file is committed text, so the diff is the confirmation and the replacement stays -reviewable after the fact. A script has none of that — no witness, no glance at -the screen — so it says so in the request. +reviewable after the fact. A script has none of that -- no witness, no glance at +the screen -- so it says so in the request. `save-workspace` also takes `path`, for a tab that is not a workspace yet: that is how a hand-arranged tab becomes a project's layout without opening it through the @@ -157,7 +157,7 @@ picker first. `slosh --check slosh.layout` holds the result to the layout schema and prints one `file:line: what` per problem, so a project's layout goes through the -same check as everything else you commit — see +same check as everything else you commit -- see [layouts](layouts.md#what-to-call-them). ## Identity @@ -169,11 +169,11 @@ project:api.9f3c1d20 ``` The hash is of the resolved absolute path, not of the name, so two git worktrees of -one repo are two workspaces — which is what they are, and a name-keyed session +one repo are two workspaces -- which is what they are, and a name-keyed session would have merged them and then focused the wrong one. Membership is that string and nothing else: no side table of open projects to fall out of step with the tabs. -Because the session declared it, it is **locked** — no program running in a pane +Because the session declared it, it is **locked** -- no program running in a pane can relabel a project tab, however chatty its title. That is the same rule any declared purpose gets, and it is what makes the purpose safe for a tool to address. @@ -187,14 +187,14 @@ built and deliberately not claimed. Discovery is derived, never remembered: one `readdir` per root plus two `stat`s per entry, run when the picker opens rather than per frame. **Nothing is stored, so -nothing can be stale** — and no watcher can promise that. Inotify does not fire for +nothing can be stale** -- and no watcher can promise that. Inotify does not fire for a bind mount, an sshfs share or a checkout another machine wrote, so a cache that trusted it would be wrong exactly when the answer mattered. One thing a scan cannot see is a project's layout file changing under a workspace that is already open. `workspaces` reports each layout's `mtime`, so a tool that keeps the mtime it opened with can compare and notice. Re-applying the new file over -the running panes is deliberately not offered — it would kill them. +the running panes is deliberately not offered -- it would kill them. ## From another program @@ -209,9 +209,9 @@ $ slosh -s work cmd '{"cmd":"panes"}' # keep the ones whose tab_id is 3 | verb | takes | answers | |---|---|---| -| `workspaces` | — | `roots`, and a `workspaces[]` of `name` `path` `purpose` `layout` (the file, or `""`) `mtime` `tab` (0 when it is not open) | +| `workspaces` | -- | `roots`, and a `workspaces[]` of `name` `path` `purpose` `layout` (the file, or `""`) `mtime` `tab` (0 when it is not open) | | `open-workspace` | `name` or `path`; `suspended` | `tab` `purpose` `path` `created` `tabs` `honoured`. Already open, it focuses that tab and answers `created:false` | -| `close-workspace` | `name` or `purpose` | `closed` — how many tabs went | +| `close-workspace` | `name` or `purpose` | `closed` -- how many tabs went | | `save-workspace` | `tab` (0 for the current one), `path` for a tab that is not a workspace yet, `suspend`, `force` | `path` `purpose` `panes` `suspended` `replaced` | Every one of them is in the bare dispatcher too, so `slosh -s work cmd @@ -221,7 +221,7 @@ without quoting JSON ([scripting](scripting.md#the-control-socket)). `open-workspace` is idempotent, which is the property that makes it safe to call from a script that does not know whether it ran already: asking twice focuses the tab rather than building a second one. `suspended:true` opens the layout with every -pane suspended whatever the file said — the *open ten projects, run zero processes* +pane suspended whatever the file said -- the *open ten projects, run zero processes* case, which is a different question from the one the project answered about which of its own panes are expensive. |
