Skip to content

Scrollback

WezTerm provides a searchable scrollback buffer with a configurable maximum size limit that allows you to review information that doesn't fit in the physical window size. As content is printed to the display the display may be scrolled up to accommodate newly added lines. The scrolled lines are moved into the scrollback buffer and can be reviewed by scrolling the window up or down.

This section describes working with the scrollback and discusses some configuration options; be sure to read the configuration docs to learn how to change your settings!

Controlling the scrollback size

This value serves as an upper bound on the number of lines. The larger this value, the more memory is required to manage the tab. If you have a lot of long lived tabs then making this value very large may put some pressure on your system depending on the amount of RAM you have available.

-- How many lines of scrollback you want to retain per tab
config.scrollback_lines = 3500

Clearing the scrollback buffer

By default, CTRL-SHIFT-K and CMD-K will trigger the ClearScrollback action and discard the contents of the scrollback buffer. There is no way to undo discarding the scrollback.

See the ClearScrollback docs for information on rebinding this key.

Enable/Disable scrollbar

You can control whether WezTerm displays a scrollbar via your configuration file:

-- Enable the scrollbar.
-- It will occupy the right window padding space.
-- If right padding is set to 0 then it will be increased
-- to a single cell width
config.enable_scroll_bar = true

You may change the color of the scrollbar if you wish!

Scrolling without a scrollbar

By default, SHIFT-PageUp and SHIFT-PageDown will adjust the viewport scrollback position by one full screen for each press.

See the ScrollByPage docs for more information on this key binding assignment.

Searching the scrollback

By default, CTRL-SHIFT-F and CMD-F (F for Find) will activate the search overlay in the current tab.

When the search overlay is active the behavior of wezterm changes:

  • Typing (or pasting) text will populate the search pattern in the bar at the bottom of the screen.
  • Text from the scrollback that matches the search pattern will be highlighted and the number of matches shown in the search bar.
  • The bottom-most match will be selected and the viewport scrolled to show the selected text.
  • Enter, UpArrow and CTRL-P will cause the selection to move to any prior matching text.
  • PageUp will traverse to previous matches one page at a time.
  • CTRL-N and DownArrow will cause the selection to move to any next matching text.
  • PageDown will traverse to the next match one page at a time.
  • CTRL-R will cycle through the pattern matching mode; the initial mode is case-sensitive text matching, the next will match ignoring case and the last will match using the regular expression syntax described here. The matching mode is indicated in the search bar.
  • CTRL-U will clear the search pattern so you can start over.
  • CTRL-SHIFT-C will copy the selected text to the clipboard.
  • Escape will cancel the search overlay, leaving the currently selected text selected with the viewport scrolled to that location.

Configurable search mode key assignments

Since: Version 20220624-141144-bd1b7c5d

The functionality described in this section requires version 20220624-141144-bd1b7c5d of wezterm, or a more recent version.

The key assignments for search mode are specified by the search_mode Key Table.

You may use wezterm.gui.default_key_tables to obtain the defaults and extend them. In earlier versions of wezterm there wasn't a way to override portions of the key table, only to replace the entire table.

The default configuration at the time that these docs were built (which may be more recent than your version of wezterm) is shown below.

You can see the configuration in your version of wezterm by running wezterm show-keys --lua --key-table search_mode.

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  key_tables = {
    search_mode = {
      { key = 'Enter', mods = 'NONE', action = act.CopyMode 'PriorMatch' },
      { key = 'Escape', mods = 'NONE', action = act.CopyMode 'Close' },
      { key = 'n', mods = 'CTRL', action = act.CopyMode 'NextMatch' },
      { key = 'p', mods = 'CTRL', action = act.CopyMode 'PriorMatch' },
      { key = 'r', mods = 'CTRL', action = act.CopyMode 'CycleMatchType' },
      { key = 'u', mods = 'CTRL', action = act.CopyMode 'ClearPattern' },
      {
        key = 'PageUp',
        mods = 'NONE',
        action = act.CopyMode 'PriorMatchPage',
      },
      {
        key = 'PageDown',
        mods = 'NONE',
        action = act.CopyMode 'NextMatchPage',
      },
      { key = 'UpArrow', mods = 'NONE', action = act.CopyMode 'PriorMatch' },
      { key = 'DownArrow', mods = 'NONE', action = act.CopyMode 'NextMatch' },
    },
  },
}

(Those assignments reference CopyMode because search mode is a facet of Copy Mode).

Configuring Saved Searches

Since: Version 20200607-144723-74889cd4

The functionality described in this section requires version 20200607-144723-74889cd4 of wezterm, or a more recent version.

If you find that you're often searching for the same things then you may wish to assign a keybinding to trigger that search.

For example, if you find that you're frequently running git log and then reaching for your mouse to copy and paste a relevant git commit hash then you might like this:

config.keys = {
  -- search for things that look like git hashes
  {
    key = 'H',
    mods = 'SHIFT|CTRL',
    action = wezterm.action.Search { Regex = '[a-f0-9]{6,}' },
  },
}

With that in your config you can now:

  • CTRL-SHIFT-H to highlight all the git hashes and select the closest one to the bottom of the screen.
  • Use ENTER/CTRL-N/CTRL-P to cycle through the git hashes
  • CTRL-SHIFT-C to copy
  • Escape
  • CTRL-SHIFT-V (or SHIFT-Insert) to Paste

without needing to reach for your mouse.

See the Search action docs for more information on using the Search action.