How to Clear WezTerm Viewport While Preserving Scrollback with a Custom Keybindi

by

Summary

Effortlessly clear the viewport in WezTerm without losing scrollback:
By customizing your wezterm.lua you can emulate Windows PowerShell’s Ctrl+L behavior – clearing the visible screen while preserving the scroll history.

Root Cause

  • The default action ClearScrollbackAndViewport merges the viewport clear with scrubbing the scrollback buffer.
  • WezTerm exposes a separate action, ClearViewport, that only clears the visible area, keeping the scrollback intact.

Why This Happens in Real Systems

  • Terminal emulators often unify “clear screen” and “clear history” as a single command to reduce complexity.
  • Users rarely need the scrollback preserved when a screen is refreshed; defaults favor a clean slate.
  • Custom keybindings can override this behavior, but the wrong action constant must be used.

Real-World Impact

  • With the wrong binding

    • Pressing Ctrl+L deletes all past output.
    • Users lose context, making debugging or manual verification harder.

  • With the correct binding

    • The viewport collapses, but all previous lines stay scrollable.
    • Users retain full history while having a tidy workspace.

Example Code (if necessary and relevant)

local wezterm = require 'wezterm'

local config = {}

-- Ensure the `keys` table exists
config.keys = config.keys or {}

-- Map Ctrl+L to clear only the viewport, preserving scrollback
table.insert(config.keys, {
  key  = 'l',
  mods = 'CTRL',
  action = wezterm.action.ClearViewport,
})

return config

How Senior Engineers Fix It

  1. Identify the correct action – use ClearViewport instead of ClearScrollbackAndViewport.
  2. Add the binding in a dedicated section of the wezterm.lua to keep configurations readable.
  3. Test on the target platform (Windows, macOS, Linux) to ensure the key combination behaves as expected.
  4. Document the change in the project wiki or README so others reuse the pattern.

Why Juniors Miss It

  • Assuming a single “clear screen” command covers all use cases.
  • Overlooking the action namespace (ClearViewport vs. ClearScrollbackAndViewport).
  • Skipping alphabetical reads of docs – the key bind vocabulary in WezTerm is case‑sensitive.
  • Adding code inside prose – leading to syntax errors or mis‑displayed config files.

Leave a Comment