Is there a way to clear screen and save contents in scrollback?

[chenzhiwei]

What Operating System(s) are you running on?

Linux Wayland

Which Wayland compositor or X11 Window manager(s) are you using?

No response

WezTerm version

20230712-072601-f4abf8fd

Ask your question!

I want to clear the screen and later scrollback to check the contents.

After some investigation I found binding \e[nS and \e[nA (n is for n lines) to Ctrl+L in Wezterm can implement this feature, this works in Linux, but does not work in Windows.

Kitty has following in the document: https://sw.kovidgoyal.net/kitty/conf/#shortcut-kitty.Reset-the-terminal

clear-only-screen() {
    printf "\e[H\e[2J"
}

clear-screen-and-scrollback() {
    printf "\e[H\e[3J"
}

clear-screen-saving-contents-in-scrollback() {
    printf "\e[H\e[22J"
}

I know Wezterm has ClearScrollback action, want to ask whether Wezterm can add ClearScreen action with above behaviors.

https://wezfurlong.org/wezterm/config/lua/keyassignment/ClearScrollback.html

[bew]

note: You already asked this question last year ^^
#2405

@wez replied at the time he didn't want this (non-conform) behavior in Wezterm.

This works in Linux, but does not work in Windows.

Might need some debugging here, see where it's not working exactly.

[chenzhiwei]

The bash bind has limitations which do not work on remote shell.

It will be great if Wezterm can implement this feature.

[ismk]

Second this, It would be great to have a feature that allows us to clear the viewport without impacting the scrollback buffer.

[wez]

I think there is some confusion around this functionality.

There is an ED escape sequence for erasing content in the display.
ED, as implemented in wezterm, supports the following parameters:

• \e[J - Erase to End of Display. Erases the content from the cursor to the bottom of the viewport
• \e[1J - Erase to Start of Display. Erases from the cursor to the top of the viewport
• \e[2J - Erase Display - clears the viewport, regardless of cursor position
• \e[3J - Erase the scrollback, not the viewport. This is an xterm extension.

Separately, there is a command line utility called clear which ships as part of ncurses. It says that its purpose is to clear the viewport and the scrollback. Its behavior is defined by its own source code, but is driven by terminfo definitions that are outside of the control of wezterm. Ultimately, it should emit the \e[2J sequence and possibly the \e[3J depending on terminfo.

Separately, many line editors have a keyboard shortcut for CTRL-L that triggers \e[2J. I've never experienced one that will, by default, erase the scrollback.

For the folks above that seem to be asking for a way to clear the viewport without impacting the scrollback: I would expect that to the default in most software, and you will need to check your configuration to see where you may have something configured that behaves differently.

This issue and the other original question were asking for different behavior, which is to move the viewport into the scrollback and then tidy up the viewport.

wezterm doesn't have an escape sequence for this non-standard behavior, but you can script that behavior for yourself; it works by moving the cursor down enough rows that the current viewport is shifted into the scrollback, then injects the CTRL-L keypress which causes most software to clear and re-render the viewport:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.keys = {
  {key='K', mods='CTRL|SHIFT', action=wezterm.action_callback(function(window, pane)
    local pos = pane:get_cursor_position()
    local move_viewport_to_scrollback = string.rep('\r\n', pos.y)
    pane:inject_output(move_viewport_to_scrollback)
    pane:send_text('\x0c') -- CTRL-L
  end)}
}

return config

[ismk]

Hey Wez! first of all thank you so much for the detailed reply. The escape codes makes sense, and you are right the functionality we are asking for is the non-standard which is to move the viewport into the scrollback and then tidy up the viewport.

I know iterm2 isn't cross-platform so it might implement this a bit different but this is what happens in iterm2 when you press CTRL-L

Where as in wezterm if we use CTRL-L it cuts off the text

It seems the issue arises due to the dimensions of the window. Elements within the current viewport are discarded, while those outside it, in the scrollback, are retained. This aligns with your observation in your comment.
Is there an alternative approach to inserting blank lines? Implementing this method results in extensive empty spaces when scrolling up, which is not ideal.
See:

[ismk]

Yes this seems to work! thank you!! 🥇

[chenzhiwei]

@ismk Hi, does this solution work for you? It only works at first time. Reproduce steps:

1. seq 1 100, then CTRL+SHIFT+K, works
2. echo something, then CTRL+SHIFT+K, does not work

[ismk]

@chenzhiwei You are correct. @wez's solution works to a certain extent, but there is a nuance to the behavior depending on the output length. I was able to reproduce the issue you encountered:
When the output is longer than the window size, the scrollback is triggered. In this case, if you run seq 1 100 and the output exceeds the visible area, pressing CTRL+SHIFT+K will clear the screen while preserving the scrollback history.
However, if the output is shorter than the window size and doesn't trigger the scrollback, pressing CTRL+SHIFT+K will clear the screen but will NOT preserve the scrollback history.

To illustrate this behavior, you can try the following:
Run echo something and then press CTRL+SHIFT+K. This will clear the screen but will NOT preserve the scrollback history.
Run seq 1 100 and then press CTRL+SHIFT+K. This will clear the screen and WILL preserve the scrollback history.

The key difference lies in whether the output is long enough to trigger the scrollback. When the output fits within the visible window, pressing CTRL+SHIFT+K clears the screen without preserving the scrollback. However, when the output exceeds the window size and triggers the scrollback, pressing CTRL+SHIFT+K clears the screen while preserving the scrollback history.

[chenzhiwei]

@wez Hi Wez, do you have any other solutions?

[wez]

Sorry to say that I have no time or inclination to look at this in any detail