Tmux 2.8.X to 2.9.X migration

[garyayo]

This morning I updated tmux to 2.9 from 2.8.1 running on OSX 10.14.4 and I hit the following issues:

/Users/gary/.tmux.conf:123: invalid option: pane-border-fg
/Users/gary/.tmux.conf:124: invalid option: pane-active-border-fg

/Users/gary/.tmux.conf:141: invalid option: message-fg
/Users/gary/.tmux.conf:142: invalid option: message-bg
/Users/gary/.tmux.conf:143: invalid option: message-command-fg
/Users/gary/.tmux.conf:144: invalid option: message-command-bg

/Users/gary/.tmux.conf:147: invalid option: mode-bg
/Users/gary/.tmux.conf:148: invalid option: mode-fg

/Users/gary/.tmux.conf:155: invalid option: window-status-current-bg
/Users/gary/.tmux.conf:156: invalid option: window-status-current-fg
/Users/gary/.tmux.conf:157: invalid option: window-status-current-attr
/Users/gary/.tmux.conf:158: invalid option: window-status-bg
/Users/gary/.tmux.conf:159: invalid option: window-status-fg
/Users/gary/.tmux.conf:160: invalid option: window-status-attr

/Users/gary/.tmux.conf:164: invalid option: mode-attr
/Users/gary/.tmux.conf:165: invalid option: mode-fg
/Users/gary/.tmux.conf:166: invalid option: mode-bg

/Users/gary/.tmux.conf:171: invalid option: pane-border-bg
/Users/gary/.tmux.conf:172: invalid option: pane-border-fg
/Users/gary/.tmux.conf:173: invalid option: pane-active-border-bg
/Users/gary/.tmux.conf:174: invalid option: pane-active-border-fg

/Users/gary/.tmux.conf:183: invalid option: status-attr

/Users/gary/.tmux.conf:189: invalid option: window-status-current-fg
/Users/gary/.tmux.conf:190: invalid option: window-status-current-bg
/Users/gary/.tmux.conf:191: invalid option: window-status-current-attr

/Users/gary/.tmux.conf:194: invalid option: window-status-fg
/Users/gary/.tmux.conf:195: invalid option: window-status-bg
/Users/gary/.tmux.conf:196: invalid option: window-status-attr

/Users/gary/.tmux.conf:199: invalid option: window-status-bell-attr
/Users/gary/.tmux.conf:200: invalid option: window-status-bell-fg
/Users/gary/.tmux.conf:201: invalid option: window-status-bell-bg

/Users/gary/.tmux.conf:206: invalid option: message-attr
/Users/gary/.tmux.conf:207: invalid option: message-fg
/Users/gary/.tmux.conf:208: invalid option: message-bg

I was wondering if there was a 2.8 > 2.9 migration guide available to make this process a little easier?

Thanks

[nicm]

It's all the same issue, use -style instead. It's in the change log and the release announcement, what more do you need?

[nicm]

I would probably not be difficult for someone to write a couple of lines of perl or python or even sh to change configs, we could put it in the FAQ...

[garyayo]

@nicm I'm sorry man, I just don't understand what you expect us to do... You make a rather impactful change and expect us to figure it out for ourselves? I love TMUX and use it everyday but why does it feel like you're kicking dirt in our faces?

Currently I'm digging through the documentation to see how I can migrate over but its an agonizing trial and error experience. I see that for the most part the syntax has changed to -style fg=<whatever> but I'm still not seeing how to utilize -attr and that's just the start. Is there any sort of clear cut guide stating that XYZ option has changed to ABC?

[nicm]

I don't think that's fair. Both the CHANGES file and the release announcement say to replace -fg/-bg/-attr options with -style options, there is a large section in the manual about STYLES - with a couple of examples - plus every individual option is documented. The -attr/-fg/-bg form of these options have been undocumented and not displayed by show-options for more than 5 years.

You didn't come here saying "I read the manual and I tried to change X and Y into Z and it didn't work", you just came and pasted a bunch of 100 virtually identical errors into an issue.

[garyayo]

But I did look through the changes... I understand that these changes are dead obvious to you but its not as clear to some of us.. I even tried to search for migration guides and any other documentation that could help. I pasted a bunch of 100 virtually identical errors into an issue in the hope to receive some constructive feedback and guidance. I was wrong and I'm sorry.

[nicm]

These are the -style options:

             message-command-style style
             message-style style
             mode-style style
             pane-active-border-style style
             pane-border-style style
             status-left-style style
             status-right-style style
             status-style style
             window-active-style style
             window-status-activity-style style
             window-status-bell-style style
             window-status-current-style style
             window-status-last-style style
             window-status-style style
             window-style style

The form is exactly the same, it is just one option instead of three:

set -g mode-style bg=red,fg=green,blink

[nicm]

I've added a section to the FAQ https://github.com/tmux/tmux/wiki/FAQ#how-do-i-translate--fg--bg-and--attr-options-into--style-options.

[garyayo]

Thank you @nicm, very much appreciated. ❤️

[LandonSchropp]

I would also appreciate it if the changed variables were specifically listed in the changelog so they could be easily searched. When my install broke this morning, my first step was to try and search the changelog for window-status-activity-attr, which didn't show up anywhere.

[FernandoBasso]

Here's a diff of what I had to change to upgrade the config to be Tmux 2.9 compliant. It might help too.

https://gitlab.com/fernandobasso/dotfiles/commit/af2c0ac59b93b318575367f0313ad1ca0627a6ba

[tbutts]

As was suggested, I made a python2/3 script to update a tmux.conf file to use the v1.9+ -style options. Find it here (instructions and caveats included): https://gist.github.com/tbutts/6abf7fb5b948c066bf180922fb37adcf

The config migration script should work for most folks. I've tried it on the configs being referenced to this issue, and the results are good. In some cases, the updates people are making manually are actually incorrect and the script is less error-prone. Just to be clear according to the tmux docs, if you set the same option repeatedly, the last one takes effect. The -style option grouping multiple settings together makes this more apparent. If your config looks like:

set -g status-style bg=green,fg=magenta,bold
...
set -g status-style bg=blue

Then the second status-style line is all that is applied. Your status bar will have a background of blue and then default for foreground and all attrs (so no bold in this case). If the set commands were rewritten with the -ga flagset, then that would extend the settings from the previous lines instead of overwriting them.

Just read the tmux docs, it's all there.

I'll admit my tmux.conf has been a mess of copy+paste for years before the v2.9 removal caused the start-up errors. It feels like with how devs share dotfiles around, it's been easy for me to build up cruft and never touch my conf file because it just works. That's a shame, because I'm now seeing many nice new features tmux has added over time that I could have been using.

[garyayo]

Thanks @tbutts for taking the time to put that together. That's really kind of you.

[scbunn]

I wish this ticket was not closed as I spent the last several hours trying to do the same thing. This ticket should be highlighted somewhere.

[chakrit]

@nicm The upgrade came to me as a surprise mostly because I set homebrew (where I obtain tmux builds) to auto-upgrade every week or so. So I had these errors popping up on the start of day (and that's when you have a lot of work issues to fix and the last thing you want is your dev-env breaking) so I had no chance to go through the release notes or changelog to prepare myself.

But perfectly understand that this is fault on my part and not trying to blame you or tmux or anything and partly because homebrew (and other pkg managers) is just too easy to use. You just brew upgrade && brew cleanup and forget about it. Also, just to note, searching for "tmux 2.9 upgrade" yield this issue as the first hit and the CHANGES file as the second hit for me. The CHANGES file have no mention of the status-attr option changes (which is what is breaking in my tmux.conf) so it was a bit frustrating there.

Just want to add a data point here.

To fix the above I'd like to suggest a version directive in the config. This can help give proper warnings and pointers to the new users. For example, this could have been the tmux start-up message:

$ tmux
WARNING! - We detected that your config file is from 2.8.x series,
however the current version is 2.9

You may encounter some breaking changes.
Be sure to check the changelog: https://github.com/tmux/tmux/blob/master/CHANGES

(also willing to pitch in code, but my C knowledge is quite limited)

[adong]

Why is this a breaking change instead of being backward compatible?

[drakkhen]

This should have been a deprecation warning before making it a breaking change.