diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 7f4f0c825..ee6aa79fd 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -14,6 +14,7 @@ - [Key & Mouse Binding](config/keys.markdown) - [Colors & Appearance](config/appearance.markdown) - [Lua Reference](config/lua.markdown) +- [Scrollback](scrollback.markdown) - [Hyperlinks](hyperlinks.markdown) - [Shell Integration](shell-integration.markdown) - [iTerm Image Protocol](imgcat.markdown) diff --git a/docs/changelog.markdown b/docs/changelog.markdown index 2669fa467..19e11a435 100644 --- a/docs/changelog.markdown +++ b/docs/changelog.markdown @@ -20,12 +20,8 @@ brief notes about them may accumulate here. `action=wezterm.action{ActivateTab=i-1}` to pass the integer argument. * Windows: now also available with a setup.exe installer * Added `ClearScrollback` key assignment to clear the scrollback. This is bound to CMD-K and CTRL-SHIFT-K by default. -* Added `Search` key assignment to search the scrollback. This is bound to - CMD-F and CTRL-SHIFT-F by default. It activates the search overlay; type (or - paste) to enter a search pattern and highlight matches. Pressing Enter (or - CTRL-P) advances to an earlier match, CTRL-N to a later match. Escape - cancels the search overlay. CTRL-R cycles through case sensitive, insensitive - and regex matching modes while the search overlay is active. +* Added `Search` key assignment to search the scrollback. Read the new + [scrollback](scrollback.html) section for more information! * Fixed an issue where ALT+number would send the wrong output for European keyboard layouts on macOS and Linux. As part of this the default behavior has changed: we used to force ALT+number to produce ALT+number instead of diff --git a/docs/config/keys.markdown b/docs/config/keys.markdown index a238ca1ed..7c5c236a3 100644 --- a/docs/config/keys.markdown +++ b/docs/config/keys.markdown @@ -637,3 +637,27 @@ If a selection is in progress, acts as though `CompleteSelection` was triggered. Otherwise acts as though `OpenLinkAtMouseCursor` was triggered. +## Search + +This action will trigger the search overlay for the current tab. +It accepts a typed pattern string as its parameter, allowing for +`Regex`, `CaseSensitiveString` and `CaseInSensitiveString` as +pattern matching types. + +The supported [regular expression syntax is described +here](https://docs.rs/regex/1.3.9/regex/#syntax). + + +```lua +local wezterm = require 'wezterm'; +return { + keys = { + -- search for things that look like git hashes + {key="H", mods="SHIFT|CTRL", action=wezterm.action{Search={Regex="[a-f0-9]{6,}"}}}, + -- search for the lowercase string "hash" matching the case exactly + {key="H", mods="SHIFT|CTRL", action=wezterm.action{Search={CaseSensitiveString="hash"}}}, + -- search for the string "hash" matching regardless of case + {key="H", mods="SHIFT|CTRL", action=wezterm.action{Search={CaseInSensitiveString="hash"}}}, + }, +} +``` diff --git a/docs/features.markdown b/docs/features.markdown index 94f3a017c..3b1fed0db 100644 --- a/docs/features.markdown +++ b/docs/features.markdown @@ -4,7 +4,7 @@ * [Multiplex terminal tabs and windows on local and remote hosts, with native mouse and scrollback](multiplexing.html) * Ligatures, Color Emoji and font fallback, with true color and [dynamic color schemes](config/appearance.html#colors). * [Hyperlinks](hyperlinks.html) -* Scrollback (use mouse wheel and `Shift-PageUp` and `Shift PageDown`) +* [Searchable Scrollback](scrollback.html) (use mouse wheel and `Shift-PageUp` and `Shift PageDown` to navigate, Ctrl-Shift-F to activate search mode) * xterm style selection of text with mouse; paste selection via `Shift-Insert` (bracketed paste is supported!) * SGR style mouse reporting (works in vim and tmux) * Render underline, double-underline, italic, bold, strikethrough (most other terminal emulators do not support as many render attributes) diff --git a/docs/scrollback.markdown b/docs/scrollback.markdown new file mode 100644 index 000000000..166c10228 --- /dev/null +++ b/docs/scrollback.markdown @@ -0,0 +1,116 @@ +## 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](config/files.html) 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. + +```lua +return { + -- How many lines of scrollback you want to retain per tab + 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](config/keys.html#clearscrollback) docs for information +on rebinding this key. + +### Enable/Disable scrollbar + +You can control whether WezTerm displays a scrollbar via your configuration +file: + +```lua +return { + -- 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 + enable_scroll_bar = true, +} +``` + +You may [change the color of the scrollbar](config/appearance.html#defining-your-own-colors) 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](config/keys.html#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` and `CTRL-P` will cause the selection to move to any prior matching text +* `CTRL-N` will cause the selection to move to any next matching text +* `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](https://docs.rs/regex/1.3.9/regex/#syntax). + The matching mode is indicated in the search bar. +* `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. + +### Configuring Saved Searches + +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: + +```lua +local wezterm = require 'wezterm'; +return { + 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](config/keys.html#search) for more information on +using the `Search` action.