112 lines
4.0 KiB
Markdown
112 lines
4.0 KiB
Markdown
# vterm-editor.el
|
|
|
|
Compose text in a full Emacs buffer and send it to vterm with a single keystroke.
|
|
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
When working inside a vterm terminal, editing multi-line text can be awkward: you lose access to Emacs keybindings, navigation, and editing commands. `vterm-editor` solves this by opening a temporary buffer where you can write comfortably using all of Emacs, then send the result back to vterm.
|
|
|
|
### Without vterm-editor
|
|
|
|
You type directly in the terminal, limited to basic line editing.
|
|
|
|
### With vterm-editor
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ Edit, then C-c C-c to send or C-c C-k to cancel│ ← header line
|
|
├─────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Write freely here with full Emacs power: │
|
|
│ - Multiple cursors, search & replace, etc. │
|
|
│ - Spell checking, auto-complete, snippets │
|
|
│ - Any major/minor mode you want │
|
|
│ │
|
|
└─────────────────────────────────────────────────┘
|
|
│ C-c C-c │ C-c C-k
|
|
▼ ▼
|
|
Text sent to vterm Buffer discarded
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Full Emacs editing**: Write in a regular buffer with all your keybindings and modes available
|
|
- **Bracketed paste**: Sends text using vterm's bracketed paste mode, safe for multi-line content
|
|
- **Simple workflow**: `C-c C-c` to send, `C-c C-k` to cancel
|
|
- **Clean UI**: Header line shows available actions, no clutter in the buffer
|
|
- **Lightweight**: Less than 80 lines of code
|
|
|
|
## Installation
|
|
|
|
### Using `use-package` (Emacs 29+)
|
|
|
|
```elisp
|
|
(use-package vterm-editor
|
|
:ensure t
|
|
:vc (:url "https://git.andros.dev/andros/vterm-editor.el"))
|
|
```
|
|
|
|
Or from a local path:
|
|
|
|
```elisp
|
|
(use-package vterm-editor
|
|
:load-path "~/path/to/vterm-editor")
|
|
```
|
|
|
|
### Manual installation
|
|
|
|
1. Download `vterm-editor.el`
|
|
2. Place it in your Emacs load path
|
|
3. Add to your init file:
|
|
|
|
```elisp
|
|
(require 'vterm-editor)
|
|
```
|
|
|
|
### With a keybinding in vterm
|
|
|
|
```elisp
|
|
(use-package vterm-editor
|
|
:after vterm
|
|
:bind (:map vterm-mode-map
|
|
("C-c e" . vterm-editor-open)))
|
|
```
|
|
|
|
## Usage
|
|
|
|
From any vterm buffer, run:
|
|
|
|
```
|
|
M-x vterm-editor-open
|
|
```
|
|
|
|
A new buffer `*vterm-editor*` opens in `text-mode` with `vterm-editor-mode` enabled. Write your text, then:
|
|
|
|
- **`C-c C-c`**: Send the text to the original vterm buffer and close the editor
|
|
- **`C-c C-k`**: Discard the text and close the editor without sending anything
|
|
|
|
The editor buffer is killed after either action, and focus returns to vterm.
|
|
|
|
## How it works
|
|
|
|
1. `vterm-editor-open` saves a reference to the current vterm buffer
|
|
2. A temporary `*vterm-editor*` buffer opens via `pop-to-buffer`
|
|
3. On `C-c C-c`, the buffer content is sent using `vterm-send-string` with the `paste-p` flag enabled (bracketed paste mode), which wraps the text in terminal escape sequences (`\e[200~`...`\e[201~`) so the shell treats it as pasted content rather than executed commands
|
|
4. `quit-window` kills the editor buffer and restores the previous window layout
|
|
|
|
## Requirements
|
|
|
|
- Emacs 25.1 or higher
|
|
- [emacs-libvterm](https://github.com/akermu/emacs-libvterm) (vterm)
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please see the [contribution guidelines](https://git.andros.dev/andros/contribute) for instructions on how to submit issues or pull requests.
|
|
|
|
## License
|
|
|
|
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
|