From 5fd2973b9a53ca639e82f1db178587f553dc6e0a Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 27 Jul 2026 07:29:25 -0700 Subject: [PATCH] lib-vt: better docs for C options --- include/ghostty/vt/terminal.h | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/include/ghostty/vt/terminal.h b/include/ghostty/vt/terminal.h index d28ba2b50..8aaa57e9b 100644 --- a/include/ghostty/vt/terminal.h +++ b/include/ghostty/vt/terminal.h @@ -872,6 +872,17 @@ typedef enum GHOSTTY_ENUM_TYPED { /** * Set the maximum scrollback allocation in bytes. * + * This is an estimate. Internally, libghostty only prunes bytes up + * to a "page"-granularity. A page is the minimum allocated unit of + * grid space within Ghostty. A page at the time of writing these docs + * is about 400KB, so the byte limit will be within this delta. + * + * This works alongside the line limit configuration. If both are set, + * the first-reached limit is used first. Both limits are dependent + * on external state (byte limit can be reached with less lines if + * more styles are used for example, line limit can be reached with + * a narrower terminal viewport). So, they are useful together. + * * Lowering the limit immediately removes eligible complete historical * pages. A value of zero disables scrollback and erases retained history. * A NULL value pointer removes the byte limit. @@ -883,6 +894,20 @@ typedef enum GHOSTTY_ENUM_TYPED { /** * Set the maximum number of physical lines retained in scrollback. * + * This is an estimate. Internally, libghostty only prunes lines up + * to a "page"-granularity. A page is the minimum allocated unit of + * grid space within Ghostty. As a result, the actual available scrollback + * lines will almost always be higher than configured. The magnitude + * of the difference depends on the number of used styles, graphemes, etc. + * since the row-count in a page is dynamic based on that. In general, + * it ranges from dozens to a hundred or so lines. + * + * This works alongside the line limit configuration. If both are set, + * the first-reached limit is used first. Both limits are dependent + * on external state (byte limit can be reached with less lines if + * more styles are used for example, line limit can be reached with + * a narrower terminal viewport). So, they are useful together. + * * Lowering the limit immediately removes eligible complete historical * pages. A NULL value pointer removes the line limit. *