Skip to content

Copy Mode

Since: Version 20200607-144723-74889cd4

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

Copy mode allows you to make selections using the keyboard; no need to reach for your mouse or trackpad. Copy mode is similar to quick select mode but is geared up for describing selections based on keyboard control, whereas quick select mode is used to quickly select and copy commonly used patterns. The colors of the highlighted/selected text can be configured.

The ActivateCopyMode key assignment is used to enter copy mode; it is bound to CTRL-SHIFT-X by default.

When copy mode is activated, the title is prefixed with "Copy Mode" and the behavior of the tab is changed; keyboard input now controls the cursor and allows moving it through the scrollback, scrolling the viewport as needed, in a style similar to that of the Vim editor.

Move the cursor to the start of the region you wish to select and press v to toggle selection mode (it is off by default), then move the cursor to the end of that region. You can then use Copy (by default: CTRL-SHIFT-C) to copy that region to the clipboard.

Key Assignments

The default key assignments in copy mode are as follows:

Action Key Assignment
Activate copy mode Ctrl + Shift + X
Copy and exit copy mode y
Exit copy mode Esc
Ctrl + C
Ctrl + G
q
Cell selection v
Line selection Shift + V
Rectangular selection Ctrl + V (Since: Version 20220624-141144-bd1b7c5d)
Move Left LeftArrow
h
Move Down DownArrow
j
Move Up UpArrow
k
Move Right RightArrow
l
Move forward one word Alt + RightArrow
Alt + F
Tab
w
Move backward one word Alt + LeftArrow
Alt + B
Shift + Tab
b
Move forward one word end e (Since: Version 20230320-124340-559cb7b0)
Move to start of this line 0
Home
Move to start of next line Enter
Move to end of this line $
End
Move to start of indented line Alt + M
^
Move to bottom of scrollback Shift + G
Move to top of scrollback g
Move to top of viewport Shift + H
Move to middle of viewport Shift + M
Move to bottom of viewport Shift + L
Move up one screen PageUp
Ctrl + B
Move up half a screen Ctrl + U (Since: Version 20230320-124340-559cb7b0)
Move down one screen PageDown
Ctrl + F
Move down half a screen Ctrl + D (Since: Version 20230320-124340-559cb7b0)
Move to other end of the selection o
Move to other end of the selection horizontally Shift + O (useful in Rectangular mode)

Configurable 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 copy mode are specified by the copy_mode Key Table.

You may provide your own definition of this key table if you wish to customize it.

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 copy_mode.

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

return {
  key_tables = {
    copy_mode = {
      { key = 'Tab', mods = 'NONE', action = act.CopyMode 'MoveForwardWord' },
      {
        key = 'Tab',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveBackwardWord',
      },
      {
        key = 'Enter',
        mods = 'NONE',
        action = act.CopyMode 'MoveToStartOfNextLine',
      },
      {
        key = 'Escape',
        mods = 'NONE',
        action = act.Multiple {
          { CopyMode = 'ScrollToBottom' },
          { CopyMode = 'Close' },
        },
      },
      {
        key = 'Space',
        mods = 'NONE',
        action = act.CopyMode { SetSelectionMode = 'Cell' },
      },
      {
        key = '$',
        mods = 'NONE',
        action = act.CopyMode 'MoveToEndOfLineContent',
      },
      {
        key = '$',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToEndOfLineContent',
      },
      { key = ',', mods = 'NONE', action = act.CopyMode 'JumpReverse' },
      { key = '0', mods = 'NONE', action = act.CopyMode 'MoveToStartOfLine' },
      { key = ';', mods = 'NONE', action = act.CopyMode 'JumpAgain' },
      {
        key = 'F',
        mods = 'NONE',
        action = act.CopyMode { JumpBackward = { prev_char = false } },
      },
      {
        key = 'F',
        mods = 'SHIFT',
        action = act.CopyMode { JumpBackward = { prev_char = false } },
      },
      {
        key = 'G',
        mods = 'NONE',
        action = act.CopyMode 'MoveToScrollbackBottom',
      },
      {
        key = 'G',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToScrollbackBottom',
      },
      { key = 'H', mods = 'NONE', action = act.CopyMode 'MoveToViewportTop' },
      {
        key = 'H',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToViewportTop',
      },
      {
        key = 'L',
        mods = 'NONE',
        action = act.CopyMode 'MoveToViewportBottom',
      },
      {
        key = 'L',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToViewportBottom',
      },
      {
        key = 'M',
        mods = 'NONE',
        action = act.CopyMode 'MoveToViewportMiddle',
      },
      {
        key = 'M',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToViewportMiddle',
      },
      {
        key = 'O',
        mods = 'NONE',
        action = act.CopyMode 'MoveToSelectionOtherEndHoriz',
      },
      {
        key = 'O',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToSelectionOtherEndHoriz',
      },
      {
        key = 'T',
        mods = 'NONE',
        action = act.CopyMode { JumpBackward = { prev_char = true } },
      },
      {
        key = 'T',
        mods = 'SHIFT',
        action = act.CopyMode { JumpBackward = { prev_char = true } },
      },
      {
        key = 'V',
        mods = 'NONE',
        action = act.CopyMode { SetSelectionMode = 'Line' },
      },
      {
        key = 'V',
        mods = 'SHIFT',
        action = act.CopyMode { SetSelectionMode = 'Line' },
      },
      {
        key = '^',
        mods = 'NONE',
        action = act.CopyMode 'MoveToStartOfLineContent',
      },
      {
        key = '^',
        mods = 'SHIFT',
        action = act.CopyMode 'MoveToStartOfLineContent',
      },
      { key = 'b', mods = 'NONE', action = act.CopyMode 'MoveBackwardWord' },
      { key = 'b', mods = 'ALT', action = act.CopyMode 'MoveBackwardWord' },
      { key = 'b', mods = 'CTRL', action = act.CopyMode 'PageUp' },
      {
        key = 'c',
        mods = 'CTRL',
        action = act.Multiple {
          { CopyMode = 'ScrollToBottom' },
          { CopyMode = 'Close' },
        },
      },
      {
        key = 'd',
        mods = 'CTRL',
        action = act.CopyMode { MoveByPage = 0.5 },
      },
      {
        key = 'e',
        mods = 'NONE',
        action = act.CopyMode 'MoveForwardWordEnd',
      },
      {
        key = 'f',
        mods = 'NONE',
        action = act.CopyMode { JumpForward = { prev_char = false } },
      },
      { key = 'f', mods = 'ALT', action = act.CopyMode 'MoveForwardWord' },
      { key = 'f', mods = 'CTRL', action = act.CopyMode 'PageDown' },
      {
        key = 'g',
        mods = 'NONE',
        action = act.CopyMode 'MoveToScrollbackTop',
      },
      {
        key = 'g',
        mods = 'CTRL',
        action = act.Multiple {
          { CopyMode = 'ScrollToBottom' },
          { CopyMode = 'Close' },
        },
      },
      { key = 'h', mods = 'NONE', action = act.CopyMode 'MoveLeft' },
      { key = 'j', mods = 'NONE', action = act.CopyMode 'MoveDown' },
      { key = 'k', mods = 'NONE', action = act.CopyMode 'MoveUp' },
      { key = 'l', mods = 'NONE', action = act.CopyMode 'MoveRight' },
      {
        key = 'm',
        mods = 'ALT',
        action = act.CopyMode 'MoveToStartOfLineContent',
      },
      {
        key = 'o',
        mods = 'NONE',
        action = act.CopyMode 'MoveToSelectionOtherEnd',
      },
      {
        key = 'q',
        mods = 'NONE',
        action = act.Multiple {
          { CopyMode = 'ScrollToBottom' },
          { CopyMode = 'Close' },
        },
      },
      {
        key = 't',
        mods = 'NONE',
        action = act.CopyMode { JumpForward = { prev_char = true } },
      },
      {
        key = 'u',
        mods = 'CTRL',
        action = act.CopyMode { MoveByPage = -0.5 },
      },
      {
        key = 'v',
        mods = 'NONE',
        action = act.CopyMode { SetSelectionMode = 'Cell' },
      },
      {
        key = 'v',
        mods = 'CTRL',
        action = act.CopyMode { SetSelectionMode = 'Block' },
      },
      { key = 'w', mods = 'NONE', action = act.CopyMode 'MoveForwardWord' },
      {
        key = 'y',
        mods = 'NONE',
        action = act.Multiple {
          { CopyTo = 'ClipboardAndPrimarySelection' },
          { CopyMode = 'ScrollToBottom' },
          { CopyMode = 'Close' },
        },
      },
      { key = 'PageUp', mods = 'NONE', action = act.CopyMode 'PageUp' },
      { key = 'PageDown', mods = 'NONE', action = act.CopyMode 'PageDown' },
      {
        key = 'End',
        mods = 'NONE',
        action = act.CopyMode 'MoveToEndOfLineContent',
      },
      {
        key = 'Home',
        mods = 'NONE',
        action = act.CopyMode 'MoveToStartOfLine',
      },
      { key = 'LeftArrow', mods = 'NONE', action = act.CopyMode 'MoveLeft' },
      {
        key = 'LeftArrow',
        mods = 'ALT',
        action = act.CopyMode 'MoveBackwardWord',
      },
      {
        key = 'RightArrow',
        mods = 'NONE',
        action = act.CopyMode 'MoveRight',
      },
      {
        key = 'RightArrow',
        mods = 'ALT',
        action = act.CopyMode 'MoveForwardWord',
      },
      { key = 'UpArrow', mods = 'NONE', action = act.CopyMode 'MoveUp' },
      { key = 'DownArrow', mods = 'NONE', action = act.CopyMode 'MoveDown' },
    },
  },
}