aboutsummaryrefslogtreecommitdiffstats
path: root/docs/workspaces.md
diff options
context:
space:
mode:
authoruser <user@clank>2026-09-02 12:35:46 +0200
committeruser <user@clank>2026-09-02 12:35:46 +0200
commit26a9f3e63f696957658335f0fdf58fd50c929930 (patch)
treec8e7eff5c7b7b456713de16194fa340e2323d8d9 /docs/workspaces.md
parentweb: the logo becomes geometry -- fonts cannot break rects (diff)
parentdocs: chore (diff)
downloadslosh-26a9f3e63f696957658335f0fdf58fd50c929930.tar.gz
slosh-26a9f3e63f696957658335f0fdf58fd50c929930.tar.xz
slosh-26a9f3e63f696957658335f0fdf58fd50c929930.zip
Merge remote-tracking branch 'origin/docs-new'
Diffstat (limited to 'docs/workspaces.md')
-rw-r--r--docs/workspaces.md125
1 files changed, 21 insertions, 104 deletions
diff --git a/docs/workspaces.md b/docs/workspaces.md
index 134b8b2..a685748 100644
--- a/docs/workspaces.md
+++ b/docs/workspaces.md
@@ -1,6 +1,6 @@
# Workspaces
-slosh has the concept of **workspaces**. Essentially a workspace is a
+slosh has the concept of **workspaces**. Essentially a workspace is a
pane layout that represents a project. slosh will scan your config's `project_roots`
folder(s) for two kinds of sub folders: ones that have a `slosh.layout` file, and
ones that have a `.git` but no `slosh.layout`. in the latter case our project picker
@@ -15,89 +15,33 @@ 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
-each root to look, 2 by default, 1 to 8.
+`project_roots` takes one or more director{y,ies}, and `depth` is how many levels below
+each root to look, 2 by default.
## From the keyboard
-| key | does |
-|---|---|
-| `w` | the projects picker |
-| `W` | write this tab as this project's layout |
-| `P` | set this pane's purpose |
-
-`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).
+| key | action | does |
+| --- | -------------- | --------------------------------------- |
+| `w` | workspaces | the projects picker |
+| `W` | save-workspace | write this tab as this project's layout |
+| `P` | set-purpose | set this pane's purpose |
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
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.
-The flow the feature is shaped around, once through:
-
-```
-C-a w picker: ~/work newthing .git · no layout
-Enter your project_layout, cwd bound to newthing
-C-a Enter, npm run dev arrange it, run things
-C-a P service:web Enter tag the pane that matters
-C-a W "wrote slosh.layout · 4 panes, 2 suspended"
-```
-
-Tomorrow, `C-a w Enter` rebuilds that tab with the dev server in the pane you put
-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:
-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
-every tab carrying that purpose and says how many.
+**Closing one is `C-a X`**, which closes the tab and the workspace with it.
## Saving one
-`C-a W` writes the focused tab to `slosh.layout` in the project's directory,
-and the toast says what happened:
-`wrote slosh.layout · 4 panes, 2 suspended`.
+`C-a W` writes the focused tab to `slosh.layout` in the project's directory.
**What each pane is running goes in with it.** That is what makes writing a layout
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
-[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).
-
-**A project's layout is not a verbatim dump of the session**, and `suspend` is
-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` |
-| `none` | nothing |
-| `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
-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.
-
-Neither can restore what is *inside* a program, and the file does not pretend
-otherwise: a shell's history and an editor's buffers are not in it.
-
-**Over the API, writing over a layout that is already there is refused without
-`force`; from the keyboard `C-a W` replaces it and the toast says `replaced`.**
-The asymmetry is deliberate: the operator pressing the key is looking at the
-tab being written, and the file is committed text, so the diff is the
-confirmation. A script has no witness, so it says so in the request.
+declared up front for it to be recorded.
`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
@@ -105,12 +49,11 @@ 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
-[layouts](layouts.md#what-to-call-them).
+same check as everything else.
## Identity
-A workspace *is* its tab's [purpose](layouts.md#purposes):
+A workspace _is_ its tab's [purpose](layouts.md#purposes):
```
project:api.9f3c1d20
@@ -122,27 +65,7 @@ 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
-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.
-
-A tab that a layout gave some *other* purpose keeps it and is not a member.
-Honouring it is the point: overwriting a declared purpose is precisely what the
-lock forbids, and a project layout that names a tab `agent:main` meant it.
-`open-workspace` counts those in `honoured`, so a caller can see that a tab was
-built and deliberately not claimed.
-
-## Nothing watches
-
-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
-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.
+can relabel a project tab, however chatty its title.
## From another program
@@ -155,12 +78,12 @@ $ slosh -s work cmd '{"cmd":"open-workspace","name":"api"}'
$ 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) |
-| `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 |
-| `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` |
+| verb | takes | answers |
+| ----------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `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 |
+| `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
workspaces` and `slosh -s work cmd open-workspace api` do the same from a shell
@@ -169,12 +92,6 @@ without quoting JSON ([scripting](scripting.md#the-control-socket)).
`open-workspace` is idempotent: asking twice focuses the tab rather than
building a second one, so a script that does not know whether it already ran is
safe. `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.
-
-The useful part is the last step. Having opened a workspace, filter
-[`panes`](scripting.md#the-control-socket) by that `tab_id` and act on the purposes
-the project's own layout declared: the project decided that `service:web` is its
-dev server and that it starts suspended, and neither the session nor the program
-driving it had to know that beforehand.