Metadata-Version: 2.4
Name: turbovi
Version: 0.3.1
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.2
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# TurboVI

A vi clone for the terminal: modes, counts, operators, registers, marks, macros, split windows and `:s`, in about three thousand lines of Python.

```sh
uv sync
uv run turbovi somefile.py
uv run turbovi one.py two.py   # two buffers, :bn between them
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 W B E 0 ^ $ gg G { } f F t T %`. Operators `d c y > <` with doubling (`dd`, `yy`, `cc`), text objects (`iw aw i( a" i{`), and `x X D C s S r ~ J p P o O`.

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

**Paging** with `<C-f>` `<C-b>` `<C-d>` `<C-u>`, by the window rather than by a fixed number, and `<C-e>` / `<C-y>` to move the view without moving the cursor.

**Search** with `/ ? n N` and match highlighting. **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.

**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.

**The system clipboard** on `"+y` and `"+p`, over OSC 52 and a local helper, so it crosses ssh.

**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.

**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.

## 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 uses **no widgets at all** — views, events and hooks, nothing else — which is what proved the core carries a real application on its own. It lived in that repository as `examples/vi/` until 2026-08-26; a smaller showcase version stays there.
