OS X Byobu Vertical Split

Chris Jeon picture Chris Jeon · Oct 3, 2014 · Viewed 22.5k times · Source

I'm currently on OS X using iTerm2 and byobu, and I can't figure out how to split my screen vertically on OS X. On Linux, I can split my screen vertically with Ctrl+F2, but on OSX, that doesn't work, thanks to Apple's different keyboard.

I Googled all around for the solution, and I can't figure this out. I can split my screen horizontally with Shift+F2, but I need to be able to split vertically. Has anyone figured out how to get byobu's keyboard bindings to work well with Apple computers?

Thanks in advance.

Answer

MangoHands picture MangoHands · Oct 20, 2014

Looks like there's on open bug on this issue.

I was able to configure iTerm2 to use byobu locally on OS X as well as remotely over ssh on an Ubuntu 14.04 server.

Using:

  • OS X version: 10.9.5 Build 13F34
  • iTerm2 version: Build 1.0.0.20140629

First, in your OS X system preferences, edit your keyboard settings and remove or change any shortcut settings that may conflict with byobu (i.e. Ctrl + F1-F12).

Option 1: Workaround using escape sequences

Here's a workaround that will work without adding full functionality to the FN keys. This will allow you to split windows vertically using the byobu escape key:

  1. Start byobu.

  2. Set your desired Ctrl-A behavior by running: byobu-ctrl-a. I chose to go with Emacs-mode.

  3. Run byobu-config and choose or change your escape sequence. I went with the new default Ctrl + S. The F12 key is also an escape sequence

  4. Now you can issue a command with your escape sequence. Try F12 then % or Ctrl + s then % to split a window vertically. For a full list of commands, try Ctrl + s then ? or F12 then ?.

Option 2: Setting iTerm2 key mappings to fully use all FN keys.

You can add some key mappings to your iTerm2 profile to get the CTRL, ALT, SHIFT, and FN keys to work with byobu. This is tedious, but I went through the exercise and it seems to work. I don't think there's an automated way to save these key mappings with iTerm2.

  1. Open iTerm2 preference and select Profiles.
  2. Choose the profile you'd like to use.
  3. Open the Terminal pane and under "Report terminal type" choose "linux".
  4. Open the Keys pane and manually add the following key bindings. Here's an example how to add one key binding:

    • Click the '+' icon.
    • Enter the keyboard shortcut being mapped in the first field. Example: CTRL + F2
    • Select "Send Escape Sequence" in the Action field.
    • Enter the characters in the third field. Example: [1;5Q

You can determine the control characters for any key sequence not listed here by referring to the tmux source code.

Repeat this for all of these mappings to make the corresponding byobu command work:

  • CTRL + F2 : [1;5Q
  • CTRL + SHIFT + F2 : [1;6Q
  • ALT + LEFT : [1;3D
  • ALT + RIGHT : [1;3C
  • ALT + UP : [1;3A
  • ALT + DOWN : [1;3B
  • CTRL + F3 : [1;5R
  • CTRL + F4 : [1;5S
  • CTRL + SHIFT + F3 : [1;6R
  • CTRL + SHIFT + F4 : [1;6S
  • SHIFT + ALT + LEFT : [1;4D
  • SHIFT + ALT + RIGHT : [1;4C
  • SHIFT + ALT + UP : [1;4A
  • SHIFT + ALT + DOWN : [1;4B
  • CTRL + F5 : [15;5~
  • CTRL + SHIFT + F5 : [15;6~
  • ALT + F6 : [17;3~
  • CTRL + F6 : [17;5~
  • ALT + PPAGE : [5;3~
  • ALT + NPAGE : [6;3~
  • CTRL + F8 : [19;5~
  • ALT + SHIFT + F8 : [19;4~
  • CTRL + SHIFT + F8 : [19;6~
  • CTRL + F9 : [20;5~
  • ALT + F11 : [23;3~
  • CTRL + F11 : [23;5~
  • ALT + F12 : [24;3~
  • CTRL + F12 : [24;5~
  • ALT + INS: [2;3~

Summary

To get things to work we needed to:

  • Remove conflicts with OS X keyboard shortcuts.
  • Edit the terminal key mappings to send the correct escape sequences when using function keys.
  • Set the iTerm2 terminal type to "Linux", which sets the TERM environmental variable to be "linux". Byobu and/or Tmux seemed to be sensitive to this.

Some other references on escape sequences: SO link and xterm-keys.c


Default directory for new windows and panes

It looks like there are some difference in tmux window default directory between tmux 1.8 and tmux 1.9 (Src, Src, Src). If you are using byobu with tmux 1.9 you can try adding this to your ~/.byobu/keybindings.tmux file so that when you create new windows or vertical/horizontal splits that they open in the same directory as the current pane:

unbind-key -n F2
bind-key -n F2 display-panes \; new-window -c "#{pane_current_path}" -n -
unbind-key -n C-F2
bind-key -n C-F2 display-panes \; split-window -hc "#{pane_current_path}"
unbind-key -n  S-F2
bind-key -n S-F2 display-panes \; split-window -vc "#{pane_current_path}"
unbind-key %
bind-key % display-panes \; split-window -hc "#{pane_current_path}"
unbind-key |
bind-key | display-panes \; split-window -vc "#{pane_current_path}"

Press F5 to reload settings.