Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Scrollback

Scrollback is the history that has scrolled off the top of the screen, kept so you can scroll back and read it.

It’s also where a terminal’s memory goes. Most of what a terminal holds is its screen contents and scrollback, and a program can write forever. So you need to decide how much history to keep, and if you’re running a lot of terminals, what to do about the memory it takes.

The default limit is small, so nearly every terminal wants to set its own. The scrollbar and the compression sections are only for those who need them. Most programs never need compression.

Limits

Scrollback has two limits, and both are set with their corresponding setter. If you set both, the first one reached is used.

OptionDefaultusize::MAXNone
Terminal::set_scrollback_max_bytes()10,000 bytesNo limitRestores the default
Terminal::set_scrollback_max_lines()No limitNo limitNo limit
// Keep up to 10 MB of history.
terminal.set_scrollback_max_bytes(Some(10 * 1024 * 1024))?;

They’re useful together, because each one depends on things you don’t control. The byte limit is reached with fewer lines if the program uses more styles, and the line limit is reached sooner with a narrower terminal.

Both limits are estimates. History lives in pages, the smallest unit of grid space we allocate, and we only prune whole pages. A page is about 400 KB at the time of writing, so the byte limit is accurate to about that much, and the default of 10,000 bytes is one page in practice. The line limit almost always keeps more lines than you asked for, usually somewhere from dozens to a hundred or so.

Lowering a limit removes eligible complete pages right away. A byte limit of zero disables scrollback and erases the history you have.

Read the limits back with Terminal::scrollback_max_bytes() and Terminal::scrollback_max_lines(). They return None when the limit is unlimited, and they always report the primary screen’s value, even while the alternate screen is active.

Scrolling the viewport

The viewport is the part of the terminal you’re showing. Move it with Terminal::scroll_viewport(), which takes a tagged union:

TagWhat it does
ScrollViewport::TopScroll to the top of the scrollback
ScrollViewport::BottomScroll to the bottom (the active area)
ScrollViewport::DeltaScroll by a number of rows, negative for up
ScrollViewport::RowScroll so that this row is the first one visible
ScrollViewport::DeltaPromptScroll by a number of prompts, negative for backward
terminal.scroll_viewport(ScrollViewport::Delta(-5))?; // up 5 rows

Row 0 is the top of the scrollback. The row is clamped so the viewport never scrolls past the top of the active area. With no scrollback, such as on the alternate screen, the viewport stays on the active area.

Scrolling by prompts needs semantic prompt markers from the shell. Without a matching prompt it does nothing.

Terminal::viewport_active() tells you if the viewport is following the active area, or if someone has scrolled up into history.

The scrollbar

Read Terminal::scrollbar() to get a terminal::Scrollbar, which has the three numbers you need to draw one: total rows in the scrollable area, the offset of the viewport into them, and the len of the visible area.

There’s no notification when these change, and that’s on purpose. Poll once per frame or once per write batch and compare the result with the last one. This is what Ghostty’s own renderer does. It’s cheap, because we keep the total up to date as the terminal changes and cache the offset. The one exception is the first read after the viewport moves somewhere that isn’t an absolute row, which can cost O(pages).

The offset is the same row space as ScrollViewport::Row, so when someone drags your scrollbar you can scroll straight to the position you drew.

let bar = terminal.scrollbar()?;

// Someone dragged the scrollbar halfway down.
let row = (bar.total - bar.len) / 2;
terminal.scroll_viewport(ScrollViewport::Row(row as usize));

If you only want counts, Terminal::total_rows() is the rows in the active screen including scrollback, and Terminal::scrollback_rows() is the rows in scrollback.

Resizing

By default, a resize can pull rows out of scrollback and back into the active area. Growing the rows reveals scrollback if the cursor is on the bottom row, and a column reflow that needs fewer rows reveals it too.

Most programs want this and can skip this section. But if your pty keeps its own screen buffer without scrollback, it can’t pull rows back, and it will disagree with the terminal about the screen after a resize. Windows ConPTY is the case that needs this. Call Terminal::set_resize_pull_scrollback() with false:

terminal.set_resize_pull_scrollback(false)?;

Now growing the rows always appends blank rows at the bottom, and a column reflow keeps the top of the active area on the same content. A line that’s fully in scrollback stays there, but a soft-wrapped line with at least one row still in the active area can still unwrap back into view. The setting survives a full reset (RIS).

Memory use

Read Terminal::memory_usage() to see how much memory a terminal holds. This is for applications that host many terminals and have to stay inside a budget, for example by compressing or closing whichever ones hold the most. The read never decompresses scrollback, but it does look at every page, so don’t do it after every write.

Budget against the resident bytes. That’s the physical memory the pages use right now. Virtual bytes are the address space reserved for pages.

Each screen has its own fields, with a primary_ or alternate_ prefix, so add them together for the terminal’s total. The primary screen holds shell output and all of the scrollback. The alternate screen is used by full-screen programs such as text editors, and its fields are zero until a program first switches to it.

Colors, styles and hyperlinks are stored in pages, so they’re already in the page figures. Images are stored separately and have their own fields. Small things outside of pages, such as the window title and internal bookkeeping, aren’t counted. They’re small next to the pages once a terminal has any scrollback.

On macOS, the system takes back memory freed by compression lazily, when something else needs it. Until then, the memory the system reports for your process (its RSS) can be higher than the resident figures here.

/// Return the bytes of memory a terminal currently holds. A server hosting
/// many terminals can compare this figure across terminals to decide which
/// one to compress or shut down first.
fn terminal_resident_bytes(terminal: &Terminal<'_, '_>) -> Result<u64, Error> {
    let usage = terminal.memory_usage()?;

    // Count both screens and any images. The alternate screen reports zero
    // until a program such as a full-screen editor first switches to it.
    Ok(usage.primary_resident_bytes
        + usage.primary_image_bytes
        + usage.alternate_resident_bytes
        + usage.alternate_image_bytes)
}

Full program: rust-vt-compression/src/main.rs

Compression

Old scrollback is mostly sitting there, so we can compress it. This changes how the history is stored and nothing else. The contents and the scrollback limit stay the same, and reading compressed history restores it transparently.

You drive it. libghostty-vt doesn’t create a timer or a background thread, so nothing is compressed until you ask. The shape is an idle timer: restart it when the terminal changes, and when it fires, compress a step at a time until there’s nothing left to do.

Terminal::compression_activity() returns an opaque token. Only compare it for equality, because it can wrap, and a change in either direction means the same thing. It changes only when compression-relevant state changes, so restart your idle timer when it does.

    let mut activity = terminal.compression_activity()?;

    // Terminal mutations may change the token. When it changes, restart the
    // application's idle timer rather than compressing on the output path.
    for _ in 0..4000 {
        terminal.vt_write(b"repeated and compressible terminal history\r\n");
    }

    let new_activity = terminal.compression_activity()?;
    if activity != new_activity {
        activity = new_activity;
        // Restart the application's compression idle timer here.
    }

Full program: rust-vt-compression/src/main.rs

When the timer fires, call Terminal::compress with CompressionMode::Incremental, which does a bounded amount of work. There are three results:

/// Perform one step after the application's idle timer fires. Returning true
/// asks the application to schedule another step while the terminal is idle.
fn compression_idle_step(terminal: &mut Terminal<'_, '_>) -> Result<bool, Error> {
    match terminal.compress(CompressionMode::Incremental)? {
        CompressionResult::Pending => Ok(true),
        CompressionResult::Unsupported | CompressionResult::Complete => Ok(false),
        _ => unreachable!(),
    }
}

Full program: rust-vt-compression/src/main.rs

Complete means the pass finished, not that every page was compressed. Compression is opportunistic. A page can be unprofitable to compress, or hit an allocation or reclamation failure.

CompressionMode::Full does one synchronous scan of every eligible page instead. It can stall on large scrollback.

Terminal::compress isn’t thread-safe with anything else on the same terminal, so serialize it with your writes, rendering, searches and other terminal access.

Compression lowers the resident figure but not the virtual one, because each page’s space stays reserved for decompression.