Provide configuration examples

[rapha8l]

Hi,

A configuration example would be nice, and maybe some other examples like scripts
Thanks

Raphael

[alexherbo2]

• https://github.com/alexherbo2/configuration/blob/master/config/wezterm/wezterm.lua
• https://github.com/bew/dotfiles/blob/main/gui/wezterm/wezterm.lua

[wez]

I spent a lot of time on the examples throughout the docs: https://wezfurlong.org/wezterm/
What sort of things were you looking for? Perhaps we can do something to make it easier to find?

[rapha8l]

I saw the doc, and it's clear, though a configuration file filled would be more easy to access immediatly

[bew]

For config example, you could also find all configs on github:
https://github.com/search?l=&q=filename%3Awezterm.lua&type=code

[rapha8l]

Sure, but it's not exactly the same :)

[bjornlll]

Agree. Was looking for the same. A few pre-filled configuration for common common user personas would be helpful: E.g. Mac with retina display => Config file pre-configured with font ligatures + font settings that suit a high-DPI display.

[wez]

#628 is a discussion thread that was just started that shows screenshots and configs; it currently just has a single example, but I'll see if I can persuade some folks to share their configs there also.

[bjornlll]

Great, @wez. Thanks!

[Trollwut]

Could it be an option to provide a default configuration in the user directory?

The content would be any config option with a description what it does, default is being shown, but the whole thing is commented.

Other terminals do provide it like that and I find this very accessible. As the configs are commented out, it wouldn't interfere with updates - except if the user explicitely wants to have other settings.

[jwiede]

I agree with Trollwut, having wezterm create default configuration on first launch would be more "common" to how other apps like kitty, etc. handle the situation. The default cnfig files don't set anything, but have all the major options described in commented-out sections. I find that incredibly useful, versus having to dig around repeatedly as you work through "initial config".

[azgarcia]

What do I need to put in my wezterm.lua to get a git bash experience on a windows computer? The clink is not working

[wez]

What do I need to put in my wezterm.lua to get a git bash experience on a windows computer? The clink is not working

@azgarcia Please make your own separate issue!

[wez]

My thoughts on providing a config file with commented out stuff are:

• The commented out content is not testable/verifiable so it tends towards being broken over time
• Because it isn't the actual code or the actual documentation, it will tend to drift from those primary sources and also tend to be broken over time
• It captures the state of your initial wezterm install and will never be updated to match more recent versions of wezterm, so it will also tend towards stale over time
• for complex software you're talking about a really big blob of commented text with no way to navigate it
• commented content cannot be syntax highlighted or styled, so you end up with the worst presentation of information possible

I really don't want to have a mode that deposits a config file like that.

I would much rather capture from those that are asking about this what the most common things are that they want to configure and see if we can have a better guided initial experience to help them configure those.

[rapha8l]

If not providing a directly used config file, there could be something like a /usr/share/wezterm/example

[follower]

An alternative approach that might address some of the concerns raised could be:

• Programmatically generate a config file that contains the current defaults (not commented out) with docs extracted from code (e.g. via here).
• Perhaps provide a command option to generate the config file for the current default and (if config not already found) offer to write it to the standard location--or some other location if a config exists to enable manual diffing.
• (Maybe (automatically?) generate a version-named default config file in ~/.local/share/wezterm/ or equivalent to enable easy diff-ing to catch up with what's changed with each installed version.)

Edit: Added link to defaults in code, which I couldn't find before.

[camilaac]

I spent a lot of time on the examples throughout the docs: https://wezfurlong.org/wezterm/ What sort of things were you looking for? Perhaps we can do something to make it easier to find?

The documentation is very nice, just a small detail confused me: everything is inside a "return" statement.

I don't know rust or lua, but I expected something like https://github.com/lefcha/imapfilter/blob/38f5f428c43df6e90b82e278e260bd8109443d30/samples/config.lua . The "return" statements puzzled me so I looked elsewhere for configuration examples, just to find the "return" was part of the configuration syntax.

Perhaps it's obvious, but it took me a while, if a wezterm.lua was provided it would save me and other dummies a lot of time.

[eugenesvk]

I would much rather capture from those that are asking about this what the most common things are that they want to configure and see if we can have a better guided initial experience to help them configure those.

Well, this also limits discovery (what if you have this great unique setting, but I just don't know about it yet since it's not present in other terminals?), though it's also fine if you don't want include everything in one file, you can have an "advanced" file with all the extra commented out commands, and instructions in the main config on how to load it

Though in general it's easier to read through the properly commented "blob", where I can see the effects immediately:

• open an Editor and Wez side-by-side
• change the value or uncomment a config
• save the file
• (profit :)) see the effect immediately (don't even need to restart it, which is great!)

rather than jumping back and forth between terminal/editor/browser copying&pasting to achieve the same
(no HTML beauty can beat the benefits of this immediate feedback, and currently docs are not dense enough, why do I have to click on every single font suboption to see how to use it, in the default file it would be just a few extra commented out lines that convey this information much better)

So I'd also suggest creating a new config file with defaults uncommented and other options commented out.
Something like (without 3 lines of comments per setting, an editor can word-wrap at user's if more details are needed) (defaults are made up)

local wezterm = require 'wezterm';

return {
  -- option	= value	, [default] comment

  -- Fonts
  font     	= wezterm.font("JetBrains Mono")                             	, -- [JetBrains Mono]
  -- font  	= wezterm.font("JetBrains Mono", {weight="Bold",italic=true})	, -- [JetBrains Mono] Name with parameters
  font_size	= 12.0                                                       	, -- [12.0]

  -- Colors
  color_scheme     	= "nord"   	, -- full list @ wezfurlong.org/wezterm/colorschemes/index.html
  colors           	= {        	  -- color_scheme takes precedence over these
    foreground     	= "silver" 	, -- [silver] The default text color
    background     	= "black"  	, -- [black]  The default background color
    cursor_bg      	= "#52ad70"	, -- [#52ad70] Overrides the cell background color when the current cell is occupied by the cursor and the cursor style is set to Block
    cursor_fg      	= "black"  	, -- [black]   Overrides the text color when the current cell is occupied by the cursor
    cursor_border  	= "#52ad70"	, -- [#52ad70] Specifies the border color of the cursor when the cursor style is set to Block, of the color of the vertical or horizontal bar when the cursor style is set to Bar or Underline.
    selection_fg   	= "black"  	, -- [black]   The foreground color of selected text
    selection_bg   	= "#fffacd"	, -- [#fffacd] The background color of selected text
    scrollbar_thumb	= "#222222"	, -- [#222222] The color of the scrollbar "thumb"; the portion that represents the current viewport
    split          	= "#444444"	, -- [#444444] The color of the split lines between panes
  --   ansi        	= {"black", "maroon", "green", "olive", "navy", "purple", "teal", "silver"},
  --   brights     	= {"grey", "red", "lime", "yellow", "blue", "fuchsia", "aqua", "white"},
  --   indexed     	= {[136]="#af8700"} , -- Arbitrary colors of the palette in the range from 16 to 255
  },

  -- Appearance
  window_background_opacity   	= 0.9  	, -- [1.0] alpha channel value with floating point numbers in the range 0.0 (meaning completely translucent/transparent) through to 1.0 (meaning completely opaque)
  enable_tab_bar              	= false	, -- [true]
  hide_tab_bar_if_only_one_tab	= false	, -- [false] hide the tab bar when there is only a single tab in the window
}

[CGMossa]

I'm trying to setup wezterm. I'm not a native shell user, and I just want to get going.. a default lua file that I can tinker with would help. I don't know lua either. ...

[bew]

Idea:
Add a wezterm cli option to show all available options, with one line documentation (?) and its current value (not sure yet how to display mouse/key bindings.. maybe a kind of table?).
The output should not be in Lua format to avoid people copy/pasting everything in a file, but with enough information (and a doc link for more info?) for people to see them and start tinkering.
Followed by a link to https://wezfurlong.org/wezterm/config/files.html to help people start their config.
That doc could also have a few links to Lua's documentation? And link to a small introduction to Lua?

To further avoid people from copy/pasting all default values of a given wezterm version (which is your main 'fear' @wez IIRC), we could make wezterm give a (friendly) warning when an option is set to its default value saying they should remove the option from their config.

[eugenesvk]

copy/pasting everything in a file, but with enough information (and a doc link for more info?) for people to see them and start tinkering.

you start tinkering BY "copy/pasting everything in a file" and changing values to observe the effect

The 'fear of defaults' is alleviated by commenting out all the values, not by making them uncopypasteable

[MiSawa]

The doc is excellent, but it would be even nicer if it had a configuration (or maybe just the keybind) example that results in similar to the default of tmux / screen, since I think a lot of people tries to migrate from them and spend some time to figure out how to make muscle-memoried keybindings work.

[tdensmore]

https://github.com/search?l=&q=filename%3Awezterm.lua&type=code

Honestly it could be testable and verifiable if during definition of done (or the release process) a working configuration with all working configurations was generated / used. The test case could be "Wexterm starts correctly with this config file". Then, Wezterm on initial startup could merely write a copy of this commented out file to the user's config directory. Sounds like a win / win. I will even volunteer to help maintain the file.