wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-08-18 02:30:57 +03:00
Code Issues Projects Releases Wiki Activity

docs: shift from return {} style to config.something style

Browse Source 
Nudge new users towards using this style:

```lua
local config = {}
config.color_scheme = 'Batman'
return config
```

and surface how to write lua modules closer to the main section
on config files. In that lua modules section, nudge towards using
a convention similar to that of the plugin spec described in
this commit: e4ae8a844d
This commit is contained in:
Wez Furlong 2023-03-19 18:26:21 -07:00
parent 060d0f1ed4
commit 0f8146b212
No known key found for this signature in database
GPG Key ID: 7A7F66A31EC9B387
138 changed files with 5922 additions and 6317 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ci/generate-docs.py
View File

@ -307,9 +307,7 @@ function load_scheme_player(ident) {{
idx.write(
f"""
```lua
return {{
color_scheme = "{title}",
}}
config.color_scheme = "{title}"
```
"""

416
docs/config/appearance.md
View File

@ -9,9 +9,12 @@ WezTerm ships with over 700 color schemes available from
You can select a color scheme with a line like this:
```lua
return {
color_scheme = 'Batman',
}
local wezterm = require 'wezterm'
local config = {}
config.color_scheme = 'Batman'
return config
```
You can find a list of available color schemes and screenshots
@ -49,84 +52,87 @@ you can use `#RRGGBB` to specify a color code using the
usual hex notation; eg: `#000000` is equivalent to `black`:
```lua
return {
colors = {
-- The default text color
foreground = 'silver',
-- The default background color
background = 'black',
local wezterm = require 'wezterm'
local config = {}
-- Overrides the cell background color when the current cell is occupied by the
-- cursor and the cursor style is set to Block
cursor_bg = '#52ad70',
-- Overrides the text color when the current cell is occupied by the cursor
cursor_fg = 'black',
-- Specifies the border color of the cursor when the cursor style is set to Block,
-- or the color of the vertical or horizontal bar when the cursor style is set to
-- Bar or Underline.
cursor_border = '#52ad70',
config.colors = {
-- The default text color
foreground = 'silver',
-- The default background color
background = 'black',
-- the foreground color of selected text
selection_fg = 'black',
-- the background color of selected text
selection_bg = '#fffacd',
-- Overrides the cell background color when the current cell is occupied by the
-- cursor and the cursor style is set to Block
cursor_bg = '#52ad70',
-- Overrides the text color when the current cell is occupied by the cursor
cursor_fg = 'black',
-- Specifies the border color of the cursor when the cursor style is set to Block,
-- or the color of the vertical or horizontal bar when the cursor style is set to
-- Bar or Underline.
cursor_border = '#52ad70',
-- The color of the scrollbar "thumb"; the portion that represents the current viewport
scrollbar_thumb = '#222222',
-- the foreground color of selected text
selection_fg = 'black',
-- the background color of selected text
selection_bg = '#fffacd',
-- The color of the split lines between panes
split = '#444444',
-- The color of the scrollbar "thumb"; the portion that represents the current viewport
scrollbar_thumb = '#222222',
ansi = {
'black',
'maroon',
'green',
'olive',
'navy',
'purple',
'teal',
'silver',
},
brights = {
'grey',
'red',
'lime',
'yellow',
'blue',
'fuchsia',
'aqua',
'white',
},
-- The color of the split lines between panes
split = '#444444',
-- Arbitrary colors of the palette in the range from 16 to 255
indexed = { [136] = '#af8700' },
-- Since: 20220319-142410-0fcdea07
-- When the IME, a dead key or a leader key are being processed and are effectively
-- holding input pending the result of input composition, change the cursor
-- to this color to give a visual cue about the compose state.
compose_cursor = 'orange',
-- Colors for copy_mode and quick_select
-- available since: 20220807-113146-c2fee766
-- In copy_mode, the color of the active text is:
-- 1. copy_mode_active_highlight_* if additional text was selected using the mouse
-- 2. selection_* otherwise
copy_mode_active_highlight_bg = { Color = '#000000' },
-- use `AnsiColor` to specify one of the ansi color palette values
-- (index 0-15) using one of the names "Black", "Maroon", "Green",
-- "Olive", "Navy", "Purple", "Teal", "Silver", "Grey", "Red", "Lime",
-- "Yellow", "Blue", "Fuchsia", "Aqua" or "White".
copy_mode_active_highlight_fg = { AnsiColor = 'Black' },
copy_mode_inactive_highlight_bg = { Color = '#52ad70' },
copy_mode_inactive_highlight_fg = { AnsiColor = 'White' },
quick_select_label_bg = { Color = 'peru' },
quick_select_label_fg = { Color = '#ffffff' },
quick_select_match_bg = { AnsiColor = 'Navy' },
quick_select_match_fg = { Color = '#ffffff' },
ansi = {
'black',
'maroon',
'green',
'olive',
'navy',
'purple',
'teal',
'silver',
},
brights = {
'grey',
'red',
'lime',
'yellow',
'blue',
'fuchsia',
'aqua',
'white',
},
-- Arbitrary colors of the palette in the range from 16 to 255
indexed = { [136] = '#af8700' },
-- Since: 20220319-142410-0fcdea07
-- When the IME, a dead key or a leader key are being processed and are effectively
-- holding input pending the result of input composition, change the cursor
-- to this color to give a visual cue about the compose state.
compose_cursor = 'orange',
-- Colors for copy_mode and quick_select
-- available since: 20220807-113146-c2fee766
-- In copy_mode, the color of the active text is:
-- 1. copy_mode_active_highlight_* if additional text was selected using the mouse
-- 2. selection_* otherwise
copy_mode_active_highlight_bg = { Color = '#000000' },
-- use `AnsiColor` to specify one of the ansi color palette values
-- (index 0-15) using one of the names "Black", "Maroon", "Green",
-- "Olive", "Navy", "Purple", "Teal", "Silver", "Grey", "Red", "Lime",
-- "Yellow", "Blue", "Fuchsia", "Aqua" or "White".
copy_mode_active_highlight_fg = { AnsiColor = 'Black' },
copy_mode_inactive_highlight_bg = { Color = '#52ad70' },
copy_mode_inactive_highlight_fg = { AnsiColor = 'White' },
quick_select_label_bg = { Color = 'peru' },
quick_select_label_fg = { Color = '#ffffff' },
quick_select_match_bg = { AnsiColor = 'Navy' },
quick_select_match_fg = { Color = '#ffffff' },
}
return config
```
*Since: 20220101-133340-7edc5b5a*
@ -134,16 +140,14 @@ return {
You may specify colors in the HSL color space, if you prefer that over RGB, by using:
```lua
return {
colors = {
-- the first number is the hue measured in degrees with a range
-- of 0-360.
-- The second number is the saturation measured in percentage with
-- a range of 0-100.
-- The third number is the lightness measured in percentage with
-- a range of 0-100.
foreground = 'hsl:235 100 50',
},
config.colors = {
-- the first number is the hue measured in degrees with a range
-- of 0-360.
-- The second number is the saturation measured in percentage with
-- a range of 0-100.
-- The third number is the lightness measured in percentage with
-- a range of 0-100.
foreground = 'hsl:235 100 50',
}
```
@ -174,16 +178,14 @@ The alpha value is ignored except when used with `selection_fg` and
`selection_bg`:
```lua
return {
colors = {
-- Make the selection text color fully transparent.
-- When fully transparent, the current text color will be used.
selection_fg = 'none',
-- Set the selection background color with alpha.
-- When selection_bg is transparent, it will be alpha blended over
-- the current cell background color, rather than replace it
selection_bg = 'rgba(50% 50% 50% 50%)',
},
config.colors = {
-- Make the selection text color fully transparent.
-- When fully transparent, the current text color will be used.
selection_fg = 'none',
-- Set the selection background color with alpha.
-- When selection_bg is transparent, it will be alpha blended over
-- the current cell background color, rather than replace it
selection_bg = 'rgba(50% 50% 50% 50%)',
}
```
@ -201,16 +203,14 @@ All of the settings available from the `colors` section are available
to use in the `color_schemes` sections.
```lua
return {
color_scheme = 'Red Scheme',
config.color_scheme = 'Red Scheme'
color_schemes = {
['Red Scheme'] = {
background = 'red',
},
['Blue Scheme'] = {
background = 'blue',
},
config.color_schemes = {
['Red Scheme'] = {
background = 'red',
},
['Blue Scheme'] = {
background = 'blue',
},
}
```
@ -236,9 +236,7 @@ will need to instruct wezterm where to look for your scheme files; the
`color_scheme_dirs` setting specifies a list of directories to be searched:
```lua
return {
color_scheme_dirs = { '/some/path/to/my/color/schemes' },
}
config.color_scheme_dirs = { '/some/path/to/my/color/schemes' }
```
Color scheme names that are defined in files in your `color_scheme_dirs` list
@ -253,14 +251,14 @@ of the color scheme repo contains shell scripts that can change the color
scheme immediately on the fly. This can be used in your own scripts to alter
the terminal appearance programmatically:
```bash
```console
$ git clone https://github.com/mbadolato/iTerm2-Color-Schemes.git
$ cd iTerm2-Color-Schemes/dynamic-colors
$ for scheme in *.sh ; do ; echo $scheme ; \
bash "$scheme" ; ../tools/screenshotTable.sh; sleep 0.5; done
```
<video width="80%" controls src="../../screenshots/wezterm-dynamic-colors.mp4" loop></video>
<video width="80%" controls src="../screenshots/wezterm-dynamic-colors.mp4" loop></video>
### Tab Bar Appearance & Colors
@ -285,36 +283,32 @@ details.
The following options affect the fancy tab bar:
```lua
local wezterm = require 'wezterm'
config.window_frame = {
-- The font used in the tab bar.
-- Roboto Bold is the default; this font is bundled
-- with wezterm.
-- Whatever font is selected here, it will have the
-- main font setting appended to it to pick up any
-- fallback fonts you may have used there.
font = wezterm.font { family = 'Roboto', weight = 'Bold' },
return {
window_frame = {
-- The font used in the tab bar.
-- Roboto Bold is the default; this font is bundled
-- with wezterm.
-- Whatever font is selected here, it will have the
-- main font setting appended to it to pick up any
-- fallback fonts you may have used there.
font = wezterm.font { family = 'Roboto', weight = 'Bold' },
-- The size of the font in the tab bar.
-- Default to 10. on Windows but 12.0 on other systems
font_size = 12.0,
-- The size of the font in the tab bar.
-- Default to 10. on Windows but 12.0 on other systems
font_size = 12.0,
-- The overall background color of the tab bar when
-- the window is focused
active_titlebar_bg = '#333333',
-- The overall background color of the tab bar when
-- the window is focused
active_titlebar_bg = '#333333',
-- The overall background color of the tab bar when
-- the window is not focused
inactive_titlebar_bg = '#333333',
}
-- The overall background color of the tab bar when
-- the window is not focused
inactive_titlebar_bg = '#333333',
},
colors = {
tab_bar = {
-- The color of the inactive tab bar edge/divider
inactive_tab_edge = '#575757',
},
window.colors = {
tab_bar = {
-- The color of the inactive tab bar edge/divider
inactive_tab_edge = '#575757',
},
}
```
@ -327,78 +321,76 @@ to the items displayed in the tab bar.
The following options control the appearance of the tab bar:
```lua
return {
colors = {
tab_bar = {
-- The color of the strip that goes along the top of the window
-- (does not apply when fancy tab bar is in use)
background = '#0b0022',
config.colors = {
tab_bar = {
-- The color of the strip that goes along the top of the window
-- (does not apply when fancy tab bar is in use)
background = '#0b0022',
-- The active tab is the one that has focus in the window
active_tab = {
-- The color of the background area for the tab
bg_color = '#2b2042',
-- The color of the text for the tab
fg_color = '#c0c0c0',
-- The active tab is the one that has focus in the window
active_tab = {
-- The color of the background area for the tab
bg_color = '#2b2042',
-- The color of the text for the tab
fg_color = '#c0c0c0',
-- Specify whether you want "Half", "Normal" or "Bold" intensity for the
-- label shown for this tab.
-- The default is "Normal"
intensity = 'Normal',
-- Specify whether you want "Half", "Normal" or "Bold" intensity for the
-- label shown for this tab.
-- The default is "Normal"
intensity = 'Normal',
-- Specify whether you want "None", "Single" or "Double" underline for
-- label shown for this tab.
-- The default is "None"
underline = 'None',
-- Specify whether you want "None", "Single" or "Double" underline for
-- label shown for this tab.
-- The default is "None"
underline = 'None',
-- Specify whether you want the text to be italic (true) or not (false)
-- for this tab. The default is false.
italic = false,
-- Specify whether you want the text to be italic (true) or not (false)
-- for this tab. The default is false.
italic = false,
-- Specify whether you want the text to be rendered with strikethrough (true)
-- or not for this tab. The default is false.
strikethrough = false,
},
-- Specify whether you want the text to be rendered with strikethrough (true)
-- or not for this tab. The default is false.
strikethrough = false,
},
-- Inactive tabs are the tabs that do not have focus
inactive_tab = {
bg_color = '#1b1032',
fg_color = '#808080',
-- Inactive tabs are the tabs that do not have focus
inactive_tab = {
bg_color = '#1b1032',
fg_color = '#808080',
-- The same options that were listed under the `active_tab` section above
-- can also be used for `inactive_tab`.
},
-- The same options that were listed under the `active_tab` section above
-- can also be used for `inactive_tab`.
},
-- You can configure some alternate styling when the mouse pointer
-- moves over inactive tabs
inactive_tab_hover = {
bg_color = '#3b3052',
fg_color = '#909090',
italic = true,
-- You can configure some alternate styling when the mouse pointer
-- moves over inactive tabs
inactive_tab_hover = {
bg_color = '#3b3052',
fg_color = '#909090',
italic = true,
-- The same options that were listed under the `active_tab` section above
-- can also be used for `inactive_tab_hover`.
},
-- The same options that were listed under the `active_tab` section above
-- can also be used for `inactive_tab_hover`.
},
-- The new tab button that let you create new tabs
new_tab = {
bg_color = '#1b1032',
fg_color = '#808080',
-- The new tab button that let you create new tabs
new_tab = {
bg_color = '#1b1032',
fg_color = '#808080',
-- The same options that were listed under the `active_tab` section above
-- can also be used for `new_tab`.
},
-- The same options that were listed under the `active_tab` section above
-- can also be used for `new_tab`.
},
-- You can configure some alternate styling when the mouse pointer
-- moves over the new tab button
new_tab_hover = {
bg_color = '#3b3052',
fg_color = '#909090',
italic = true,
-- You can configure some alternate styling when the mouse pointer
-- moves over the new tab button
new_tab_hover = {
bg_color = '#3b3052',
fg_color = '#909090',
italic = true,
-- The same options that were listed under the `active_tab` section above
-- can also be used for `new_tab_hover`.
},
-- The same options that were listed under the `active_tab` section above
-- can also be used for `new_tab_hover`.
},
},
}
@ -424,11 +416,9 @@ In this example, inactive panes will be slightly de-saturated and dimmed;
this is the default configuration:
```lua
return {
inactive_pane_hsb = {
saturation = 0.9,
brightness = 0.8,
},
config.inactive_pane_hsb = {
saturation = 0.9,
brightness = 0.8,
}
```
@ -458,9 +448,7 @@ reduce it by half, and 2.0 will double the value.
You can attach an image to the background of the wezterm window:
```lua
return {
window_background_image = '/path/to/wallpaper.jpg',
}
config.window_background_image = '/path/to/wallpaper.jpg'
```
If the path is a relative path then it will be expanded relative
@ -478,20 +466,18 @@ You can optionally transform the background image by specifying
a hue, saturation, brightness multiplier:
```lua
return {
window_background_image = '/path/to/wallpaper.jpg',
config.window_background_image = '/path/to/wallpaper.jpg'
window_background_image_hsb = {
-- Darken the background image by reducing it to 1/3rd
brightness = 0.3,
config.window_background_image_hsb = {
-- Darken the background image by reducing it to 1/3rd
brightness = 0.3,
-- You can adjust the hue by scaling its value.
-- a multiplier of 1.0 leaves the value unchanged.
hue = 1.0,
-- You can adjust the hue by scaling its value.
-- a multiplier of 1.0 leaves the value unchanged.
hue = 1.0,
-- You can adjust the saturation also.
saturation = 1.0,
},
-- You can adjust the saturation also.
saturation = 1.0,
}
```
@ -533,9 +519,7 @@ Setting this to a value other than the default `1.0` may impact render
performance.
```lua
return {
window_background_opacity = 1.0,
}
config.window_background_opacity = 1.0
```
## Text Background Opacity
@ -556,8 +540,6 @@ The range of values permitted are `0.0` (completely translucent)
through to `1.0` (completely opaque).
```lua
return {
text_background_opacity = 0.3,
}
config.text_background_opacity = 0.3
```

4
docs/config/default-keys.md
View File

@ -85,9 +85,7 @@ disable all of them with this configuration; if you chose to do this,
you must explicitly register every binding.
```lua
return {
disable_default_key_bindings = true,
}
config.disable_default_key_bindings = true
```
!!! tip

121
docs/config/files.md
View File

@ -1,3 +1,31 @@
## Quick Start
Create a file named `wezterm.lua` in your home directory, with the following
contents:
```lua
-- Pull in the wezterm API
local wezterm = require 'wezterm'
-- This table will hold the configuration.
local config = {}
-- In newer versions of wezterm, use the config_builder which will
-- help provide clearer error messages
if wezterm.config_builder then
config = wezterm.config_builder()
end
-- This is where you actually apply your config choices
-- For example, changing the color scheme:
config.color_scheme = 'AdventureTime'
-- and finally, return the configuration to wezterm
return config
```
## Configuration Files
`wezterm` will look for a [lua](https://www.lua.org/manual/5.3/manual.html)
@ -79,7 +107,8 @@ for more information and examples of how to use that functionality.
The `wezterm.lua` configuration file is a lua script which allows for a high
degree of flexibility. The script is expected to return a configuration
table, so a basic empty configuration file will look like this:
table, so a basic empty (and rather useless!) configuration file will look like
this:
```lua
return {}
@ -89,18 +118,23 @@ Throughout these docs you'll find configuration fragments that demonstrate
configuration and that look something like this:
```lua
return {
color_scheme = 'Batman',
}
local wezterm = require 'wezterm'
local config = {}
config.color_scheme = 'Batman'
return config
```
and perhaps another one like this:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font 'JetBrains Mono',
}
local config = {}
config.font = wezterm.font 'JetBrains Mono'
return config
```
If you wanted to use both of these in the same file, you would merge them together
@ -108,12 +142,77 @@ like this:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font 'JetBrains Mono',
color_scheme = 'Batman',
}
local config = {}
config.font = wezterm.font 'JetBrains Mono'
config.color_scheme = 'Batman'
return config
```
For the sake of brevity in these docs, individual snippets may be shown as
just the config assignments:
```lua
config.color_scheme = 'Batman'
```
## Making your own Lua Modules
If you'd like to break apart your configuration into multiple files, you'll
be interested in this information.
The Lua `package.path` is configured with the following paths in this order:
* On Windows: a `wezterm_modules` dir in the same directory as `wezterm.exe`. This is for thumb drive mode, and is not recommended to be used otherwise.
* `~/.config/wezterm`
* `~/.wezterm`
* A system specific set of paths which may (or may not!) find locally installed lua modules
That means that if you wanted to break your config up into a `helpers.lua` file
you would place it in `~/.config/wezterm/helpers.lua` with contents like this:
```lua
-- I am helpers.lua and I should live in ~/.config/wezterm/helpers.lua
local wezterm = require 'wezterm'
-- This is the module table that we will export
local module = {}
-- This function is private to this module and is not visible
-- outside.
local function private_helper()
wezterm.log_error 'hello!'
end
-- define a function in the module table.
-- Only functions defined in `module` will be exported to
-- code that imports this module.
-- The suggested convention for making modules that update
-- the config is for them to export an `apply_to_config`
-- function that accepts the config object, like this:
function module.apply_to_config(config)
private_helper()
config.color_scheme = 'Batman'
end
-- return our module table
return module
```
and then in your `wezterm.lua`
you would use it like this:
```lua
local helpers = require 'helpers'
local config = {}
helpers.apply_to_config(config)
return config
```
## Configuration Reference
Continue browsing this section of the docs for an overview of the commonly

39
docs/config/font-shaping.md
View File

@ -20,9 +20,7 @@ If you want to disable ligatures in most fonts, then you may want to
use a setting like this:
```lua
return {
harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
}
config.harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' }
```
Some fonts make available extended options via stylistic sets.
@ -33,11 +31,9 @@ it lists available stylistic sets here:
and you can set them in wezterm:
```lua
return {
-- Use this for a zero with a dot rather than a line through it
-- when using the Fira Code font
harfbuzz_features = { 'zero' },
}
-- Use this for a zero with a dot rather than a line through it
-- when using the Fira Code font
config.harfbuzz_features = { 'zero' }
```
*Since: 20220101-133340-7edc5b5a*
@ -46,12 +42,9 @@ You can specify `harfbuzz_features` on a per-font basis, rather than
globally for all fonts:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font {
family = 'JetBrains Mono',
harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
},
config.font = wezterm.font {
family = 'JetBrains Mono',
harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
}
```
@ -59,18 +52,14 @@ and this example disables ligatures for JetBrains Mono,
but keeps the default for the other fonts in the fallback:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font_with_fallback {
{
family = 'JetBrains Mono',
weight = 'Medium',
harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
},
{ family = 'Terminus', weight = 'Bold' },
'Noto Color Emoji',
config.font = wezterm.font_with_fallback {
{
family = 'JetBrains Mono',
weight = 'Medium',
harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
},
{ family = 'Terminus', weight = 'Bold' },
'Noto Color Emoji',
}
```

22
docs/config/fonts.md
View File

@ -9,14 +9,11 @@ If you wish to use a different font face, then you can use
the [wezterm.font](lua/wezterm/font.md) function to specify it:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font 'Fira Code',
-- You can specify some parameters to influence the font selection;
-- for example, this selects a Bold, Italic font variant.
font = wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true }),
}
config.font = wezterm.font 'Fira Code'
-- You can specify some parameters to influence the font selection;
-- for example, this selects a Bold, Italic font variant.
config.font =
wezterm.font('JetBrains Mono', { weight = 'Bold', italic = true })
```
#### Fallback
@ -35,12 +32,9 @@ monospace font, but it doesn't have glyphs for the asian script that you
sometimes work with:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font_with_fallback {
'Fira Code',
'DengXian',
},
config.font = wezterm.font_with_fallback {
'Fira Code',
'DengXian',
}
```

127
docs/config/key-tables.md
View File

@ -18,6 +18,7 @@ modes, using `r` for resize and `a` for activation:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
-- Show which key table is active in the status area
wezterm.on('update-right-status', function(window, pane)
@ -28,75 +29,75 @@ wezterm.on('update-right-status', function(window, pane)
window:set_right_status(name or '')
end)
return {
leader = { key = 'Space', mods = 'CTRL|SHIFT' },
keys = {
-- CTRL+SHIFT+Space, followed by 'r' will put us in resize-pane
-- mode until we cancel that mode.
{
key = 'r',
mods = 'LEADER',
action = act.ActivateKeyTable {
name = 'resize_pane',
one_shot = false,
},
},
-- CTRL+SHIFT+Space, followed by 'a' will put us in activate-pane
-- mode until we press some other key or until 1 second (1000ms)
-- of time elapses
{
key = 'a',
mods = 'LEADER',
action = act.ActivateKeyTable {
name = 'activate_pane',
timeout_milliseconds = 1000,
},
config.leader = { key = 'Space', mods = 'CTRL|SHIFT' }
config.keys = {
-- CTRL+SHIFT+Space, followed by 'r' will put us in resize-pane
-- mode until we cancel that mode.
{
key = 'r',
mods = 'LEADER',
action = act.ActivateKeyTable {
name = 'resize_pane',
one_shot = false,
},
},
key_tables = {
-- Defines the keys that are active in our resize-pane mode.
-- Since we're likely to want to make multiple adjustments,
-- we made the activation one_shot=false. We therefore need
-- to define a key assignment for getting out of this mode.
-- 'resize_pane' here corresponds to the name="resize_pane" in
-- the key assignments above.
resize_pane = {
{ key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
{ key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },
{ key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
{ key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },
{ key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
{ key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },
{ key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
{ key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },
-- Cancel the mode by pressing escape
{ key = 'Escape', action = 'PopKeyTable' },
},
-- Defines the keys that are active in our activate-pane mode.
-- 'activate_pane' here corresponds to the name="activate_pane" in
-- the key assignments above.
activate_pane = {
{ key = 'LeftArrow', action = act.ActivatePaneDirection 'Left' },
{ key = 'h', action = act.ActivatePaneDirection 'Left' },
{ key = 'RightArrow', action = act.ActivatePaneDirection 'Right' },
{ key = 'l', action = act.ActivatePaneDirection 'Right' },
{ key = 'UpArrow', action = act.ActivatePaneDirection 'Up' },
{ key = 'k', action = act.ActivatePaneDirection 'Up' },
{ key = 'DownArrow', action = act.ActivatePaneDirection 'Down' },
{ key = 'j', action = act.ActivatePaneDirection 'Down' },
-- CTRL+SHIFT+Space, followed by 'a' will put us in activate-pane
-- mode until we press some other key or until 1 second (1000ms)
-- of time elapses
{
key = 'a',
mods = 'LEADER',
action = act.ActivateKeyTable {
name = 'activate_pane',
timeout_milliseconds = 1000,
},
},
}
config.key_tables = {
-- Defines the keys that are active in our resize-pane mode.
-- Since we're likely to want to make multiple adjustments,
-- we made the activation one_shot=false. We therefore need
-- to define a key assignment for getting out of this mode.
-- 'resize_pane' here corresponds to the name="resize_pane" in
-- the key assignments above.
resize_pane = {
{ key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
{ key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },
{ key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
{ key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },
{ key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
{ key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },
{ key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
{ key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },
-- Cancel the mode by pressing escape
{ key = 'Escape', action = 'PopKeyTable' },
},
-- Defines the keys that are active in our activate-pane mode.
-- 'activate_pane' here corresponds to the name="activate_pane" in
-- the key assignments above.
activate_pane = {
{ key = 'LeftArrow', action = act.ActivatePaneDirection 'Left' },
{ key = 'h', action = act.ActivatePaneDirection 'Left' },
{ key = 'RightArrow', action = act.ActivatePaneDirection 'Right' },
{ key = 'l', action = act.ActivatePaneDirection 'Right' },
{ key = 'UpArrow', action = act.ActivatePaneDirection 'Up' },
{ key = 'k', action = act.ActivatePaneDirection 'Up' },
{ key = 'DownArrow', action = act.ActivatePaneDirection 'Down' },
{ key = 'j', action = act.ActivatePaneDirection 'Down' },
},
}
return config
```
### Key Table Activation Stack

10
docs/config/keyboard-concepts.md
View File

@ -109,10 +109,8 @@ with no composition effects, while the right `Option` key performs composition
You can control this behavior in your configuration:
```lua
return {
send_composed_key_when_left_alt_is_pressed = false,
send_composed_key_when_right_alt_is_pressed = true,
}
config.send_composed_key_when_left_alt_is_pressed = false
config.send_composed_key_when_right_alt_is_pressed = true
```
*since: 20210203-095643-70a364eb*
@ -153,9 +151,7 @@ You can tell WezTerm to disable dead keys by setting this in your configuration
file:
```lua
return {
use_dead_keys = false,
}
config.use_dead_keys = false
```
Note that for X11 systems with `use_ime=true`, depending on the configured IME,

78
docs/config/keys.md
View File

@ -5,17 +5,13 @@ The default key table assignments can be overridden or extended using the
disable a default assignment like this:
```lua
local wezterm = require 'wezterm'
return {
keys = {
-- Turn off the default CMD-m Hide action, allowing CMD-m to
-- be potentially recognized and handled by the tab
{
key = 'm',
mods = 'CMD',
action = wezterm.action.DisableDefaultAssignment,
},
config.keys = {
-- Turn off the default CMD-m Hide action, allowing CMD-m to
-- be potentially recognized and handled by the tab
{
key = 'm',
mods = 'CMD',
action = wezterm.action.DisableDefaultAssignment,
},
}
```
@ -142,23 +138,19 @@ milliseconds). While `LEADER` is active, the `|` key (with no other modifiers)
will trigger the current pane to be split.
```lua
local wezterm = require 'wezterm'
return {
-- timeout_milliseconds defaults to 1000 and can be omitted
leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 },
keys = {
{
key = '|',
mods = 'LEADER|SHIFT',
action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
},
-- Send "CTRL-A" to the terminal when pressing CTRL-A, CTRL-A
{
key = 'a',
mods = 'LEADER|CTRL',
action = wezterm.action.SendString '\x01',
},
-- timeout_milliseconds defaults to 1000 and can be omitted
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }
config.keys = {
{
key = '|',
mods = 'LEADER|SHIFT',
action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
},
-- Send "CTRL-A" to the terminal when pressing CTRL-A, CTRL-A
{
key = 'a',
mods = 'LEADER|CTRL',
action = wezterm.action.SendString '\x01',
},
}
```
@ -174,23 +166,19 @@ uses `CapsLock` as a `LEADER` without it affecting the shift / capital state as
long as you have `setxkbmap -option caps:none` configured.
```lua
local wezterm = require 'wezterm'
return {
-- timeout_milliseconds defaults to 1000 and can be omitted
-- for this example use `setxkbmap -option caps:none` in your terminal.
leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 },
keys = {
{
key = '|',
mods = 'LEADER|SHIFT',
action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
},
{
key = '-',
mods = 'LEADER',
action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
},
-- timeout_milliseconds defaults to 1000 and can be omitted
-- for this example use `setxkbmap -option caps:none` in your terminal.
config.leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 }
config.keys = {
{
key = '|',
mods = 'LEADER|SHIFT',
action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
},
{
key = '-',
mods = 'LEADER',
action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
},
}
```

65
docs/config/launch.md
View File

@ -38,10 +38,8 @@ the argument array; the array allows specifying the program and arguments
portably:
```lua
return {
-- Spawn a fish shell in login mode
default_prog = { '/usr/local/bin/fish', '-l' },
}
-- Spawn a fish shell in login mode
config.default_prog = { '/usr/local/bin/fish', '-l' }
```
## Launching a different program as a one off via the CLI
@ -64,9 +62,7 @@ directory you can do so via the config, CLI, and when using
* Setting the [`default_cwd`](lua/config/default_cwd.md) via the config:
```lua
return {
default_cwd = "/some/path",
}
config.default_cwd = "/some/path"
```
* One off program in a specific working directory via the CLI:
@ -108,13 +104,11 @@ The behavior is to take the environment of the `wezterm` process
and then set the specified variables for the spawned process.
```lua
return {
set_environment_variables = {
-- This changes the default prompt for cmd.exe to report the
-- current directory using OSC 7, show the current time and
-- the current directory colored in the prompt.
prompt = '$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m ',
},
config.set_environment_variables = {
-- This changes the default prompt for cmd.exe to report the
-- current directory using OSC 7, show the current time and
-- the current directory colored in the prompt.
prompt = '$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m ',
}
```
@ -140,30 +134,28 @@ Each entry in `launch_menu` is an instance of a
[SpawnCommand](lua/SpawnCommand.md) object.
```lua
return {
launch_menu = {
{
args = { 'top' },
},
{
-- Optional label to show in the launcher. If omitted, a label
-- is derived from the `args`
label = 'Bash',
-- The argument array to spawn. If omitted the default program
-- will be used as described in the documentation above
args = { 'bash', '-l' },
config.launch_menu = {
{
args = { 'top' },
},
{
-- Optional label to show in the launcher. If omitted, a label
-- is derived from the `args`
label = 'Bash',
-- The argument array to spawn. If omitted the default program
-- will be used as described in the documentation above
args = { 'bash', '-l' },
-- You can specify an alternative current working directory;
-- if you don't specify one then a default based on the OSC 7
-- escape sequence will be used (see the Shell Integration
-- docs), falling back to the home directory.
-- cwd = "/some/path"
-- You can specify an alternative current working directory;
-- if you don't specify one then a default based on the OSC 7
-- escape sequence will be used (see the Shell Integration
-- docs), falling back to the home directory.
-- cwd = "/some/path"
-- You can override environment variables just for this command
-- by setting this here. It has the same semantics as the main
-- set_environment_variables configuration option described above
-- set_environment_variables = { FOO = "bar" },
},
-- You can override environment variables just for this command
-- by setting this here. It has the same semantics as the main
-- set_environment_variables configuration option described above
-- set_environment_variables = { FOO = "bar" },
},
}
```
@ -175,7 +167,6 @@ menu when running on Windows:
```lua
local wezterm = require 'wezterm'
local launch_menu = {}
if wezterm.target_triple == 'x86_64-pc-windows-msvc' then

105
docs/config/lua/ExecDomain.md
View File

@ -78,6 +78,7 @@ that affect the styling of the text. You may wish to use
```lua
local wezterm = require 'wezterm'
local config = {}
-- Equivalent to POSIX basename(3)
-- Given "/foo/bar" returns "bar"
@ -86,61 +87,61 @@ local function basename(s)
return string.gsub(s, '(.*[/\\])(.*)', '%2')
end
return {
exec_domains = {
-- Defines a domain called "scoped" that will run the requested
-- command inside its own individual systemd scope.
-- This defines a strong boundary for resource control and can
-- help to avoid OOMs in one pane causing other panes to be
-- killed.
wezterm.exec_domain('scoped', function(cmd)
-- The "cmd" parameter is a SpawnCommand object.
-- You can log it to see what's inside:
wezterm.log_info(cmd)
config.exec_domains = {
-- Defines a domain called "scoped" that will run the requested
-- command inside its own individual systemd scope.
-- This defines a strong boundary for resource control and can
-- help to avoid OOMs in one pane causing other panes to be
-- killed.
wezterm.exec_domain('scoped', function(cmd)
-- The "cmd" parameter is a SpawnCommand object.
-- You can log it to see what's inside:
wezterm.log_info(cmd)
-- Synthesize a human understandable scope name that is
-- (reasonably) unique. WEZTERM_PANE is the pane id that
-- will be used for the newly spawned pane.
-- WEZTERM_UNIX_SOCKET is associated with the wezterm
-- process id.
local env = cmd.set_environment_variables
local ident = 'wezterm-pane-'
.. env.WEZTERM_PANE
.. '-on-'
.. basename(env.WEZTERM_UNIX_SOCKET)
-- Synthesize a human understandable scope name that is
-- (reasonably) unique. WEZTERM_PANE is the pane id that
-- will be used for the newly spawned pane.
-- WEZTERM_UNIX_SOCKET is associated with the wezterm
-- process id.
local env = cmd.set_environment_variables
local ident = 'wezterm-pane-'
.. env.WEZTERM_PANE
.. '-on-'
.. basename(env.WEZTERM_UNIX_SOCKET)
-- Generate a new argument array that will launch a
-- program via systemd-run
local wrapped = {
'/usr/bin/systemd-run',
'--user',
'--scope',
'--description=Shell started by wezterm',
'--same-dir',
'--collect',
'--unit=' .. ident,
}
-- Generate a new argument array that will launch a
-- program via systemd-run
local wrapped = {
'/usr/bin/systemd-run',
'--user',
'--scope',
'--description=Shell started by wezterm',
'--same-dir',
'--collect',
'--unit=' .. ident,
}
-- Append the requested command
-- Note that cmd.args may be nil; that indicates that the
-- default program should be used. Here we're using the
-- shell defined by the SHELL environment variable.
for _, arg in ipairs(cmd.args or { os.getenv 'SHELL' }) do
table.insert(wrapped, arg)
end
-- Append the requested command
-- Note that cmd.args may be nil; that indicates that the
-- default program should be used. Here we're using the
-- shell defined by the SHELL environment variable.
for _, arg in ipairs(cmd.args or { os.getenv 'SHELL' }) do
table.insert(wrapped, arg)
end
-- replace the requested argument array with our new one
cmd.args = wrapped
-- replace the requested argument array with our new one
cmd.args = wrapped
-- and return the SpawnCommand that we want to execute
return cmd
end),
},
-- Making the domain the default means that every pane/tab/window
-- spawned by wezterm will have its own scope
default_domain = 'scoped',
-- and return the SpawnCommand that we want to execute
return cmd
end),
}
-- Making the domain the default means that every pane/tab/window
-- spawned by wezterm will have its own scope
config.default_domain = 'scoped'
return config
```
## Example: docker domains
@ -150,6 +151,7 @@ gist of it is:
```lua
local wezterm = require 'wezterm'
local config = {}
function docker_list()
-- Use wezterm.run_child_process to run
@ -200,9 +202,8 @@ for id, name in pairs(docker_list()) do
)
end
return {
exec_domains = exec_domains,
}
config.exec_domains = exec_domains
return config
```
With something like the config above, each time the config is reloaded, the

6
docs/config/lua/PaneInformation.md
View File

@ -73,6 +73,7 @@ tab in the tab bar when there is unseen output.
```lua
local wezterm = require 'wezterm'
local config = {}
wezterm.on(
'format-tab-title',
@ -100,7 +101,7 @@ wezterm.on(
end
)
return {}
return config
```
*Since: 20220624-141144-bd1b7c5d*
@ -111,6 +112,7 @@ This example shows the domain name of the active pane appended to the tab title:
```lua
local wezterm = require 'wezterm'
local config = {}
wezterm.on('format-tab-title', function(tab)
local pane = tab.active_pane
@ -121,6 +123,6 @@ wezterm.on('format-tab-title', function(tab)
return title
end)
return {}
return config
```

112
docs/config/lua/SshDomain.md
View File

@ -6,36 +6,34 @@ The `SshDomain` struct specifies information about an individual
It is a lua object with the following fields:
```lua
return {
ssh_domains = {
{
-- The name of this specific domain. Must be unique amongst
-- all types of domain in the configuration file.
name = 'my.server',
config.ssh_domains = {
{
-- The name of this specific domain. Must be unique amongst
-- all types of domain in the configuration file.
name = 'my.server',
-- identifies the host:port pair of the remote server
-- Can be a DNS name or an IP address with an optional
-- ":port" on the end.
remote_address = '192.168.1.1',
-- identifies the host:port pair of the remote server
-- Can be a DNS name or an IP address with an optional
-- ":port" on the end.
remote_address = '192.168.1.1',
-- Whether agent auth should be disabled.
-- Set to true to disable it.
-- no_agent_auth = false,
-- Whether agent auth should be disabled.
-- Set to true to disable it.
-- no_agent_auth = false,
-- The username to use for authenticating with the remote host
username = 'yourusername',
-- The username to use for authenticating with the remote host
username = 'yourusername',
-- If true, connect to this domain automatically at startup
-- connect_automatically = true,
-- If true, connect to this domain automatically at startup
-- connect_automatically = true,
-- Specify an alternative read timeout
-- timeout = 60,
-- Specify an alternative read timeout
-- timeout = 60,
-- The path to the wezterm binary on the remote host.
-- Primarily useful if it isn't installed in the $PATH
-- that is configure for ssh.
-- remote_wezterm_path = "/home/yourusername/bin/wezterm"
},
-- The path to the wezterm binary on the remote host.
-- Primarily useful if it isn't installed in the $PATH
-- that is configure for ssh.
-- remote_wezterm_path = "/home/yourusername/bin/wezterm"
},
}
```
@ -45,14 +43,12 @@ return {
You may now specify a table with ssh config overrides:
```lua
return {
ssh_domains = {
{
name = 'my.server',
remote_address = '192.168.1.1',
ssh_option = {
identityfile = '/path/to/id_rsa.pub',
},
config.ssh_domains = {
{
name = 'my.server',
remote_address = '192.168.1.1',
ssh_option = {
identityfile = '/path/to/id_rsa.pub',
},
},
}
@ -85,31 +81,29 @@ panes and tabs. The following values are recognized for `assume_shell`:
`env -c DIR ENV1=VAL1 ENV2=VAL2 $SHELL`.
```lua
return {
ssh_domains = {
{
name = 'my.server',
remote_address = '192.168.1.1',
multiplexing = 'None',
config.ssh_domains = {
{
name = 'my.server',
remote_address = '192.168.1.1',
multiplexing = 'None',
-- When multiplexing == "None", default_prog can be used
-- to specify the default program to run in new tabs/panes.
-- Due to the way that ssh works, you cannot specify default_cwd,
-- but you could instead change your default_prog to put you
-- in a specific directory.
default_prog = { 'fish' },
-- When multiplexing == "None", default_prog can be used
-- to specify the default program to run in new tabs/panes.
-- Due to the way that ssh works, you cannot specify default_cwd,
-- but you could instead change your default_prog to put you
-- in a specific directory.
default_prog = { 'fish' },
-- assume that we can use syntax like:
-- "env -C /some/where $SHELL"
-- using whatever the default command shell is on this
-- remote host, so that shell integration will respect
-- the current directory on the remote host.
assume_shell = 'Posix',
},
-- assume that we can use syntax like:
-- "env -C /some/where $SHELL"
-- using whatever the default command shell is on this
-- remote host, so that shell integration will respect
-- the current directory on the remote host.
assume_shell = 'Posix',
},
default_domain = 'my.server',
}
config.default_domain = 'my.server'
```
You may now specify the round-trip latency threshold for enabling predictive
@ -120,13 +114,11 @@ result of that prediction locally without waiting, hence hiding latency to the
user. This option only applies when `multiplexing = "WezTerm"`.
```lua
return {
ssh_domains = {
{
name = 'my.server',
remote_address = '192.168.1.1',
local_echo_threshold_ms = 10,
},
config.ssh_domains = {
{
name = 'my.server',
remote_address = '192.168.1.1',
local_echo_threshold_ms = 10,
},
}
```

108
docs/config/lua/TlsDomainClient.md
View File

@ -6,66 +6,64 @@ to a [TLS Domain](../../multiplexing.md#tls-domains).
It is a lua object with the following fields:
```lua
return {
tls_domains = {
{
-- The name of this specific domain. Must be unique amongst
-- all types of domain in the configuration file.
name = 'server.name',
config.tls_domains = {
{
-- The name of this specific domain. Must be unique amongst
-- all types of domain in the configuration file.
name = 'server.name',
-- If set, use ssh to connect, start the server, and obtain
-- a certificate.
-- The value is "user@host:port", just like "wezterm ssh" accepts.
bootstrap_via_ssh = 'server.hostname',
-- If set, use ssh to connect, start the server, and obtain
-- a certificate.
-- The value is "user@host:port", just like "wezterm ssh" accepts.
bootstrap_via_ssh = 'server.hostname',
-- identifies the host:port pair of the remote server.
remote_address = 'server.hostname:8080',
-- identifies the host:port pair of the remote server.
remote_address = 'server.hostname:8080',
-- the path to an x509 PEM encoded private key file.
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_private_key = "/some/path/key.pem",
-- the path to an x509 PEM encoded private key file.
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_private_key = "/some/path/key.pem",
-- the path to an x509 PEM encoded certificate file
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_cert = "/some/path/cert.pem",
-- the path to an x509 PEM encoded certificate file
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_cert = "/some/path/cert.pem",
-- the path to an x509 PEM encoded CA chain file
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_ca = "/some/path/ca.pem",
-- the path to an x509 PEM encoded CA chain file
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_ca = "/some/path/ca.pem",
-- A set of paths to load additional CA certificates.
-- Each entry can be either the path to a directory or to a PEM encoded
-- CA file. If an entry is a directory, then its contents will be
-- loaded as CA certs and added to the trust store.
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
-- A set of paths to load additional CA certificates.
-- Each entry can be either the path to a directory or to a PEM encoded
-- CA file. If an entry is a directory, then its contents will be
-- loaded as CA certs and added to the trust store.
-- Omit this if you are using `bootstrap_via_ssh`.
-- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
-- explicitly control whether the client checks that the certificate
-- presented by the server matches the hostname portion of
-- `remote_address`. The default is true. This option is made
-- available for troubleshooting purposes and should not be used outside
-- of a controlled environment as it weakens the security of the TLS
-- channel.
-- accept_invalid_hostnames = false,
-- explicitly control whether the client checks that the certificate
-- presented by the server matches the hostname portion of
-- `remote_address`. The default is true. This option is made
-- available for troubleshooting purposes and should not be used outside
-- of a controlled environment as it weakens the security of the TLS
-- channel.
-- accept_invalid_hostnames = false,
-- the hostname string that we expect to match against the common name
-- field in the certificate presented by the server. This defaults to
-- the hostname portion of the `remote_address` configuration and you
-- should not normally need to override this value.
-- expected_cn = "other.name",
-- the hostname string that we expect to match against the common name
-- field in the certificate presented by the server. This defaults to
-- the hostname portion of the `remote_address` configuration and you
-- should not normally need to override this value.
-- expected_cn = "other.name",
-- If true, connect to this domain automatically at startup
-- connect_automatically = false,
-- If true, connect to this domain automatically at startup
-- connect_automatically = false,
-- Specify an alternate read timeout
-- read_timeout = 60,
-- Specify an alternate read timeout
-- read_timeout = 60,
-- Specify an alternate write timeout
-- write_timeout = 60,
-- Specify an alternate write timeout
-- write_timeout = 60,
-- The path to the wezterm binary on the remote host
-- remote_wezterm_path = "/home/myname/bin/wezterm"
},
-- The path to the wezterm binary on the remote host
-- remote_wezterm_path = "/home/myname/bin/wezterm"
},
}
```
@ -80,14 +78,12 @@ result of that prediction locally without waiting, hence hiding latency to the
user. This option only applies when `multiplexing = "WezTerm"`.
```lua
return {
tls_domains = {
{
name = 'server,name',
bootstrap_via_ssh = 'server.hostname',
remote_address = 'server.hostname:8080',
local_echo_threshold_ms = 10,
},
config.tls_domains = {
{
name = 'server,name',
bootstrap_via_ssh = 'server.hostname',
remote_address = 'server.hostname:8080',
local_echo_threshold_ms = 10,
},
}
```

44
docs/config/lua/TlsDomainServer.md
View File

@ -6,33 +6,31 @@ the server side of a [TLS Domain](../../multiplexing.md#tls-domains).
It is a lua object with the following fields:
```lua
return {
tls_servers = {
{
-- The address:port combination on which the server will listen
-- for client connections
bind_address = 'server.hostname:8080',
config.tls_servers = {
{
-- The address:port combination on which the server will listen
-- for client connections
bind_address = 'server.hostname:8080',
-- the path to an x509 PEM encoded private key file.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_private_key = "/path/to/key.pem",
-- the path to an x509 PEM encoded private key file.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_private_key = "/path/to/key.pem",
-- the path to an x509 PEM encoded certificate file.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_cert = "/path/to/cert.pem",
-- the path to an x509 PEM encoded certificate file.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_cert = "/path/to/cert.pem",
-- the path to an x509 PEM encoded CA chain file.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_ca = "/path/to/chain.pem",
-- the path to an x509 PEM encoded CA chain file.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_ca = "/path/to/chain.pem",
-- A set of paths to load additional CA certificates.
-- Each entry can be either the path to a directory
-- or to a PEM encoded CA file. If an entry is a directory,
-- then its contents will be loaded as CA certs and added
-- to the trust store.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
},
-- A set of paths to load additional CA certificates.
-- Each entry can be either the path to a directory
-- or to a PEM encoded CA file. If an entry is a directory,
-- then its contents will be loaded as CA certs and added
-- to the trust store.
-- You can omit this if your tls_client is using bootstrap_via_ssh.
-- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
},
}
```

42
docs/config/lua/WslDomain.md
View File

@ -18,35 +18,33 @@ output from `wsl -l -v` and assigns that as the value of the
A `WslDomain` is a lua object with the following fields:
```lua
return {
wsl_domains = {
{
-- The name of this specific domain. Must be unique amonst all types
-- of domain in the configuration file.
name = 'WSL:Ubuntu-18.04',
config.wsl_domains = {
{
-- The name of this specific domain. Must be unique amonst all types
-- of domain in the configuration file.
name = 'WSL:Ubuntu-18.04',
-- The name of the distribution. This identifies the WSL distribution.
-- It must match a valid distribution from your `wsl -l -v` output in
-- order for the domain to be useful.
distribution = 'Ubuntu-18.04',
-- The name of the distribution. This identifies the WSL distribution.
-- It must match a valid distribution from your `wsl -l -v` output in
-- order for the domain to be useful.
distribution = 'Ubuntu-18.04',
-- The username to use when spawning commands in the distribution.
-- If omitted, the default user for that distribution will be used.
-- The username to use when spawning commands in the distribution.
-- If omitted, the default user for that distribution will be used.
-- username = "hunter",
-- username = "hunter",
-- The current working directory to use when spawning commands, if
-- the SpawnCommand doesn't otherwise specify the directory.
-- The current working directory to use when spawning commands, if
-- the SpawnCommand doesn't otherwise specify the directory.
-- default_cwd = "/tmp"
-- default_cwd = "/tmp"
-- The default command to run, if the SpawnCommand doesn't otherwise
-- override it. Note that you may prefer to use `chsh` to set the
-- default shell for your user inside WSL to avoid needing to
-- specify it here
-- The default command to run, if the SpawnCommand doesn't otherwise
-- override it. Note that you may prefer to use `chsh` to set the
-- default shell for your user inside WSL to avoid needing to
-- specify it here
-- default_prog = {"fish"}
},
-- default_prog = {"fish"}
},
}
```

8
docs/config/lua/config/animation_fps.md
View File

@ -14,10 +14,8 @@ If you are running with a CPU renderer (eg: you have [front_end](front_end.md)
transitions:
```lua
return {
animation_fps = 1,
cursor_blink_ease_in = 'Constant',
cursor_blink_ease_out = 'Constant',
}
config.animation_fps = 1
config.cursor_blink_ease_in = 'Constant'
config.cursor_blink_ease_out = 'Constant'
```

4
docs/config/lua/config/automatically_reload_config.md
View File

@ -10,7 +10,5 @@ with a key bound to the action [ReloadConfiguration](../keyassignment/ReloadConf
For example, to disable auto config reload:
```lua
return {
automatically_reload_config = false,
}
config.automatically_reload_config = false
```

134
docs/config/lua/config/background.md
View File

@ -104,84 +104,82 @@ The video at the top of this page demonstrate this configuration in action.
-- for text, so we're going to dim it down to 10% of its normal brightness
local dimmer = { brightness = 0.1 }
return {
enable_scroll_bar = true,
min_scroll_bar_height = '2cell',
colors = {
scrollbar_thumb = 'white',
config.enable_scroll_bar = true
config.min_scroll_bar_height = '2cell'
config.colors = {
scrollbar_thumb = 'white',
}
config.background = {
-- This is the deepest/back-most layer. It will be rendered first
{
source = {
File = '/Alien_Ship_bg_vert_images/Backgrounds/spaceship_bg_1.png',
},
-- The texture tiles vertically but not horizontally.
-- When we repeat it, mirror it so that it appears "more seamless".
-- An alternative to this is to set `width = "100%"` and have
-- it stretch across the display
repeat_x = 'Mirror',
hsb = dimmer,
-- When the viewport scrolls, move this layer 10% of the number of
-- pixels moved by the main viewport. This makes it appear to be
-- further behind the text.
attachment = { Parallax = 0.1 },
},
background = {
-- This is the deepest/back-most layer. It will be rendered first
{
source = {
File = '/Alien_Ship_bg_vert_images/Backgrounds/spaceship_bg_1.png',
},
-- The texture tiles vertically but not horizontally.
-- When we repeat it, mirror it so that it appears "more seamless".
-- An alternative to this is to set `width = "100%"` and have
-- it stretch across the display
repeat_x = 'Mirror',
hsb = dimmer,
-- When the viewport scrolls, move this layer 10% of the number of
-- pixels moved by the main viewport. This makes it appear to be
-- further behind the text.
attachment = { Parallax = 0.1 },
-- Subsequent layers are rendered over the top of each other
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_1_spines.png',
},
-- Subsequent layers are rendered over the top of each other
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_1_spines.png',
},
width = '100%',
repeat_x = 'NoRepeat',
width = '100%',
repeat_x = 'NoRepeat',
-- position the spins starting at the bottom, and repeating every
-- two screens.
vertical_align = 'Bottom',
repeat_y_size = '200%',
hsb = dimmer,
-- position the spins starting at the bottom, and repeating every
-- two screens.
vertical_align = 'Bottom',
repeat_y_size = '200%',
hsb = dimmer,
-- The parallax factor is higher than the background layer, so this
-- one will appear to be closer when we scroll
attachment = { Parallax = 0.2 },
-- The parallax factor is higher than the background layer, so this
-- one will appear to be closer when we scroll
attachment = { Parallax = 0.2 },
},
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_2_alienball.png',
},
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_2_alienball.png',
},
width = '100%',
repeat_x = 'NoRepeat',
width = '100%',
repeat_x = 'NoRepeat',
-- start at 10% of the screen and repeat every 2 screens
vertical_offset = '10%',
repeat_y_size = '200%',
hsb = dimmer,
attachment = { Parallax = 0.3 },
-- start at 10% of the screen and repeat every 2 screens
vertical_offset = '10%',
repeat_y_size = '200%',
hsb = dimmer,
attachment = { Parallax = 0.3 },
},
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_3_lobster.png',
},
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_3_lobster.png',
},
width = '100%',
repeat_x = 'NoRepeat',
width = '100%',
repeat_x = 'NoRepeat',
vertical_offset = '30%',
repeat_y_size = '200%',
hsb = dimmer,
attachment = { Parallax = 0.4 },
vertical_offset = '30%',
repeat_y_size = '200%',
hsb = dimmer,
attachment = { Parallax = 0.4 },
},
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_4_spiderlegs.png',
},
{
source = {
File = '/Alien_Ship_bg_vert_images/Overlays/overlay_4_spiderlegs.png',
},
width = '100%',
repeat_x = 'NoRepeat',
width = '100%',
repeat_x = 'NoRepeat',
vertical_offset = '50%',
repeat_y_size = '150%',
hsb = dimmer,
attachment = { Parallax = 0.5 },
},
vertical_offset = '50%',
repeat_y_size = '150%',
hsb = dimmer,
attachment = { Parallax = 0.5 },
},
}
```

6
docs/config/lua/config/bypass_mouse_reporting_modifiers.md
View File

@ -16,8 +16,6 @@ as though `SHIFT` was not pressed and then match it against the mouse
assignments.
```lua
return {
-- Use ALT instead of SHIFT to bypass application mouse reporting
bypass_mouse_reporting_modifiers = 'ALT',
}
-- Use ALT instead of SHIFT to bypass application mouse reporting
config.bypass_mouse_reporting_modifiers = 'ALT'
```

6
docs/config/lua/config/check_for_updates.md
View File

@ -13,8 +13,6 @@ Set `check_for_updates` to `false` to disable this completely or set
`check_for_updates_interval_seconds` for an alternative update interval.
```lua
return {
check_for_updates = true,
check_for_updates_interval_seconds = 86400,
}
config.check_for_updates = true
config.check_for_updates_interval_seconds = 86400
```

4
docs/config/lua/config/clean_exit_codes.md
View File

@ -15,9 +15,7 @@ with SIGINT, but that bash itself wasn't. In that situation you may wish
to set this config to treat `130` as OK:
```lua
return {
clean_exit_codes = { 130 },
}
config.clean_exit_codes = { 130 }
```
Note that `0` is always treated as a clean exit code and can be omitted

4
docs/config/lua/config/cursor_blink_rate.md
View File

@ -11,9 +11,7 @@ It is recommended to avoid blinking cursors when on battery power, as it is
relatively costly to keep re-rendering for the blink!
```lua
return {
cursor_blink_rate = 800,
}
config.cursor_blink_rate = 800
```
*Since: 20220319-142410-0fcdea07*

10
docs/config/lua/config/daemon_options.md
View File

@ -12,11 +12,9 @@ There are three fields supported:
* `stderr` - specifies where a log of the stderr stream from the daemon will be placed. The default is `$XDG_RUNTIME_DIR/wezterm/stderr` on X11/Wayland systems, or `$HOME/.local/share/wezterm/stderr`.
```lua
return {
daemon_options = {
stdout = '/some/where/stdout',
stderr = '/some/where/stderr',
pid_file = '/some/where/pid_file',
},
config.daemon_options = {
stdout = '/some/where/stdout',
stderr = '/some/where/stderr',
pid_file = '/some/where/pid_file',
}
```

4
docs/config/lua/config/debug_key_events.md
View File

@ -8,9 +8,7 @@ This can be helpful in figuring out how keys are being decoded on your system,
or for discovering the system-dependent "raw" key code values.
```lua
return {
debug_key_events = true,
}
config.debug_key_events = true
```
Produces logs like the following when typing `ls`: (artificially wrapped

4
docs/config/lua/config/default_cursor_style.md
View File

@ -11,9 +11,7 @@ Acceptable values are `SteadyBlock`, `BlinkingBlock`,
and `BlinkingBar`.
```lua
return {
default_cursor_style = 'SteadyBlock',
}
config.default_cursor_style = 'SteadyBlock'
```
Using a blinking style puts more load on the graphics subsystem.

4
docs/config/lua/config/default_domain.md
View File

@ -27,9 +27,7 @@ then wezterm will by default create a `WslDomain` with the name `"WSL:Ubuntu-18.
and if I set my config like this:
```lua
return {
default_domain = 'WSL:Ubuntu-18.04',
}
config.default_domain = 'WSL:Ubuntu-18.04'
```
then when wezterm starts up, it will open with a shell running inside that Ubuntu

4
docs/config/lua/config/default_gui_startup_args.md
View File

@ -13,9 +13,7 @@ If you know that you always want to use wezterm's ssh client to login to a
particular host, then you might consider using this configuration:
```lua
return {
default_gui_startup_args = { 'ssh', 'some-host' },
}
config.default_gui_startup_args = { 'ssh', 'some-host' }
```
which will cause `wezterm` with no additional subcommand arguments to be

4
docs/config/lua/config/default_prog.md
View File

@ -7,9 +7,7 @@ For example, to have `wezterm` always run `top` by default,
you'd use this:
```lua
return {
default_prog = { 'top' },
}
config.default_prog = { 'top' }
```
`default_prog` is implemented as an array where the 0th element

4
docs/config/lua/config/enable_scroll_bar.md
View File

@ -6,9 +6,7 @@ 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.
```lua
return {
enable_scroll_bar = true,
}
config.enable_scroll_bar = true
```

10
docs/config/lua/config/enable_wayland.md
View File

@ -6,14 +6,10 @@ when starting the gui frontend, and instead use X11.
This option is only considered on X11/Wayland systems and
has no effect on macOS or Windows.
The default is false.
The default is true. In versions prior to 20220624-141144-bd1b7c5d it was
disabled by default.
```lua
return {
enable_wayland = true,
}
config.enable_wayland = true
```
*Since: 20220624-141144-bd1b7c5d*
The default is now `true`.

10
docs/config/lua/config/exit_behavior.md
View File

@ -10,9 +10,7 @@ There are three possible values:
* `"CloseOnCleanExit"` - if the shell program exited with a successful status, behave like `"Close"`, otherwise, behave like `"Hold"`. This is the default setting.
```lua
return {
exit_behavior = 'Hold',
}
console.exit_behavior = 'Hold'
```
Note that most unix shells will exit with the status of the last command that
@ -22,9 +20,9 @@ For example, if you interrupt a command and then use `exit` (with no arguments),
CTRL-D to send EOF to the shell, the shell will return an unsuccessful exit
status. The same thing holds if you were to run:
```
false
exit
```console
$ false
$ exit
```
With the default `exit_behavior="CloseOnCleanExit"` setting, that will cause

16
docs/config/lua/config/font_dirs.md
View File

@ -6,13 +6,11 @@ if you configure the `font_dirs` option, wezterm will load fonts from that
set of directories:
```lua
return {
-- This tells wezterm to look first for fonts in the directory named
-- `fonts` that is found alongside your `wezterm.lua` file.
-- As this option is an array, you may list multiple locations if
-- you wish.
font_dirs = { 'fonts' },
}
-- This tells wezterm to look first for fonts in the directory named
-- `fonts` that is found alongside your `wezterm.lua` file.
-- As this option is an array, you may list multiple locations if
-- you wish.
config.font_dirs = { 'fonts' }
```
wezterm will scan the `font_dirs` to build a database of available fonts. When
@ -27,9 +25,7 @@ systems and don't want to install those fonts on every system that you use,
then you can set:
```lua
return {
font_locator = 'ConfigDirsOnly',
}
config.font_locator = 'ConfigDirsOnly'
```

150
docs/config/lua/config/font_rules.md
View File

@ -59,66 +59,62 @@ font-weights that are either too bold or too light for the default rules to
produce great results, hence this set of rules.
```lua
local wezterm = require 'wezterm'
config.font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium'
config.font_rules = {
-- For Bold-but-not-italic text, use this relatively bold font, and override
-- its color to a tomato-red color to make bold text really stand out.
{
intensity = 'Bold',
italic = false,
font = wezterm.font_with_fallback(
'Operator Mono SSm Lig',
-- Override the color specified by the terminal output and force
-- it to be tomato-red.
-- The color value you set here can be any CSS color name or
-- RGB color string.
{ foreground = 'tomato' }
),
},
return {
font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium',
font_rules = {
-- For Bold-but-not-italic text, use this relatively bold font, and override
-- its color to a tomato-red color to make bold text really stand out.
{
intensity = 'Bold',
italic = false,
font = wezterm.font_with_fallback(
'Operator Mono SSm Lig',
-- Override the color specified by the terminal output and force
-- it to be tomato-red.
-- The color value you set here can be any CSS color name or
-- RGB color string.
{ foreground = 'tomato' }
),
},
-- Bold-and-italic
{
intensity = 'Bold',
-- Bold-and-italic
{
intensity = 'Bold',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
italic = true,
},
},
},
-- normal-intensity-and-italic
{
intensity = 'Normal',
-- normal-intensity-and-italic
{
intensity = 'Normal',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'DemiLight',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'DemiLight',
italic = true,
},
},
},
-- half-intensity-and-italic (half-bright or dim); use a lighter weight font
{
intensity = 'Half',
-- half-intensity-and-italic (half-bright or dim); use a lighter weight font
{
intensity = 'Half',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'Light',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'Light',
italic = true,
},
},
},
-- half-intensity-and-not-italic
{
intensity = 'Half',
italic = false,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'Light',
},
-- half-intensity-and-not-italic
{
intensity = 'Half',
italic = false,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'Light',
},
},
}
@ -127,37 +123,33 @@ return {
Here's another example combining `FiraCode` with `Victor Mono`, using `Victor Mono` only for italics:
```lua
local wezterm = require 'wezterm'
config.font = wezterm.font { family = 'FiraCode' }
return {
font = wezterm.font { family = 'FiraCode' },
font_rules = {
{
intensity = 'Bold',
italic = true,
font = wezterm.font {
family = 'VictorMono',
weight = 'Bold',
style = 'Italic',
},
config.font_rules = {
{
intensity = 'Bold',
italic = true,
font = wezterm.font {
family = 'VictorMono',
weight = 'Bold',
style = 'Italic',
},
{
italic = true,
intensity = 'Half',
font = wezterm.font {
family = 'VictorMono',
weight = 'DemiBold',
style = 'Italic',
},
},
{
italic = true,
intensity = 'Half',
font = wezterm.font {
family = 'VictorMono',
weight = 'DemiBold',
style = 'Italic',
},
{
italic = true,
intensity = 'Normal',
font = wezterm.font {
family = 'VictorMono',
style = 'Italic',
},
},
{
italic = true,
intensity = 'Normal',
font = wezterm.font {
family = 'VictorMono',
style = 'Italic',
},
},
}
@ -168,7 +160,7 @@ return {
You can run `wezterm ls-fonts` to summarize the font rules and the fonts that
match them:
```bash
```console
$ wezterm ls-fonts
Primary font:
wezterm.font_with_fallback({

12
docs/config/lua/config/foreground_text_hsb.md
View File

@ -23,13 +23,11 @@ values, so the default of 1.0 preserves the existing component, whilst 0.5 will
reduce it by half, and 2.0 will double the value.
```lua
return {
-- This increases color saturation by 50%
foreground_text_hsb = {
hue = 1.0,
saturation = 1.5,
brightness = 1.0,
},
-- This increases color saturation by 50%
config.foreground_text_hsb = {
hue = 1.0,
saturation = 1.5,
brightness = 1.0,
}
```

8
docs/config/lua/config/freetype_load_flags.md
View File

@ -21,10 +21,8 @@ Available flags are:
* `NO_AUTOHINT` - don't use the freetype auto-hinter
```lua
return {
-- You probably don't want to do this, but this demonstrates
-- that the flags can be combined
freetype_load_flags = 'NO_HINTING|MONOCHROME',
}
-- You probably don't want to do this, but this demonstrates
-- that the flags can be combined
config.freetype_load_flags = 'NO_HINTING|MONOCHROME'
```

6
docs/config/lua/config/freetype_render_target.md
View File

@ -13,9 +13,7 @@ For example, this configuration uses light hinting but produces
subpixel-antialiased glyph bitmaps:
```lua
return {
freetype_load_target = 'Light',
freetype_render_target = 'HorizontalLcd',
}
config.freetype_load_target = 'Light'
config.freetype_render_target = 'HorizontalLcd'
```

4
docs/config/lua/config/hide_mouse_cursor_when_typing.md
View File

@ -8,7 +8,5 @@ hovering over the window.
The default is `true`. Set to `false` to disable this behavior.
```lua
return {
hide_mouse_cursor_when_typing = true,
}
config.hide_mouse_cursor_when_typing = true
```

82
docs/config/lua/config/hyperlink_rules.md
View File

@ -24,42 +24,40 @@ The default value for `hyperlink_rules` can be retrieved using
and is shown below:
```lua
return {
hyperlink_rules = {
-- Matches: a URL in parens: (URL)
{
regex = '\\((\\w+://\\S+)\\)',
format = '$1',
highlight = 1,
},
-- Matches: a URL in brackets: [URL]
{
regex = '\\[(\\w+://\\S+)\\]',
format = '$1',
highlight = 1,
},
-- Matches: a URL in curly braces: {URL}
{
regex = '\\{(\\w+://\\S+)\\}',
format = '$1',
highlight = 1,
},
-- Matches: a URL in angle brackets: <URL>
{
regex = '<(\\w+://\\S+)>',
format = '$1',
highlight = 1,
},
-- Then handle URLs not wrapped in brackets
{
regex = '\\b\\w+://\\S+[)/a-zA-Z0-9-]+',
format = '$0',
},
-- implicit mailto link
{
regex = '\\b\\w+@[\\w-]+(\\.[\\w-]+)+\\b',
format = 'mailto:$0',
},
config.hyperlink_rules = {
-- Matches: a URL in parens: (URL)
{
regex = '\\((\\w+://\\S+)\\)',
format = '$1',
highlight = 1,
},
-- Matches: a URL in brackets: [URL]
{
regex = '\\[(\\w+://\\S+)\\]',
format = '$1',
highlight = 1,
},
-- Matches: a URL in curly braces: {URL}
{
regex = '\\{(\\w+://\\S+)\\}',
format = '$1',
highlight = 1,
},
-- Matches: a URL in angle brackets: <URL>
{
regex = '<(\\w+://\\S+)>',
format = '$1',
highlight = 1,
},
-- Then handle URLs not wrapped in brackets
{
regex = '\\b\\w+://\\S+[)/a-zA-Z0-9-]+',
format = '$0',
},
-- implicit mailto link
{
regex = '\\b\\w+@[\\w-]+(\\.[\\w-]+)+\\b',
format = 'mailto:$0',
},
}
```
@ -84,14 +82,12 @@ return {
Some other examples include:
```lua
local wezterm = require 'wezterm'
-- Use the defaults as a base
local hyperlink_rules = wezterm.default_hyperlink_rules()
config.hyperlink_rules = wezterm.default_hyperlink_rules()
-- make task numbers clickable
-- the first matched regex group is captured in $1.
table.insert(hyperlink_rules, {
table.insert(config.hyperlink_rules, {
regex = [[\b[tt](\d+)\b]],
format = 'https://example.com/tasks/?t=$1',
})
@ -100,12 +96,8 @@ table.insert(hyperlink_rules, {
-- ( "nvim-treesitter/nvim-treesitter" | wbthomason/packer.nvim | wez/wezterm | "wez/wezterm.git" )
-- as long as a full url hyperlink regex exists above this it should not match a full url to
-- github or gitlab / bitbucket (i.e. https://gitlab.com/user/project.git is still a whole clickable url)
table.insert(hyperlink_rules, {
table.insert(config.hyperlink_rules, {
regex = [[["]?([\w\d]{1}[-\w\d]+)(/){1}([-\w\d\.]+)["]?]],
format = 'https://www.github.com/$1/$3',
})
return {
hyperlink_rules = hyperlink_rules,
}
```

4
docs/config/lua/config/ime_preedit_rendering.md
View File

@ -25,9 +25,7 @@ WezTerm supports the following IME preedit rendering.
You can control IME preedit rendering in your configuraiton file:
```lua
return {
ime_preedit_rendering = 'System',
}
config.ime_preedit_rendering = 'System'
```
Otherwise, the default is `"Builtin"`.

5
docs/config/lua/config/index.markdown
View File

@ -1,3 +1,8 @@
---
search:
exclude: true
---
# `Config` struct
The `return` statement at the end of your `wezterm.lua` file returns

42
docs/config/lua/config/launch_menu.md
View File

@ -11,30 +11,28 @@ Each entry in `launch_menu` is an instance of a
[SpawnCommand](../SpawnCommand.md) object.
```lua
return {
launch_menu = {
{
args = { 'top' },
},
{
-- Optional label to show in the launcher. If omitted, a label
-- is derived from the `args`
label = 'Bash',
-- The argument array to spawn. If omitted the default program
-- will be used as described in the documentation above
args = { 'bash', '-l' },
config.launch_menu = {
{
args = { 'top' },
},
{
-- Optional label to show in the launcher. If omitted, a label
-- is derived from the `args`
label = 'Bash',
-- The argument array to spawn. If omitted the default program
-- will be used as described in the documentation above
args = { 'bash', '-l' },
-- You can specify an alternative current working directory;
-- if you don't specify one then a default based on the OSC 7
-- escape sequence will be used (see the Shell Integration
-- docs), falling back to the home directory.
-- cwd = "/some/path"
-- You can specify an alternative current working directory;
-- if you don't specify one then a default based on the OSC 7
-- escape sequence will be used (see the Shell Integration
-- docs), falling back to the home directory.
-- cwd = "/some/path"
-- You can override environment variables just for this command
-- by setting this here. It has the same semantics as the main
-- set_environment_variables configuration option described above
-- set_environment_variables = { FOO = "bar" },
},
-- You can override environment variables just for this command
-- by setting this here. It has the same semantics as the main
-- set_environment_variables configuration option described above
-- set_environment_variables = { FOO = "bar" },
},
}
```

10
docs/config/lua/config/mux_env_remove.md
View File

@ -12,11 +12,9 @@ spawned by the multiplexer server.
The default value for this is:
```lua
return {
mux_env_remove = {
'SSH_AUTH_SOCK',
'SSH_CLIENT',
'SSH_CONNECTION',
},
config.mux_env_remove = {
'SSH_AUTH_SOCK',
'SSH_CLIENT',
'SSH_CONNECTION',
}
```

10
docs/config/lua/config/quick_select_patterns.md
View File

@ -6,12 +6,10 @@ Specify additional patterns to match when in [quick select mode](../../../quicks
This setting is a table listing out a set of regular expressions.
```lua
return {
quick_select_patterns = {
-- match things that look like sha1 hashes
-- (this is actually one of the default patterns)
'[0-9a-f]{7,40}',
},
config.quick_select_patterns = {
-- match things that look like sha1 hashes
-- (this is actually one of the default patterns)
'[0-9a-f]{7,40}',
}
```

4
docs/config/lua/config/selection_word_boundary.md
View File

@ -10,7 +10,5 @@ Defaults to ``" \t\n{}[]()\"'`"``.
For example, to always include spaces and newline when selecting a word, but stop on punctuations:
```lua
return {
selection_word_boundary = '{}[]()"\'`.,;:',
}
config.selection_word_boundary = '{}[]()"\'`.,;:'
```

10
docs/config/lua/config/show_new_tab_button_in_tab_bar.md
View File

@ -12,17 +12,13 @@ This example turns off the tabs and new-tab button, leaving just the left and
right status areas:
```lua
local wezterm = require 'wezterm'
wezterm.on('update-right-status', function(window, pane)
window:set_left_status 'left'
window:set_right_status 'right'
end)
return {
use_fancy_tab_bar = false,
show_tabs_in_tab_bar = false,
show_new_tab_button_in_tab_bar = false,
}
config.use_fancy_tab_bar = false
config.show_tabs_in_tab_bar = false
config.show_new_tab_button_in_tab_bar = false
```

10
docs/config/lua/config/show_tabs_in_tab_bar.md
View File

@ -11,16 +11,12 @@ This example turns off the tabs and new-tab button, leaving just the left and
right status areas:
```lua
local wezterm = require 'wezterm'
wezterm.on('update-right-status', function(window, pane)
window:set_left_status 'left'
window:set_right_status 'right'
end)
return {
use_fancy_tab_bar = false,
show_tabs_in_tab_bar = false,
show_new_tab_button_in_tab_bar = false,
}
config.use_fancy_tab_bar = false
config.show_tabs_in_tab_bar = false
config.show_new_tab_button_in_tab_bar = false
```

4
docs/config/lua/config/show_update_window.md
View File

@ -8,7 +8,5 @@ See [check_for_updates](check_for_updates.md) for more information on
the automatic update checks.
```lua
return {
show_update_window = false,
}
config.show_update_window = false
```

42
docs/config/lua/config/skip_close_confirmation_for_processes_named.md
View File

@ -15,41 +15,19 @@ not prompt for closing that particular pane.
The default value for this setting is shown below:
```lua
return {
skip_close_confirmation_for_processes_named = {
'bash',
'sh',
'zsh',
'fish',
'tmux',
},
config.skip_close_confirmation_for_processes_named = {
'bash',
'sh',
'zsh',
'fish',
'tmux',
'nu',
'cmd.exe',
'pwsh.exe',
'powershell.exe',
}
```
*Since: 20210814-124438-54e29167*:
This option now also works on Windows (prior versions only worked on Linux and
macOS), and the default value for this setting now includes some windows shell
processes:
```lua
return {
skip_close_confirmation_for_processes_named = {
'bash',
'sh',
'zsh',
'fish',
'tmux',
'nu',
'cmd.exe',
'pwsh.exe',
'powershell.exe',
},
}
```
*Since: 20220101-133340-7edc5b5a*
More advanced control over this behavior can be achieved by defining a
[mux-is-process-stateful](../mux-events/mux-is-process-stateful.md) event handler.

46
docs/config/lua/config/tab_bar_style.md
View File

@ -41,33 +41,31 @@ This example changes the tab edges to the PowerLine arrow symbols:
local wezterm = require 'wezterm'
-- The filled in variant of the < symbol
local SOLID_LEFT_ARROW = utf8.char(0xe0b2)
local SOLID_LEFT_ARROW = wezterm.nerdfonts.pl_right_hard_divider
-- The filled in variant of the > symbol
local SOLID_RIGHT_ARROW = utf8.char(0xe0b0)
local SOLID_RIGHT_ARROW = wezterm.nerdfonts.pl_left_hard_divider
return {
tab_bar_style = {
active_tab_left = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#2b2042' } },
{ Text = SOLID_LEFT_ARROW },
},
active_tab_right = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#2b2042' } },
{ Text = SOLID_RIGHT_ARROW },
},
inactive_tab_left = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#1b1032' } },
{ Text = SOLID_LEFT_ARROW },
},
inactive_tab_right = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#1b1032' } },
{ Text = SOLID_RIGHT_ARROW },
},
config.tab_bar_style = {
active_tab_left = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#2b2042' } },
{ Text = SOLID_LEFT_ARROW },
},
active_tab_right = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#2b2042' } },
{ Text = SOLID_RIGHT_ARROW },
},
inactive_tab_left = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#1b1032' } },
{ Text = SOLID_LEFT_ARROW },
},
inactive_tab_right = wezterm.format {
{ Background = { Color = '#0b0022' } },
{ Foreground = { Color = '#1b1032' } },
{ Text = SOLID_RIGHT_ARROW },
},
}
```

4
docs/config/lua/config/tab_max_width.md
View File

@ -7,7 +7,5 @@ using fancy tab mode.
Defaults to 16 glyphs in width.
```lua
return {
tab_max_width = 16,
}
config.tab_max_width = 16
```

14
docs/config/lua/config/term.md
View File

@ -8,8 +8,8 @@ data.
If you want to get the most application support out of wezterm, then you may
wish to install a copy of the `wezterm` TERM definition:
```
tempfile=$(mktemp) \
```console
$ tempfile=$(mktemp) \
&& curl -o $tempfile https://raw.githubusercontent.com/wez/wezterm/main/termwiz/data/wezterm.terminfo \
&& tic -x -o ~/.terminfo $tempfile \
&& rm $tempfile
@ -29,11 +29,9 @@ If your package manager installed the terminfo data in a non-standard location,
The following snippet works if you installed `wezterm.terminfo` with nix into your user profile. Update the path to `TERMINFO_DIRS` to match the location on your system.
```lua
return {
set_environment_variables = {
TERMINFO_DIRS = '/home/user/.nix-profile/share/terminfo',
WSLENV = 'TERMINFO_DIRS',
},
term = 'wezterm',
config.set_environment_variables = {
TERMINFO_DIRS = '/home/user/.nix-profile/share/terminfo',
WSLENV = 'TERMINFO_DIRS',
}
config.term = 'wezterm'
```

4
docs/config/lua/config/text_blink_rate.md
View File

@ -9,9 +9,7 @@ event loop schedulers manage timers; non-zero values will be at least the
interval specified with some degree of slop.
```lua
return {
text_blink_rate = 500,
}
config.text_blink_rate = 500
```
*Since: 20220319-142410-0fcdea07*

4
docs/config/lua/config/text_blink_rate_rapid.md
View File

@ -9,9 +9,7 @@ event loop schedulers manage timers; non-zero values will be at least the
interval specified with some degree of slop.
```lua
return {
text_blink_rate_rapid = 250,
}
config.text_blink_rate_rapid = 250
```
*Since: 20220319-142410-0fcdea07*

4
docs/config/lua/config/treat_left_ctrlalt_as_altgr.md
View File

@ -11,7 +11,5 @@ To fix this behavior you can tell WezTerm to treat left *Ctrl-Alt* keys as
bindings using separate Ctrl and Alt won't be triggered anymore.
```lua
return {
treat_left_ctrlalt_as_altgr = true,
}
config.treat_left_ctrlalt_as_altgr = true
```

4
docs/config/lua/config/use_ime.md
View File

@ -16,9 +16,7 @@ IME support is a platform dependent feature
You can control whether the IME is enabled in your configuration file:
```lua
return {
use_ime = false,
}
config.use_ime = false
```
Changing `use_ime` usually requires re-launching WezTerm to take full effect.

28
docs/config/lua/config/visual_bell.md
View File

@ -32,28 +32,24 @@ The following easing functions are supported:
The following configuration enables a low intensity visual bell that takes a total of 300ms to "flash" the screen:
```lua
return {
visual_bell = {
fade_in_function = 'EaseIn',
fade_in_duration_ms = 150,
fade_out_function = 'EaseOut',
fade_out_duration_ms = 150,
},
colors = {
visual_bell = '#202020',
},
config.visual_bell = {
fade_in_function = 'EaseIn',
fade_in_duration_ms = 150,
fade_out_function = 'EaseOut',
fade_out_duration_ms = 150,
}
config.colors = {
visual_bell = '#202020',
}
```
The follow configuration make the cursor briefly flare when the bell is run:
```lua
return {
visual_bell = {
fade_in_duration_ms = 75,
fade_out_duration_ms = 75,
target = 'CursorColor',
},
config.visual_bell = {
fade_in_duration_ms = 75,
fade_out_duration_ms = 75,
target = 'CursorColor',
}
```

42
docs/config/lua/config/webgpu_preferred_adapter.md
View File

@ -48,32 +48,28 @@ Based on that list, I might choose to explicitly target the discrete Gpu like
this (but note that this would be the default selection anyway):
```lua
local wezterm = require 'wezterm'
return {
webgpu_preferred_adapter = {
backend = 'Vulkan',
device = 29730,
device_type = 'DiscreteGpu',
driver = 'radv',
driver_info = 'Mesa 22.3.4',
name = 'AMD Radeon Pro W6400 (RADV NAVI24)',
vendor = 4098,
},
front_end = 'WebGpu',
config.webgpu_preferred_adapter = {
backend = 'Vulkan',
device = 29730,
device_type = 'DiscreteGpu',
driver = 'radv',
driver_info = 'Mesa 22.3.4',
name = 'AMD Radeon Pro W6400 (RADV NAVI24)',
vendor = 4098,
}
config.front_end = 'WebGpu'
```
alternatively, I might use:
```lua
local wezterm = require 'wezterm'
local config = {}
local gpus = wezterm.gui.enumerate_gpus()
return {
webgpu_preferred_adapter = gpus[1],
front_end = 'WebGpu',
}
config.webgpu_preferred_adapter = gpus[1]
config.front_end = 'WebGpu'
return config
```
If you have a more complex situation you can get a bit more elaborate; this
@ -82,21 +78,17 @@ Vulkan drivers:
```lua
local wezterm = require 'wezterm'
local adapter = nil
local front_end = nil
local config = {}
for _, gpu in ipairs(wezterm.gui.enumerate_gpus()) do
if gpu.backend == 'Vulkan' and gpu.device_type == 'Integrated' then
adapter = gpu
front_end = 'WebGpu'
config.webgpu_preferred_adapter = gpu
config.front_end = 'WebGpu'
break
end
end
return {
webgpu_preferred_adapter = adapter,
front_end = front_end,
}
return config
```
See also [webgpu_power_preference](webgpu_power_preference.md),

146
docs/config/lua/config/window_background_gradient.md
View File

@ -9,57 +9,55 @@ for `window_background_image` is ignored.
Linear gradients with vertical or horizontal orientation are supported:
```lua
return {
window_background_gradient = {
-- Can be "Vertical" or "Horizontal". Specifies the direction
-- in which the color gradient varies. The default is "Horizontal",
-- with the gradient going from left-to-right.
-- Linear and Radial gradients are also supported; see the other
-- examples below
orientation = 'Vertical',
config.window_background_gradient = {
-- Can be "Vertical" or "Horizontal". Specifies the direction
-- in which the color gradient varies. The default is "Horizontal",
-- with the gradient going from left-to-right.
-- Linear and Radial gradients are also supported; see the other
-- examples below
orientation = 'Vertical',
-- Specifies the set of colors that are interpolated in the gradient.
-- Accepts CSS style color specs, from named colors, through rgb
-- strings and more
colors = {
'#0f0c29',
'#302b63',
'#24243e',
},
-- Instead of specifying `colors`, you can use one of a number of
-- predefined, preset gradients.
-- A list of presets is shown in a section below.
-- preset = "Warm",
-- Specifies the interpolation style to be used.
-- "Linear", "Basis" and "CatmullRom" as supported.
-- The default is "Linear".
interpolation = 'Linear',
-- How the colors are blended in the gradient.
-- "Rgb", "LinearRgb", "Hsv" and "Oklab" are supported.
-- The default is "Rgb".
blend = 'Rgb',
-- To avoid vertical color banding for horizontal gradients, the
-- gradient position is randomly shifted by up to the `noise` value
-- for each pixel.
-- Smaller values, or 0, will make bands more prominent.
-- The default value is 64 which gives decent looking results
-- on a retina macbook pro display.
-- noise = 64,
-- By default, the gradient smoothly transitions between the colors.
-- You can adjust the sharpness by specifying the segment_size and
-- segment_smoothness parameters.
-- segment_size configures how many segments are present.
-- segment_smoothness is how hard the edge is; 0.0 is a hard edge,
-- 1.0 is a soft edge.
-- segment_size = 11,
-- segment_smoothness = 0.0,
-- Specifies the set of colors that are interpolated in the gradient.
-- Accepts CSS style color specs, from named colors, through rgb
-- strings and more
colors = {
'#0f0c29',
'#302b63',
'#24243e',
},
-- Instead of specifying `colors`, you can use one of a number of
-- predefined, preset gradients.
-- A list of presets is shown in a section below.
-- preset = "Warm",
-- Specifies the interpolation style to be used.
-- "Linear", "Basis" and "CatmullRom" as supported.
-- The default is "Linear".
interpolation = 'Linear',
-- How the colors are blended in the gradient.
-- "Rgb", "LinearRgb", "Hsv" and "Oklab" are supported.
-- The default is "Rgb".
blend = 'Rgb',
-- To avoid vertical color banding for horizontal gradients, the
-- gradient position is randomly shifted by up to the `noise` value
-- for each pixel.
-- Smaller values, or 0, will make bands more prominent.
-- The default value is 64 which gives decent looking results
-- on a retina macbook pro display.
-- noise = 64,
-- By default, the gradient smoothly transitions between the colors.
-- You can adjust the sharpness by specifying the segment_size and
-- segment_smoothness parameters.
-- segment_size configures how many segments are present.
-- segment_smoothness is how hard the edge is; 0.0 is a hard edge,
-- 1.0 is a soft edge.
-- segment_size = 11,
-- segment_smoothness = 0.0,
}
```
@ -86,12 +84,10 @@ clockwise, so `-45` is equivalent to `315` degrees and results in a gradient
that is moving from the top left corner down to the bottom right corner.
```lua
return {
window_background_gradient = {
colors = { '#EEBD89', '#D13ABD' },
-- Specifices a Linear gradient starting in the top left corner.
orientation = { Linear = { angle = -45.0 } },
},
config.window_background_gradient = {
colors = { '#EEBD89', '#D13ABD' },
-- Specifices a Linear gradient starting in the top left corner.
orientation = { Linear = { angle = -45.0 } },
}
```
@ -103,29 +99,27 @@ Radial gradients are implemented using a notional perfect circle that is
subsequently stretched to fill the dimensions of the window.
```lua
return {
color_scheme = 'Github',
window_background_gradient = {
colors = { 'deeppink', 'gold' },
orientation = {
Radial = {
-- Specifies the x coordinate of the center of the circle,
-- in the range 0.0 through 1.0. The default is 0.5 which
-- is centered in the X dimension.
cx = 0.75,
config.color_scheme = 'Github'
config.window_background_gradient = {
colors = { 'deeppink', 'gold' },
orientation = {
Radial = {
-- Specifies the x coordinate of the center of the circle,
-- in the range 0.0 through 1.0. The default is 0.5 which
-- is centered in the X dimension.
cx = 0.75,
-- Specifies the y coordinate of the center of the circle,
-- in the range 0.0 through 1.0. The default is 0.5 which
-- is centered in the Y dimension.
cy = 0.75,
-- Specifies the y coordinate of the center of the circle,
-- in the range 0.0 through 1.0. The default is 0.5 which
-- is centered in the Y dimension.
cy = 0.75,
-- Specifies the radius of the notional circle.
-- The default is 0.5, which combined with the default cx
-- and cy values places the circle in the center of the
-- window, with the edges touching the window edges.
-- Values larger than 1 are possible.
radius = 1.25,
},
-- Specifies the radius of the notional circle.
-- The default is 0.5, which combined with the default cx
-- and cy values places the circle in the center of the
-- window, with the edges touching the window edges.
-- Values larger than 1 are possible.
radius = 1.25,
},
},
}

4
docs/config/lua/config/window_close_confirmation.md
View File

@ -8,9 +8,7 @@ Set this to `"NeverPrompt"` if you don't like confirming closing
windows every time.
```lua
return {
window_close_confirmation = 'AlwaysPrompt',
}
config.window_close_confirmation = 'AlwaysPrompt'
```
See also

44
docs/config/lua/config/window_frame.md
View File

@ -10,19 +10,17 @@ It allows you to customize the colors of the window frame.
Some of these colors are used by the fancy tab bar.
```lua
return {
window_frame = {
inactive_titlebar_bg = '#353535',
active_titlebar_bg = '#2b2042',
inactive_titlebar_fg = '#cccccc',
active_titlebar_fg = '#ffffff',
inactive_titlebar_border_bottom = '#2b2042',
active_titlebar_border_bottom = '#2b2042',
button_fg = '#cccccc',
button_bg = '#2b2042',
button_hover_fg = '#ffffff',
button_hover_bg = '#3b3052',
},
config.window_frame = {
inactive_titlebar_bg = '#353535',
active_titlebar_bg = '#2b2042',
inactive_titlebar_fg = '#cccccc',
active_titlebar_fg = '#ffffff',
inactive_titlebar_border_bottom = '#2b2042',
active_titlebar_border_bottom = '#2b2042',
button_fg = '#cccccc',
button_bg = '#2b2042',
button_hover_fg = '#ffffff',
button_hover_bg = '#3b3052',
}
```
@ -31,16 +29,14 @@ return {
You may explicitly add a border around the window area:
```lua
return {
window_frame = {
border_left_width = '0.5cell',
border_right_width = '0.5cell',
border_bottom_height = '0.25cell',
border_top_height = '0.25cell',
border_left_color = 'purple',
border_right_color = 'purple',
border_bottom_color = 'purple',
border_top_color = 'purple',
},
config.window_frame = {
border_left_width = '0.5cell',
border_right_width = '0.5cell',
border_bottom_height = '0.25cell',
border_top_height = '0.25cell',
border_left_color = 'purple',
border_right_color = 'purple',
border_bottom_color = 'purple',
border_top_color = 'purple',
}
```

24
docs/config/lua/config/window_padding.md
View File

@ -11,13 +11,11 @@ enabled the scrollbar and have set `right` to `0` then the right padding
(and thus the scrollbar width) will instead match the width of a cell.
```lua
return {
window_padding = {
left = 2,
right = 2,
top = 0,
bottom = 0,
},
config.window_padding = {
left = 2,
right = 2,
top = 0,
bottom = 0,
}
```
@ -36,13 +34,11 @@ You may use a fractional number such as `"0.5cell"` or numbers large than one su
The default padding is shown below. In earlier releases, the default padding was 0 for each of the possible edges.
```lua
return {
window_padding = {
left = '1cell',
right = '1cell',
top = '0.5cell',
bottom = '0.5cell',
},
config.window_padding = {
left = '1cell',
right = '1cell',
top = '0.5cell',
bottom = '0.5cell',
}
```

4
docs/config/lua/config/xim_im_name.md
View File

@ -13,9 +13,7 @@ to quickly evaluate a different input method server, then you could
update your config to specify it explicitly:
```lua
return {
xim_im_name = 'fcitx',
}
config.xim_im_name = 'fcitx'
```
will cause wezterm to connect to fcitx regardless of the value of `XMODIFIERS`.

53
docs/config/lua/general.md
View File

@ -6,55 +6,8 @@ be imported into your configuration file:
```lua
local wezterm = require 'wezterm'
return {
font = wezterm.font 'JetBrains Mono',
}
local config = {}
config.font = wezterm.font 'JetBrains Mono'
return config
```
### Making your own Lua Modules
If you'd like to break apart your configuration into multiple files, you'll
be interested in this information.
The `package.path` is configured with the following paths in this order:
* On Windows: a `wezterm_modules` dir in the same directory as `wezterm.exe`
* `~/.config/wezterm`
* `~/.wezterm`
* A system specific set of paths which may (or may not!) find locally installed lua modules
That means that if you wanted to break your config up into a `helpers.lua` file
you would place it in `~/.config/wezterm/helpers.lua` with contents like this:
```lua
-- I am helpers.lua and I should live in ~/.config/wezterm/helpers.lua
local wezterm = require 'wezterm'
-- This is the module table that we will export
local module = {}
-- This function is private to this module and is not visible
-- outside.
local function private_helper()
wezterm.log_error 'hello!'
end
-- define a function in the module table.
-- Only functions defined in `module` will be exported to
-- code that imports this module
function module.my_function()
private_helper()
end
-- return our module table
return module
```
and then in your `wezterm.lua`
you would use it like this:
```lua
local helpers = require 'helpers'
helpers.my_function()
```

9
docs/config/lua/gui-events/gui-startup.md
View File

@ -35,6 +35,7 @@ This basic example splits an initial window into thirds:
```lua
local wezterm = require 'wezterm'
local mux = wezterm.mux
local config = {}
wezterm.on('gui-startup', function(cmd)
local tab, pane, window = mux.spawn_window(cmd or {})
@ -46,7 +47,7 @@ wezterm.on('gui-startup', function(cmd)
pane:split { size = 0.5 }
end)
return {}
return config
```
This example creates a default window but makes it maximize on startup:
@ -54,13 +55,14 @@ This example creates a default window but makes it maximize on startup:
```lua
local wezterm = require 'wezterm'
local mux = wezterm.mux
local config = {}
wezterm.on('gui-startup', function(cmd)
local tab, pane, window = mux.spawn_window(cmd or {})
window:gui_window():maximize()
end)
return {}
return config
```
Here's a more elaborate example that configures two workspaces:
@ -68,6 +70,7 @@ Here's a more elaborate example that configures two workspaces:
```lua
local wezterm = require 'wezterm'
local mux = wezterm.mux
local config = {}
wezterm.on('gui-startup', function(cmd)
-- allow `wezterm start -- something` to affect what we spawn
@ -104,7 +107,7 @@ wezterm.on('gui-startup', function(cmd)
mux.set_active_workspace 'coding'
end)
return {}
return config
```
See also:

12
docs/config/lua/keyassignment/ActivateCommandPalette.md
View File

@ -5,13 +5,11 @@
Activates the Command Palette, a modal overlay that enables discovery and activation of various commands.
```lua
return {
keys = {
{
key = 'P',
mods = 'CTRL',
action = wezterm.action.ActivateCommandPalette,
},
config.keys = {
{
key = 'P',
mods = 'CTRL',
action = wezterm.action.ActivateCommandPalette,
},
}
```

6
docs/config/lua/keyassignment/ActivateCopyMode.md
View File

@ -5,10 +5,8 @@
Activates copy mode!
```lua
return {
keys = {
{ key = 'X', mods = 'CTRL', action = wezterm.action.ActivateCopyMode },
},
config.keys = {
{ key = 'X', mods = 'CTRL', action = wezterm.action.ActivateCopyMode },
}
```

16
docs/config/lua/keyassignment/ActivateLastTab.md
View File

@ -5,15 +5,13 @@
Activate the previously active tab. If there is none, it will do nothing.
```lua
return {
leader = { key = 'a', mods = 'CTRL' },
keys = {
-- CTRL-a, followed by CTRL-o will switch back to the last active tab
{
key = 'o',
mods = 'LEADER|CTRL',
action = wezterm.action.ActivateLastTab,
},
config.leader = { key = 'a', mods = 'CTRL' }
config.keys = {
-- CTRL-a, followed by CTRL-o will switch back to the last active tab
{
key = 'o',
mods = 'LEADER|CTRL',
action = wezterm.action.ActivateLastTab,
},
}
```

13
docs/config/lua/keyassignment/ActivatePaneByIndex.md
View File

@ -11,12 +11,13 @@ panes, respectively:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
keys = {
{ key = 'a', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
{ key = 'b', mods = 'ALT', action = act.ActivatePaneByIndex(1) },
{ key = 'c', mods = 'ALT', action = act.ActivatePaneByIndex(2) },
},
config.keys = {
{ key = 'a', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
{ key = 'b', mods = 'ALT', action = act.ActivatePaneByIndex(1) },
{ key = 'c', mods = 'ALT', action = act.ActivatePaneByIndex(2) },
}
return config
```

44
docs/config/lua/keyassignment/ActivatePaneDirection.md
View File

@ -12,31 +12,31 @@ by the [`unzoom_on_switch_pane`](../config/unzoom_on_switch_pane.md) flag.
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
keys = {
{
key = 'LeftArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Left',
},
{
key = 'RightArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Right',
},
{
key = 'UpArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Up',
},
{
key = 'DownArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Down',
},
config.keys = {
{
key = 'LeftArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Left',
},
{
key = 'RightArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Right',
},
{
key = 'UpArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Up',
},
{
key = 'DownArrow',
mods = 'CTRL|SHIFT',
action = act.ActivatePaneDirection 'Down',
},
}
return config
```
*Since: 20220101-133340-7edc5b5a*

11
docs/config/lua/keyassignment/ActivateTab.md
View File

@ -13,25 +13,24 @@ to its left and so on.
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
local mykeys = {}
config.keys = {}
for i = 1, 8 do
-- CTRL+ALT + number to activate that tab
table.insert(mykeys, {
table.insert(config.keys, {
key = tostring(i),
mods = 'CTRL|ALT',
action = act.ActivateTab(i - 1),
})
-- F1 through F8 to activate that tab
table.insert(mykeys, {
table.insert(config.keys, {
key = 'F' .. tostring(i),
action = act.ActivateTab(i - 1),
})
end
return {
keys = mykeys,
}
return config
```

11
docs/config/lua/keyassignment/ActivateTabRelative.md
View File

@ -7,13 +7,14 @@ activates the tab to the right.
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
keys = {
{ key = '{', mods = 'ALT', action = act.ActivateTabRelative(-1) },
{ key = '}', mods = 'ALT', action = act.ActivateTabRelative(1) },
},
config.keys = {
{ key = '{', mods = 'ALT', action = act.ActivateTabRelative(-1) },
{ key = '}', mods = 'ALT', action = act.ActivateTabRelative(1) },
}
return config
```
See also [ActivateTabRelativeNoWrap](ActivateTabRelativeNoWrap.md)

10
docs/config/lua/keyassignment/ActivateTabRelativeNoWrap.md
View File

@ -14,13 +14,13 @@ but this one will not wrap around; for example, if the first tab is active
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
keys = {
{ key = '{', mods = 'ALT', action = act.ActivateTabRelativeNoWrap(-1) },
{ key = '}', mods = 'ALT', action = act.ActivateTabRelativeNoWrap(1) },
},
config.keys = {
{ key = '{', mods = 'ALT', action = act.ActivateTabRelativeNoWrap(-1) },
{ key = '}', mods = 'ALT', action = act.ActivateTabRelativeNoWrap(1) },
}
return config
```

9
docs/config/lua/keyassignment/ActivateWindow.md
View File

@ -15,20 +15,19 @@ Here's an example of setting up hotkeys to activate specific windows:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
local mykeys = {}
config.keys = {}
for i = 1, 8 do
-- CMD+ALT + number to activate that window
table.insert(mykeys, {
table.insert(config.keys, {
key = tostring(i),
mods = 'CMD|ALT',
action = act.ActivateWindow(i - 1),
})
end
return {
keys = mykeys,
}
return config
```

10
docs/config/lua/keyassignment/ActivateWindowRelative.md
View File

@ -16,13 +16,13 @@ windows:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
keys = {
{ key = 'r', mods = 'ALT', action = act.ActivateWindowRelative(1) },
{ key = 'e', mods = 'ALT', action = act.ActivateWindowRelative(-1) },
},
config.keys = {
{ key = 'r', mods = 'ALT', action = act.ActivateWindowRelative(1) },
{ key = 'e', mods = 'ALT', action = act.ActivateWindowRelative(-1) },
}
return config
```
See also [ActivateWindowRelativeNoWrap](ActivateWindowRelativeNoWrap.md),

24
docs/config/lua/keyassignment/ActivateWindowRelativeNoWrap.md
View File

@ -15,21 +15,21 @@ windows:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
keys = {
{
key = 'r',
mods = 'ALT',
action = act.ActivateWindowRelativeNoWrap(1),
},
{
key = 'e',
mods = 'ALT',
action = act.ActivateWindowRelativeNoWrap(-1),
},
config.keys = {
{
key = 'r',
mods = 'ALT',
action = act.ActivateWindowRelativeNoWrap(1),
},
{
key = 'e',
mods = 'ALT',
action = act.ActivateWindowRelativeNoWrap(-1),
},
}
return config
```
See also [ActivateWindowRelative](ActivateWindowRelative.md),

38
docs/config/lua/keyassignment/AdjustPaneSize.md
View File

@ -19,26 +19,26 @@ respectively.
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}
return {
leader = { key = 'a', mods = 'CTRL' },
keys = {
{
key = 'H',
mods = 'LEADER',
action = act.AdjustPaneSize { 'Left', 5 },
},
{
key = 'J',
mods = 'LEADER',
action = act.AdjustPaneSize { 'Down', 5 },
},
{ key = 'K', mods = 'LEADER', action = act.AdjustPaneSize { 'Up', 5 } },
{
key = 'L',
mods = 'LEADER',
action = act.AdjustPaneSize { 'Right', 5 },
},
config.leader = { key = 'a', mods = 'CTRL' }
config.keys = {
{
key = 'H',
mods = 'LEADER',
action = act.AdjustPaneSize { 'Left', 5 },
},
{
key = 'J',
mods = 'LEADER',
action = act.AdjustPaneSize { 'Down', 5 },
},
{ key = 'K', mods = 'LEADER', action = act.AdjustPaneSize { 'Up', 5 } },
{
key = 'L',
mods = 'LEADER',
action = act.AdjustPaneSize { 'Right', 5 },
},
}
return config
```

24
docs/config/lua/keyassignment/AttachDomain.md
View File

@ -19,21 +19,17 @@ entries with this action.
The example below shows how to bind a key to trigger attaching to an ssh domain:
```lua
local wezterm = require 'wezterm'
return {
ssh_domains = {
{
name = 'devhost',
remote_address = 'devhost.example.com',
},
config.ssh_domains = {
{
name = 'devhost',
remote_address = 'devhost.example.com',
},
keys = {
{
key = 'U',
mods = 'CTRL|SHIFT',
action = wezterm.action.AttachDomain 'devhost',
},
}
config.keys = {
{
key = 'U',
mods = 'CTRL|SHIFT',
action = wezterm.action.AttachDomain 'devhost',
},
}
```

25
docs/config/lua/keyassignment/CharSelect.md
View File

@ -42,22 +42,17 @@ This action is by default assigned to `CTRL-SHIFT-U` (`U` for `Unicode`).
The default assignment is equivalent to this config:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
-- Control the size of the font.
-- Uses the same font as window_frame.font
-- char_select_font_size = 18.0,
return {
-- Control the size of the font.
-- Uses the same font as window_frame.font
-- char_select_font_size = 18.0,
keys = {
{
key = 'u',
mods = 'SHIFT|CTRL',
action = act.CharSelect {
copy_on_select = true,
copy_to = 'ClipboardAndPrimarySelection',
},
config.keys = {
{
key = 'u',
mods = 'SHIFT|CTRL',
action = wezterm.action.CharSelect {
copy_on_select = true,
copy_to = 'ClipboardAndPrimarySelection',
},
},
}

50
docs/config/lua/keyassignment/ClearScrollback.md
View File

@ -11,32 +11,30 @@ Added a parameter that allows additionally clear the viewport:
local wezterm = require 'wezterm'
local act = wezterm.action
return {
keys = {
-- Clears only the scrollback and leaves the viewport intact.
-- You won't see a difference in what is on screen, you just won't
-- be able to scroll back until you've output more stuff on screen.
-- This is the default behavior.
{
key = 'K',
mods = 'CTRL|SHIFT',
action = act.ClearScrollback 'ScrollbackOnly',
},
-- Clears the scrollback and viewport leaving the prompt line the new first line.
{
key = 'K',
mods = 'CTRL|SHIFT',
action = act.ClearScrollback 'ScrollbackAndViewport',
},
-- Clears the scrollback and viewport, and then sends CTRL-L to ask the
-- shell to redraw its prompt
{
key = 'K',
mods = 'CTRL|SHIFT',
action = act.Multiple {
act.ClearScrollback 'ScrollbackAndViewport',
act.SendKey { key = 'L', mods = 'CTRL' },
},
config.keys = {
-- Clears only the scrollback and leaves the viewport intact.
-- You won't see a difference in what is on screen, you just won't
-- be able to scroll back until you've output more stuff on screen.
-- This is the default behavior.
{
key = 'K',
mods = 'CTRL|SHIFT',
action = act.ClearScrollback 'ScrollbackOnly',
},
-- Clears the scrollback and viewport leaving the prompt line the new first line.
{
key = 'K',
mods = 'CTRL|SHIFT',
action = act.ClearScrollback 'ScrollbackAndViewport',
},
-- Clears the scrollback and viewport, and then sends CTRL-L to ask the
-- shell to redraw its prompt
{
key = 'K',
mods = 'CTRL|SHIFT',
action = act.Multiple {
act.ClearScrollback 'ScrollbackAndViewport',
act.SendKey { key = 'L', mods = 'CTRL' },
},
},
}

34
docs/config/lua/keyassignment/ClearSelection.md
View File

@ -12,28 +12,20 @@ CTRL-C to the terminal when there is no selection:
local wezterm = require 'wezterm'
local act = wezterm.action
return {
keys = {
{
key = 'c',
mods = 'CTRL',
action = wezterm.action_callback(function(window, pane)
local has_selection = window:get_selection_text_for_pane(pane) ~= ''
if has_selection then
window:perform_action(
act.CopyTo 'ClipboardAndPrimarySelection',
pane
)
config.keys = {
{
key = 'c',
mods = 'CTRL',
action = wezterm.action_callback(function(window, pane)
local has_selection = window:get_selection_text_for_pane(pane) ~= ''
if has_selection then
window:perform_action(act.CopyTo 'ClipboardAndPrimarySelection', pane)
window:perform_action(act.ClearSelection, pane)
else
window:perform_action(
act.SendKey { key = 'c', mods = 'CTRL' },
pane
)
end
end),
},
window:perform_action(act.ClearSelection, pane)
else
window:perform_action(act.SendKey { key = 'c', mods = 'CTRL' }, pane)
end
end),
},
}
```

14
docs/config/lua/keyassignment/CloseCurrentPane.md
View File

@ -8,15 +8,11 @@ The act of closing a pane shuts down the PTY associated with the pane and
then kills the process associated with that pane.
```lua
local wezterm = require 'wezterm'
return {
keys = {
{
key = 'w',
mods = 'CMD',
action = wezterm.action.CloseCurrentPane { confirm = true },
},
config.keys = {
{
key = 'w',
mods = 'CMD',
action = wezterm.action.CloseCurrentPane { confirm = true },
},
}
```

12
docs/config/lua/keyassignment/CloseCurrentTab.md
View File

@ -4,13 +4,11 @@ Closes the current tab, terminating all contained panes. If that was the last
tab, closes that window. If that was the last window, wezterm terminates.
```lua
return {
keys = {
{
key = 'w',
mods = 'CMD',
action = wezterm.action.CloseCurrentTab { confirm = true },
},
config.keys = {
{
key = 'w',
mods = 'CMD',
action = wezterm.action.CloseCurrentTab { confirm = true },
},
}
```

22
docs/config/lua/keyassignment/CompleteSelection.md
View File

@ -11,19 +11,15 @@ which clipboard buffer the selection will populate; the copy action
is now equivalent to [CopyTo](CopyTo.md).
```lua
local wezterm = require 'wezterm'
return {
mouse_bindings = {
-- Change the default click behavior so that it only selects
-- text and doesn't open hyperlinks, and that it populates
-- the Clipboard rather the PrimarySelection which is part
-- of the default assignment for a left mouse click.
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'NONE',
action = wezterm.action.CompleteSelection 'Clipboard',
},
config.mouse_bindings = {
-- Change the default click behavior so that it only selects
-- text and doesn't open hyperlinks, and that it populates
-- the Clipboard rather the PrimarySelection which is part
-- of the default assignment for a left mouse click.
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'NONE',
action = wezterm.action.CompleteSelection 'Clipboard',
},
}
```

18
docs/config/lua/keyassignment/CompleteSelectionOrOpenLinkAtMouseCursor.md
View File

@ -12,17 +12,13 @@ which clipboard buffer the selection will populate. The copy action
is now equivalent to [CopyTo](CopyTo.md).
```lua
local wezterm = require 'wezterm'
return {
mouse_bindings = {
-- Change the default click behavior so that it populates
-- the Clipboard rather the PrimarySelection.
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'NONE',
action = wezterm.action.CompleteSelectionOrOpenLinkAtMouseCursor 'Clipboard',
},
config.mouse_bindings = {
-- Change the default click behavior so that it populates
-- the Clipboard rather the PrimarySelection.
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'NONE',
action = wezterm.action.CompleteSelectionOrOpenLinkAtMouseCursor 'Clipboard',
},
}
```

7
docs/config/lua/keyassignment/Copy.md
View File

@ -15,11 +15,8 @@ This action has been removed. Please use [CopyTo](CopyTo.md) instead.
```lua
local wezterm = require 'wezterm'
return {
keys = {
{ key = 'C', mods = 'CTRL', action = wezterm.action.Copy },
},
config.keys = {
{ key = 'C', mods = 'CTRL', action = wezterm.action.Copy },
}
```

14
docs/config/lua/keyassignment/CopyTo.md
View File

@ -9,15 +9,11 @@ Possible values for destination are:
* `ClipboardAndPrimarySelection` - Copy to both the clipboard and the primary selection.
```lua
local wezterm = require 'wezterm'
return {
keys = {
{
key = 'C',
mods = 'CTRL',
action = wezterm.action.CopyTo 'ClipboardAndPrimarySelection',
},
config.keys = {
{
key = 'C',
mods = 'CTRL',
action = wezterm.action.CopyTo 'ClipboardAndPrimarySelection',
},
}
```

8
docs/config/lua/keyassignment/DecreaseFontSize.md
View File

@ -3,12 +3,8 @@
Decreases the font size of the current window by 10%
```lua
local wezterm = require 'wezterm'
return {
keys = {
{ key = '-', mods = 'CTRL', action = wezterm.action.DecreaseFontSize },
},
config.keys = {
{ key = '-', mods = 'CTRL', action = wezterm.action.DecreaseFontSize },
}
```

38
docs/config/lua/keyassignment/DetachDomain.md
View File

@ -14,27 +14,25 @@ error log/debug overlay.
local wezterm = require 'wezterm'
local act = wezterm.action
return {
ssh_domains = {
{
name = 'devhost',
remote_address = 'devhost.example.com',
},
config.ssh_domains = {
{
name = 'devhost',
remote_address = 'devhost.example.com',
},
keys = {
{ key = 'U', mods = 'CTRL|SHIFT', action = act.AttachDomain 'devhost' },
-- Detaches the domain associated with the current pane
{
key = 'D',
mods = 'CTRL|SHIFT',
action = act.DetachDomain 'CurrentPaneDomain',
},
-- Detaches the "devhost" domain
{
key = 'E',
mods = 'CTRL|SHIFT',
action = act.DetachDomain { DomainName = 'devhost' },
},
}
config.keys = {
{ key = 'U', mods = 'CTRL|SHIFT', action = act.AttachDomain 'devhost' },
-- Detaches the domain associated with the current pane
{
key = 'D',
mods = 'CTRL|SHIFT',
action = act.DetachDomain 'CurrentPaneDomain',
},
-- Detaches the "devhost" domain
{
key = 'E',
mods = 'CTRL|SHIFT',
action = act.DetachDomain { DomainName = 'devhost' },
},
}
```

18
docs/config/lua/keyassignment/DisableDefaultAssignment.md
View File

@ -6,17 +6,13 @@ default assignments and cause the key press to be propagated through
to the tab for processing.
```lua
local wezterm = require 'wezterm'
return {
keys = {
-- Turn off the default CMD-m Hide action, allowing CMD-m to
-- be potentially recognized and handled by the tab
{
key = 'm',
mods = 'CMD',
action = wezterm.action.DisableDefaultAssignment,
},
config.keys = {
-- Turn off the default CMD-m Hide action, allowing CMD-m to
-- be potentially recognized and handled by the tab
{
key = 'm',
mods = 'CMD',
action = wezterm.action.DisableDefaultAssignment,
},
}
```

14
docs/config/lua/keyassignment/ExtendSelectionToMouseCursor.md
View File

@ -9,15 +9,11 @@ the scope of the selection.
The mode argument can also be `"Block"` to enable a rectangular block selection.
```lua
local wezterm = require 'wezterm'
return {
mouse_bindings = {
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'SHIFT',
action = wezterm.action.ExtendSelectionToMouseCursor 'Word',
},
config.mouse_bindings = {
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'SHIFT',
action = wezterm.action.ExtendSelectionToMouseCursor 'Word',
},
}
```

8
docs/config/lua/keyassignment/Hide.md
View File

@ -3,11 +3,7 @@
Hides (or minimizes, depending on the platform) the current window.
```lua
local wezterm = require 'wezterm'
return {
keys = {
{ key = 'h', mods = 'CMD', action = wezterm.action.Hide },
},
config.keys = {
{ key = 'h', mods = 'CMD', action = wezterm.action.Hide },
}
```

8
docs/config/lua/keyassignment/HideApplication.md
View File

@ -3,11 +3,7 @@
On macOS, hide the WezTerm application.
```lua
local wezterm = require 'wezterm'
return {
keys = {
{ key = 'h', mods = 'CMD', action = wezterm.action.HideApplication },
},
config.keys = {
{ key = 'h', mods = 'CMD', action = wezterm.action.HideApplication },
}
```

8
docs/config/lua/keyassignment/IncreaseFontSize.md
View File

@ -3,12 +3,8 @@
Increases the font size of the current window by 10%
```lua
local wezterm = require 'wezterm'
return {
keys = {
{ key = '=', mods = 'CTRL', action = wezterm.action.IncreaseFontSize },
},
config.keys = {
{ key = '=', mods = 'CTRL', action = wezterm.action.IncreaseFontSize },
}
```

10
docs/config/lua/keyassignment/MoveTab.md
View File

@ -6,20 +6,20 @@ from the left, and so on.
```lua
local wezterm = require 'wezterm'
local config = {}
config.keys = {}
local mykeys = {}
for i = 1, 8 do
-- CTRL+ALT + number to move to that position
table.insert(mykeys, {
table.insert(config.keys, {
key = tostring(i),
mods = 'CTRL|ALT',
action = wezterm.action.MoveTab(i - 1),
})
end
return {
keys = mykeys,
}
return config
```

9
docs/config/lua/keyassignment/MoveTabRelative.md
View File

@ -5,14 +5,11 @@ offset. eg: `-1` moves the tab to the left of the current tab, while `1` moves
the tab to the right.
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
return {
keys = {
{ key = '{', mods = 'SHIFT|ALT', action = act.MoveTabRelative(-1) },
{ key = '}', mods = 'SHIFT|ALT', action = act.MoveTabRelative(1) },
},
config.keys = {
{ key = '{', mods = 'SHIFT|ALT', action = act.MoveTabRelative(-1) },
{ key = '}', mods = 'SHIFT|ALT', action = act.MoveTabRelative(1) },
}
```

19
docs/config/lua/keyassignment/Multiple.md
View File

@ -8,19 +8,16 @@ want a single key press to trigger multiple actions.
The example below causes `LeftArrow` to effectively type `left`:
```lua
local wezterm = require 'wezterm'
local act = wezterm.action
return {
keys = {
{
key = 'LeftArrow',
action = act.Multiple {
act.SendKey { key = 'l' },
act.SendKey { key = 'e' },
act.SendKey { key = 'f' },
act.SendKey { key = 't' },
},
config.keys = {
{
key = 'LeftArrow',
action = act.Multiple {
act.SendKey { key = 'l' },
act.SendKey { key = 'e' },
act.SendKey { key = 'f' },
act.SendKey { key = 't' },
},
},
}

10
docs/config/lua/keyassignment/Nop.md
View File

@ -7,13 +7,9 @@ If instead of this you want the key presses to pass through to
the terminal, look at [DisableDefaultAssignment](DisableDefaultAssignment.md).
```lua
local wezterm = require 'wezterm'
return {
keys = {
-- Turn off any side effects from pressing CMD-m
{ key = 'm', mods = 'CMD', action = wezterm.action.Nop },
},
config.keys = {
-- Turn off any side effects from pressing CMD-m
{ key = 'm', mods = 'CMD', action = wezterm.action.Nop },
}
```

16
docs/config/lua/keyassignment/OpenLinkAtMouseCursor.md
View File

@ -4,16 +4,12 @@ If the current mouse cursor position is over a cell that contains
a hyperlink, this action causes that link to be opened.
```lua
local wezterm = require 'wezterm'
return {
mouse_bindings = {
-- Ctrl-click will open the link under the mouse cursor
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'CTRL',
action = wezterm.action.OpenLinkAtMouseCursor,
},
config.mouse_bindings = {
-- Ctrl-click will open the link under the mouse cursor
{
event = { Up = { streak = 1, button = 'Left' } },
mods = 'CTRL',
action = wezterm.action.OpenLinkAtMouseCursor,
},
}
```

40
docs/config/lua/keyassignment/PaneSelect.md
View File

@ -23,29 +23,27 @@ The selection alphabet defaults to the same value as [quick_select_alphabet](../
local wezterm = require 'wezterm'
local act = wezterm.action
return {
-- 36 is the default, but you can choose a different size.
-- Uses the same font as window_frame.font
-- pane_select_font_size=36,
-- 36 is the default, but you can choose a different size.
-- Uses the same font as window_frame.font
-- config.pane_select_font_size=36,
keys = {
-- activate pane selection mode with the default alphabet (labels are "a", "s", "d", "f" and so on)
{ key = '8', mods = 'CTRL', action = act.PaneSelect },
-- activate pane selection mode with numeric labels
{
key = '9',
mods = 'CTRL',
action = act.PaneSelect {
alphabet = '1234567890',
},
config.keys = {
-- activate pane selection mode with the default alphabet (labels are "a", "s", "d", "f" and so on)
{ key = '8', mods = 'CTRL', action = act.PaneSelect },
-- activate pane selection mode with numeric labels
{
key = '9',
mods = 'CTRL',
action = act.PaneSelect {
alphabet = '1234567890',
},
-- show the pane selection mode, but have it swap the active and selected panes
{
key = '0',
mods = 'CTRL',
action = act.PaneSelect {
mode = 'SwapWithActive',
},
},
-- show the pane selection mode, but have it swap the active and selected panes
{
key = '0',
mods = 'CTRL',
action = act.PaneSelect {
mode = 'SwapWithActive',
},
},
}

Some files were not shown because too many files have changed in this diff Show More