mirror of
https://github.com/wez/wezterm.git
synced 2024-08-17 18:20:32 +03:00
117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
|
# Troubleshooting
|
||
|
|
||
|
## Review logs/error messages
|
||
|
|
||
|
If things aren't working out, there may be an issue printed in the logs.
|
||
|
Read on to learn more about how to see those logs.
|
||
|
|
||
|
### Debug Overlay
|
||
|
|
||
|
By default, pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd> will activate
|
||
|
the debug overlay and allow you to review the most recently logged issues.
|
||
|
It also gives you access to a Lua REPL for evaluating built-in lua functions.
|
||
|
|
||
|
See [ShowDebugOverlay](config/lua/keyassignment/ShowDebugOverlay.md) for more
|
||
|
information on this key assignment.
|
||
|
|
||
|
### Log Files
|
||
|
|
||
|
You can find log files in `$XDG_RUNTIME_DIR/wezterm` on unix systems,
|
||
|
or `$HOME/.local/share/wezterm` on macOS and Windows systems.
|
||
|
|
||
|
### Increasing Log Verbosity
|
||
|
|
||
|
The `WEZTERM_LOG` environment variable can be used to adjust the level
|
||
|
of logging for different modules within wezterm.
|
||
|
|
||
|
To see maximum verbosity, you can start wezterm like this:
|
||
|
|
||
|
```
|
||
|
WEZTERM_LOG=debug wezterm
|
||
|
```
|
||
|
|
||
|
to see debug level logs for everything on stdout.
|
||
|
|
||
|
On Windows systems you'll usually need to set the environment variable separately:
|
||
|
|
||
|
Using `cmd.exe`:
|
||
|
|
||
|
```
|
||
|
C:\> set WEZTERM_LOG=debug
|
||
|
C:\> wezterm
|
||
|
```
|
||
|
|
||
|
Using powershell:
|
||
|
|
||
|
```
|
||
|
PS C:\> $env:WEZTERM_LOG="debug"
|
||
|
PS C:\> wezterm
|
||
|
```
|
||
|
|
||
|
Each log line will include the module name, which is a colon separated
|
||
|
namespace; in the output below the modules are `config`,
|
||
|
`wezterm_gui::frontend`, `wezterm_font::ftwrap` and `wezterm_gui::termwindow`:
|
||
|
|
||
|
```
|
||
|
10:29:24.451 DEBUG config > Reloaded configuration! generation=2
|
||
|
10:29:24.452 DEBUG wezterm_gui::frontend > workspace is default, fixup windows
|
||
|
10:29:24.459 DEBUG wezterm_font::ftwrap > set_char_size computing 12 dpi=124 (pixel height=20.666666666666668)
|
||
|
10:29:24.461 DEBUG wezterm_font::ftwrap > set_char_size computing 12 dpi=124 (pixel height=20.666666666666668)
|
||
|
10:29:24.494 DEBUG wezterm_gui::termwindow > FocusChanged(true)
|
||
|
10:29:24.495 DEBUG wezterm_gui::termwindow > FocusChanged(false)
|
||
|
```
|
||
|
|
||
|
Those modules generally match up to directories and file names within the
|
||
|
wezterm source code, or to external modules that wezterm depends upon.
|
||
|
|
||
|
You can set a more restrictive filter to focus in on just the things you want.
|
||
|
For example, if you wanted to debug only configuration related things you might
|
||
|
set:
|
||
|
|
||
|
```
|
||
|
WEZTERM_LOG=config=debug,info
|
||
|
```
|
||
|
|
||
|
which says:
|
||
|
|
||
|
* log `config` at `debug` level
|
||
|
* everything else at `info` level
|
||
|
|
||
|
You can add more comma-separated items:
|
||
|
|
||
|
```
|
||
|
WEZTERM_LOG=config=debug,wezterm_font=debug,info
|
||
|
```
|
||
|
|
||
|
See Rust's [env_logger
|
||
|
documentation](https://docs.rs/env_logger/latest/env_logger/#enabling-logging)
|
||
|
for more details on the syntax/possibilities.
|
||
|
|
||
|
## Debugging Keyboard Related issues
|
||
|
|
||
|
Turn on [debug_key_events](config/lua/config/debug_key_events.md) to log
|
||
|
information about key presses.
|
||
|
|
||
|
Use [wezterm show-keys](cli/show-keys.md) or `wezterm show-keys --lua` to show
|
||
|
the effective set of key and mouse assignments defined by your config.
|
||
|
|
||
|
Consider changing [use_ime](config/lua/config/use_ime.md) to see that is
|
||
|
influencing your keyboard usage.
|
||
|
|
||
|
Double check to see if you have some system level utility/software that might
|
||
|
be intercepting or changing the behavior of a keyboard shortcut that you're
|
||
|
trying to use.
|
||
|
|
||
|
## Debugging Font Display
|
||
|
|
||
|
Use `wezterm ls-fonts` to explain which fonts will be used for different styles
|
||
|
of text.
|
||
|
|
||
|
Use `wezterm ls-fonts --list-system` to get a list of fonts available on your
|
||
|
system, in a form that you can use in your config file.
|
||
|
|
||
|
Use `wezterm ls-fonts --text foo` to explain how wezterm will render the text
|
||
|
`foo`, and `wezterm ls-fonts --text foo --rasterize-ascii` to show an ascii art
|
||
|
rendition of that text.
|
||
|
|