# cumulus Brainstorm in the terminal: ideas as nodes on a 2D canvas, connected, folded and color-coded, across as many documents as you like. Vim keys first; the mouse works too. Runs on Windows and Linux. > **Status:** being built, one stage at a time. See [DESIGN.md](DESIGN.md) for > the plan; this README grows with the app. ## Build and run You need Rust ([rustup.rs](https://rustup.rs)). The exact version is pinned in `rust-toolchain.toml`, and rustup installs it by itself the first time. ```sh cargo build --release ``` The program is `target/release/cumulus` (`cumulus.exe` on Windows): copy it to a folder on your `PATH`. - **Windows**: nothing else to install. The `.exe` carries its own C runtime and runs on any Windows 10 or 11. - **Linux** (Void, Fedora…): build the same way. You can also build a static Linux binary from Windows with `cargo linux`: it lands in `target/x86_64-unknown-linux-musl/release/cumulus` and runs on any distribution. ## Starting it ```sh cumulus # ./ideas.cum, or ~/ideas.cum (made the first time) cumulus garden.cum # that document (a new one if it isn't there yet) cumulus notes/ # that folder's ideas.cum cumulus new "Garden plans" # makes ./garden-plans.cum (cumulus new: ./ideas.cum) cumulus --paths # where cumulus keeps its settings and data ``` Documents are plain text files (`.cum`) that live wherever you like. cumulus saves a second after each change, reloads a file another program changed (`u` undoes that), and keeps a copy of each document a day in its data folder. A document open in another cumulus opens read-only. Each one reopens where you left it. ## Settings, keys and themes `:config` lists the three config files: `config.toml` (the settings), `keys.toml` (your keys) and the theme's file. Enter opens one in your editor (the `editor` setting, or `$VISUAL` / `$EDITOR`, or notepad / vi); the first time, it's written with every option at its default behind a `#`, explained. Take a `#` away, save, and cumulus applies it at once. Each file only needs what it changes, and a mistake only skips its own line (the status bar says what's wrong). - `:set name=value` changes a setting until cumulus quits (`:set name?` shows it, Tab lists them). - `:theme name` switches to `themes/name.toml`, laid over the built-in theme: a theme can say just `accent = "magenta"`. - The built-in theme has named styles (`s`), also put on by tags: `#question` (yellow, dashed), `#important` (red, thick), `#done` (faded). - `clipboard = "unnamedplus"` makes plain `y`, `d` and `p` use the system clipboard, as the vim setting of that name does. ## Keys The plan for the everyday keys (all of them are in DESIGN.md): | Keys | What they do | |-------------------|----------------------------------------------------| | `hjkl` | move to the nearest node that way | | `gh gj gk gl` | parent, next sibling, previous sibling, first child | | `o` `O` `a` | new sibling below / above, new child: type its title, Enter for the next one | | `i` or Enter | edit the title (Esc: vim keys inside it, Esc again: done) | | `dd` `x` | delete the branch / just the node (kept in a register, as in vim) | | `yy` `p` `P` `]p` | yank the branch / paste after, before, as a child (`dd` then `p` moves a branch) | | `"a` `"+` | before `y`, `d` or `p`: register `a`; `"+` is the system clipboard (nodes go there as Markdown) | | `.` | the last change again | | `>>` `<<` | under the node above / out a level | | `u` `Ctrl-r` | undo / redo | | `za` `zf` `zi` | fold, auto-fold, focus | | `+` `-` | zoom in / out | | `K` | the body in a card beside the node (`i` edits it there) | | `v` `V` | select: the nodes between here and where you started (`V`: with their branches); then `d` `y` `>` `<` `M` or `c` act on all of them | | `M` | move the branch with `hjkl` (`M` again: just the node) | | `/` `n` `N` | search: titles, tags and bodies, fuzzily, with the note of each match beside it / the next match / the previous one | | `Ctrl-o` `Tab` | back to where you jumped from / forward again (across documents) | | `ma` `'a` `mA` | mark a node / go back to it / a capital mark: from any document | | `gd` | follow a cross-link | | `` | the action menu: `c` color, `t` tags, `b` documents, `i` inbox, `vo` outline, `vn` note… | | `Ctrl-w v` `Ctrl-w s` | split the pane side by side / stacked (`Ctrl-w hjkl` to move between them) | | `gt` `gT` | the next / previous document | | `:` `?` | command line, help (search it with `/`, Enter runs the key or command) | | `:e` `:new` `:bd` | open a document / make one / close it | | `:marks` `:jumps` `:registers` | what they hold: Enter goes there (or pastes) | | `:w` `:q` `ZZ` | save / close the pane (the last one quits) / save and close | After the first key of a sequence (`g`, `z`, `d`, ``…), a popup lists what can follow. The right mouse button opens a menu of what you can do with a node. Ctrl+click picks nodes one by one, and Ctrl+drag on the empty canvas picks the ones in its rectangle. The wheel scrolls; with Shift or Alt held (or a wheel that tilts), it scrolls sideways. ## Development ```sh cargo test # run the tests cargo lint # clippy, treating warnings as errors cargo fmt # format the code ``` To try things without touching your own documents: ```sh cargo run --example canvas # cumulus on copies of two sample documents cargo test show_canvas -- --ignored --nocapture # print the sample at each zoom, as text ``` The end-to-end tests (`src/app/tests.rs`) type keys and click on a test terminal, with the sample documents copied to a temporary folder, and check the screen, the documents and the files.