Metadata-Version: 2.4
Name: turbovi
Version: 0.6.0
Summary: A vi clone for the terminal: enough vim to edit with, in three thousand lines
Keywords: terminal,tui,vi,vim,editor,modal
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Editors
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Dist: turbodesk[syntax]>=0.4.4
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# TurboVI

A vi clone for the terminal: modes, counts, operators, registers, marks, macros, split windows, `:s`, find-in-project with a quickfix list, and Markdown shown rendered. About 6,200 lines of Python, 3,800 of them code.

```sh
uv sync
uv run turbovi somefile.py
uv run turbovi one.py two.py   # two buffers, :bn between them
uv run turbovi somefile.py +42 # on line 42
uv run turbovi                 # a scratch buffer
```

`:q` to leave, `:help` for what is here.

## What a vim user gets

**The grammar**, `["x] [count] operator [count] motion`, over `hjkl w b e ge W B E 0 ^ $ gg G { } f F t T ; , % H M L`. Operators `d c y > < gu gU g~ gc !` with doubling (`dd`, `yy`, `gcc`), text objects (`iw aw i( a" i{ i< ip it`), and `x X D C s S r R ~ J gJ Y p P o O`, `<C-a>` and `<C-x>`. In insert mode, `<C-w>`, `<C-u>` and `<C-r>x`.

**Modes**: normal, insert, visual, visual-line, visual-block and command.

**Paging** with `<C-f>` `<C-b>` `<C-d>` `<C-u>`, by the window rather than by a fixed number, `<C-e>` / `<C-y>` to move the view without moving the cursor, and `zt` `zz` `zb` to put the cursor's line at the top, middle or bottom.

**Search** with `/ ? n N * #` and match highlighting, `:set ignorecase` and `smartcase`, and `\c` and `\C` in a pattern. **Undo and redo** with `u` and `<C-r>`. **`.`** repeats the last change, recorded as keystrokes the way vi does it, so a change that ends in insert mode replays whole.

**`:s`** with ranges (`%`, `.`, `$`, `1,5`, `.+1`), the `g`, `i` and `n` flags, any non-alphanumeric delimiter, and `&` in the replacement. One `u` undoes the whole substitution.

**Commenting** with `gc`: `gcc` for a line, `gcip` for a paragraph, `gc` on a selection. The block toggles as one, as in Neovim, with the marker the file's syntax uses and `:set commentstring` for the rest.

**Shell commands** as vi has them: `:%!sort` and `!ip` run lines through a command and put back what it prints, `:!make` runs one, and `:w !wc -w` hands it the buffer. A command that fails leaves the text alone.

**Marks**: `ma` puts one down, `` `a `` comes back to the character and `'a` to the first non-blank of that line. Every jump leaves a mark, so `` `` `` returns from a `G` or a search. `:marks` lists them. They are not shifted when the text moves, which is the one place this is smaller than vi.

**Macros**: `qa` records into register `a`, `q` stops, `@a` plays, `3@a` plays three times, `@@` repeats the last. They share storage with the yank registers the way vi's do, so `"ap` pastes a macro as text and `@a` runs a yanked line. A macro that calls itself stops with a message rather than a stack that runs out.

**Several files at once** with `:e :ls :bn :bp :b`, split windows with `:sp` and `:vsp`, and `<C-w>` then `w s v c o` or `h j k l` to move between them. `<C-p>` and `:find` are a fuzzy picker over the project: type a few letters of the path and it opens in the current window.

**Find in project** on `<C-g>` or `:grep`: a box that searches on every keystroke, grouped by file, with the match underlined where it actually is. `^A` case, `^W` whole word and `^R` regex are shown rather than hidden — a search box whose rules you cannot see is one you stop trusting the first time it misses something you know is there.

<kbd>Enter</kbd> fills the **quickfix list** and jumps, as vim's `:grep` does. `:copen` shows the list with a line of context either side, `:cn` and `:cp` walk it, <kbd>Enter</kbd> in the pane goes to the entry under the cursor, and `:cdo s/from/to/g` rewrites every line in it and writes the files. The pane is an ordinary buffer whose text is built from the list, which is what saves the editor from growing a second kind of window.

**The system clipboard** on `"+y` and `"+p`. A copy goes out over OSC 52 *and* a local helper, so it crosses an ssh session; a put needs the helper, because reading back means waiting for the terminal to answer and a terminal that ignores the request never does.

**Your terminal's own mouse still works.** TurboVI does not turn mouse reporting on, so double-click, triple-click, drag, <kbd>Cmd</kbd>+<kbd>C</kbd> and <kbd>Cmd</kbd>+<kbd>V</kbd> all do what they do everywhere else. Mouse reporting is a mode of the *terminal*: switching it on would hand this editor click coordinates and take selecting and copying away from the terminal, and no program can have both. A paste arrives as text rather than as commands, however big it is and whatever mode you are in.

**Markdown, rendered.** `gR` shows a Markdown file laid out and coloured, read-only but with every motion, search and yank working on it, and `gR` again goes back to the source on the same word. `i`, `a` or `o` go back to the source as well and start typing there, so you can fix a typo the moment you read it. Lines are 80 columns at most, `:set readerwidth` to change it. <kbd>Enter</kbd> follows a link and `<C-o>` comes back. `:render html lynx -dump -stdin -width={width}` renders any other format through a command.

**Syntax colouring** from the file's name. `:set syntax=rust` colours a file with no suffix, `:set nosyntax` stops. A search hit and a selection paint over the colouring, because finding something inside a comment has to be visible.

**`.editorconfig`, honoured.** Read from the buffer's own directory upwards, stopping at the first `root = true`, with the nearest section winning: `indent_style`, `indent_size`, `tab_width`, `end_of_line`, `insert_final_newline` and `trim_trailing_whitespace`. Hand-rolled rather than taking a second dependency. **`charset` is deliberately ignored** — the encoding is *detected* from the bytes, and a config file overriding that would silently re-encode every file it was wrong about.

**A file opens and saves as itself.** The encoding, the line endings and whether the last line had a newline are read once and written back unchanged. A latin-1 file stays latin-1, a CRLF file stays CRLF, and a file with no trailing newline does not gain one.

## Settings and recovery

Settings live in `$XDG_CONFIG_HOME/turbovi/config`, a file of ex commands the way a `vimrc` is:

```
set nu
set rnu
sp
```

A modified buffer is copied to `$XDG_DATA_HOME/turbovi/recover/` every few seconds, keyed by a hash of its absolute path, and `:recover` puts it back after a crash without writing anything to disk. The recovery copy is dropped when the buffer is saved.

## What it is not

Not a vim: no plugins, no scripting language, no `:g`, no folds, no tabs, no persistent undo across sessions yet. Searches are Python `re` rather than vim's own dialect. [Differences from vim](https://turbovi.lab.abilian.com/reference/vim/) lists every place it behaves differently, on purpose or not yet.

## Built on turbodesk

[turbodesk](https://turbodesk.lab.abilian.com) is the immediate-mode terminal UI library underneath. This editor is the application on it that **draws its own buffer**: views, events and hooks, with no `editor()` widget under the text. That is what proved the core carries a real application on its own. Two dialogs are the library's, the `<C-p>` file picker and the frame around the find box. It lived in that repository as `examples/vi/` until 2026-08-26; a smaller showcase version stays there.
