Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 24 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,24 +195,15 @@ Normal letter keys exit copy mode and send the key to the terminal.
| `C-c C-n` | Jump to next prompt |
| `C-c C-p` | Jump to previous prompt |
| `C-l` | Recenter viewport |
| `C-c C-a` | Load full scrollback into buffer |
| `C-c C-t` | Exit without copying |
| `a`–`z` | Exit and send key to terminal |

Soft-wrapped newlines are automatically stripped from copied text.

After `C-c C-a`, the entire scrollback history is loaded into the buffer
as styled text. Standard Emacs commands work across the full content:
`C-x h` to select all, `C-s` to search, mark/region spanning any distance.

Set `ghostel-copy-mode-auto-load-scrollback` to `t` to skip the
viewport-only step and load the full scrollback immediately when
entering copy mode. Advantages: produces a pure Emacs buffer where
all standard commands work (incremental search, `occur`, `M-x
flush-lines`, etc.) without an extra keystroke. Disadvantages: entering
copy mode takes longer for large scrollback buffers, clickable links
(URLs, file references, OSC 8 hyperlinks) are not detected in the
loaded scrollback.
The full scrollback is always rendered into the buffer as styled text,
so `isearch`, `consult-line`, `occur`, `M-x flush-lines`, `C-x h` to
select all, and any other buffer-based command work across the full
history — even outside copy mode.

## Features

Expand All @@ -223,7 +214,7 @@ loaded scrollback.
- Text attributes: bold, italic, faint, underline (single/double/curly/dotted/dashed with color), strikethrough, inverse
- Cursor styles: block, bar, underline, hollow block
- Alternate screen buffer (for TUI apps like htop, vim, etc.)
- Scrollback buffer (configurable, default 20MB (~10,000 lines))
- Scrollback buffer (configurable, default 5 MB (~5,000 lines), materialized into the Emacs buffer so `isearch`/`consult-line` work over history)

### Links and File Detection
- **OSC 8 hyperlinks** — clickable URLs emitted by terminal programs (click or `RET` to open)
Expand Down Expand Up @@ -395,7 +386,7 @@ individual faces with `M-x customize-face`.
| `ghostel-tramp-default-method` | `nil` | TRAMP method for new remote paths from OSC 7 (nil uses `tramp-default-method`) |
| `ghostel-tramp-shell-integration` | `nil` | Auto-inject shell integration for remote TRAMP sessions |
| `ghostel-buffer-name` | `"*ghostel*"` | Default buffer name |
| `ghostel-max-scrollback` | `20MB` | Maximum scrollback size in bytes |
| `ghostel-max-scrollback` | `5MB` | Maximum scrollback size in bytes (materialized into the Emacs buffer; ~5,000 rows on 80-col terminals) |
| `ghostel-timer-delay` | `0.033` | Base redraw delay in seconds (~30fps) |
| `ghostel-adaptive-fps` | `t` | Adaptive frame rate (shorter delay after idle, stop timer when idle) |
| `ghostel-immediate-redraw-threshold` | `256` | Max output bytes to trigger immediate redraw (0 to disable) |
Expand All @@ -408,7 +399,6 @@ individual faces with `M-x customize-face`.
| `ghostel-enable-url-detection` | `t` | Linkify plain-text URLs in terminal output |
| `ghostel-enable-file-detection` | `t` | Linkify file:line references in terminal output |
| `ghostel-keymap-exceptions` | `("C-c" "C-x" ...)` | Keys passed through to Emacs |
| `ghostel-copy-mode-auto-load-scrollback` | `nil` | Load full scrollback automatically when entering copy mode |
| `ghostel-exit-functions` | `nil` | Hook run when the shell process exits |

## Evil-mode
Expand Down Expand Up @@ -498,16 +488,18 @@ terminal emulators: [vterm](https://github.com/akermu/emacs-libvterm) (native
module), [eat](https://codeberg.org/akib/emacs-eat) (pure Elisp), and Emacs
built-in `term`.

The primary benchmark streams 1 MB of data through a real process pipe,
matching actual terminal usage. Results on Apple M4 Max, Emacs 31.0.50:
The primary benchmark streams 5 MB of data through a real process pipe,
matching actual terminal usage. All backends are configured with ~1,000
lines of scrollback (matching vterm's default). Results on Apple M4 Max,
Emacs 31.0.50:

| Backend | Plain ASCII | URL-heavy |
|----------------------|------------:|----------:|
| ghostel | 72 MB/s | 26 MB/s |
| ghostel (no detect) | 74 MB/s | 74 MB/s |
| vterm | 33 MB/s | 27 MB/s |
| eat | 4.4 MB/s | 3.4 MB/s |
| term | 5.4 MB/s | 4.6 MB/s |
| ghostel | 65 MB/s | 42 MB/s |
| ghostel (no detect) | 64 MB/s | 65 MB/s |
| vterm | 29 MB/s | 24 MB/s |
| eat | 3.9 MB/s | 3.0 MB/s |
| term | 4.8 MB/s | 4.1 MB/s |

Ghostel scans terminal output for URLs and file paths, making them clickable.
The "no detect" row shows throughput with this detection disabled
Expand Down Expand Up @@ -571,8 +563,8 @@ powering Neovim's built-in terminal.
| Copy mode | Yes | Yes |
| Drag-and-drop | Yes | No |
| Auto module download | Yes | No |
| Scrollback default | ~10,000 | 1,000 |
| PTY throughput (plain ASCII) | 72 MB/s | 33 MB/s |
| Scrollback default | ~5,000 | 1,000 |
| PTY throughput (plain ASCII) | 65 MB/s | 29 MB/s |
| Default redraw rate | ~30 fps | ~10 fps |

### Key differences
Expand All @@ -599,12 +591,13 @@ bash, zsh, and fish — no shell RC changes needed. vterm requires manually
sourcing scripts in your shell configuration. Both support Elisp eval from
the shell and TRAMP-aware remote directory tracking.

**Performance.** In PTY throughput benchmarks (1 MB streamed through `cat`),
ghostel is roughly 2x faster than vterm on plain ASCII data (72 vs 33 MB/s).
On URL-heavy output the gap narrows as ghostel's link detection adds overhead,
but with detection disabled ghostel reaches 74 MB/s. See the
[Performance](#performance) section above for full numbers and how to run the
benchmark suite yourself.
**Performance.** In PTY throughput benchmarks (5 MB streamed through `cat`,
both backends configured with ~1,000 lines of scrollback), ghostel is
roughly 2x faster than vterm on plain ASCII data (65 vs 29 MB/s). On
URL-heavy output ghostel still comes out ahead of vterm (42 vs 24 MB/s);
with link detection disabled ghostel reaches 65 MB/s regardless of input.
See the [Performance](#performance) section above for full numbers and how
to run the benchmark suite yourself.

**Installation.** Ghostel can automatically download a pre-built native
module or compile from source with [Zig](https://ziglang.org/). vterm uses
Expand Down
6 changes: 4 additions & 2 deletions bench/ghostel-bench.el
Original file line number Diff line number Diff line change
Expand Up @@ -192,8 +192,10 @@ for reliable measurement."
;; ---------------------------------------------------------------------------

(defun ghostel-bench--make-ghostel (rows cols)
"Create a ghostel terminal for benchmarking."
(ghostel--new rows cols ghostel-bench-scrollback))
"Create a ghostel terminal for benchmarking.
`ghostel-bench-scrollback' is in lines (matching vterm/term),
but `ghostel--new' takes bytes — convert at ~1 KB per row."
(ghostel--new rows cols (* ghostel-bench-scrollback 1024)))

(defun ghostel-bench--make-vterm (rows cols)
"Create a vterm terminal for benchmarking."
Expand Down
Loading
Loading