Clarify when #!important is needed

[quicknir]

The .conf.local file says:

# if you don't want Oh my tmux! to alter a binding, use #!important

But it's not very clear just from this sentence when it's actually needed. As an example, I have this in my config:

# Rebind source tmux conf from r to R; copied from .tmux.conf
bind R run "sh -c '\"\$TMUX_PROGRAM\" \${TMUX_SOCKET:+-S \"\$TMUX_SOCKET\"} source \"\$TMUX_CONF\"'" \; display "#{TMUX_CONF} sourced"
bind r command-prompt "rename-window '%%'"

I'm changing the <prefix>r binding, so one might expect that #!important is needed, but it works just fine without it.

[gpakosz]

Hello @quicknir 👋

You use #!important when you don't want Oh my tmux! to change a binding that you specify.

This applies to everything that can be altered by specifying a tmux_conf_xxx= variable, e.g.

• set -g default-terminal
• bindings
• ...

The way it works is

• tmux sources the .conf file
• which in turn sources the .conf.local customization file
• then Oh my tmux! proceeds with changing tmux's configuration based on tmux_conf_xxx= variables
  • which can overwrite settings and bindings set by users from the .conf.local file
• finally Oh my tmux! proceeds with applying set and bind commands that are marked as #!important from the .conf.local customization file

In your case, changing <prefix> + r doesn't need to be marked as #!important as it's never altered by a tmux_conf_xxx= variable.

[quicknir]

Let me see if I understand - .conf first sets up its own keybindings (the defaults). Then it sources the user's .conf.local, which applies any bindings there - and also sets certain tmux_conf variables. .conf then proceeds to use those variables, some of which can affect further bindings. So user keybinds override those initial .conf keybinds, but are in turn overridden by keybinds determined by tmux_conf variables?

Rather than #important, wouldn't it be better to just encourage the user to change the tmux_conf setting that had caused the binding to be overriden? Well, I guess it's more complicated than that.

I would suggest explaining what you just explained to me, in the comments in the .conf.local. It might also be helpful to note which actual options might need you to set #important, and for which bindings, if you changed them. Like, it seems to maybe that tmux_conf_preserve_stock_bindings is such an option; I don't see too many others?

Without that, it's not very obvious to users which bindings are altered by tmux_conf or not.

Also, let me say thanks for all your hard work, and actually responding to this issue. This repo has definitely been a game changer for my use of tmux!

[gpakosz]

Rather than #important, wouldn't it be better to just encourage the user to change the tmux_conf setting that had caused the binding to be overriden? Well, I guess it's more complicated than that.

It's more complicated than that.
There are situations where you want Oh my tmux! to change/alter bindings, e.g. you want tmux_conf_new_window_retain_current_path=true and you also want to define a custom new-window binding that doesn't retain the current path.

Another situation is when Oh my tmux! detects that tmux-256color is available on a system, but for some reason the terminfo description os broken. This happens on some systems, in which case users can use #!important to force set -g default-terminal "screen-256color" instead of troubleshooting their system.

I would suggest explaining what you just explained to me, in the comments in the .conf.local. It might also be helpful to note which actual options might need you to set #important, and for which bindings, if you changed them. Like, it seems to maybe that tmux_conf_preserve_stock_bindings is such an option; I don't see too many others?

Well I don't know if it's worth maintaining such a list.
For tmux_conf_preserve_stock_bindings it's again a bit different:

• Some bindings are set in .tmux.conf
• .tmux.conf sources .tmux.conf.local
  • Which allows users to set tmux_conf_... variables, as well as anything that could go in a configuration (set, bind, ...)
• .tmux.conf then calls into _apply_configuration()
• Which in turns calls _apply_bindings()
  • Store current bindings to a temporary file
  • If tmux_conf_preserve_stock_bindings is true, spawn an ephemeral tmux instance, list keys and append that to the temporary file
  • Apply modifications to the temporary file based on tmux_conf_new_window_retain_current_path, tmux_conf_new_pane_retain_current_path, tmux_conf_new_window_reconnect_ssh, tmux_conf_new_session_prompt, tmux_conf_new_session_retain_current_path, tmux_conf_copy_to_os_clipboard
  • Extract set and bind commands marked with #!important from .tmux.conf.local and append them to the temporary file
  • Finally source the temporary file

I would say that all these details

• May/will change over time
• Are useless to 99% of Oh my tmux! users

[gpakosz]

All in all,

• tmux_conf_preserve_stock_bindings is about deciding which bindings do what: e.g. which bindings create a new window
• tmux_conf_new_window_retain_current_path is about listing all bindings that end up calling new-window and modifying them to inject or remove -c '#{pane_current_path}'
• #!important is about making sure set and bind commands will be evaluated verbatim, independently of everything else that have/could happen

[quicknir]

Okay, all this is more than fair. I see there's a lot of complexity here. Only last thing I might suggest - to add a one liner to the explanation of #!important, linking to this issue. You've already written up a lot explaining what's going on after all, this is quite valuable information that might help someone debug their config and figure out if #!important is the answer or not. I'll probably add said one liner in my fork. Thank you for your help!