38

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.

Chris Jeon
  • 1,093
  • 1
  • 11
  • 18
  • Why is is such a pain...couldn't there just be some workaround like command-line split or change the default keymap? – addlistener Jan 11 '16 at 10:38
  • 1
    Byobu broke again on El Capitan... so I just gave up and went tmux with custom config. It works fine. – Chris Jeon Jan 12 '16 at 13:40

1 Answers1

77

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.

Community
  • 1
  • 1
MangoHands
  • 1,141
  • 9
  • 11
  • Cool, well, I decided to just do Ctrl+a+% to split things vertically. One more question, when you open a new tab with Ctrl+a, the new window always seems to open in the directory when byobu was first open. In Linux, new windows open in previous window's directory. Is there a way to fix it so that new windows in byobu open in previously opened window's directory? – Chris Jeon Oct 21 '14 at 14:10
  • Here's another key mapping I had to add to get copying between splits to work (following instructions from [here](http://stackoverflow.com/questions/25923952/how-to-copy-from-one-split-and-paste-in-another-in-byobu) and [here](http://linuxcommand.org/lc3_adv_termmux.php) ): - ALT + INS: `[2;3~` – MangoHands Oct 23 '14 at 18:56
  • Chris - this is a good question. I did some digging and it seems like byobu new windows are set to the directory of the current pane when your backend is tmux 1.8. However the new version tmux 1.9 breaks this behavior. This might help: https://coderwall.com/p/tjo3ig – MangoHands Oct 24 '14 at 14:55
  • done. thanks for your help. one more question, I'm assuming you're on OSX? On OS X, I noticed that the option key in the terminal is used to skip words. So, Option+Left will skip word to the left and Option+Right to the right. In byobu, the Option+Left/Right will switch the windows open to the next window. Is there a way to swap Option and Command key in the byobu keybindings config, so that I can use Option to skip words? – Chris Jeon Oct 24 '14 at 21:19
  • Yes I'm on OS X. From what I've read it looks like you cannot bind a tmux command to the Mac Command key. However, there are several keyboard shortcuts mapped to "next-window" and "previous-window" (try `tmux list-keys | grep -'next-window'` for a full listing). If you want to bind a different key sequence to next-window and previous-window just edit the ~/.byobu/keybindings.tmux as before. Don't be scared to play around and edit this file! Just backup up a copy of the original so you can always restore it if you screw things up :-) – MangoHands Oct 26 '14 at 18:27
  • So you can't bind keys to the Command key at all? Well, this just makes me want to return this laptop and go back to linux. – Chris Jeon Oct 27 '14 at 13:47
  • I think this might be a limitation of iTerm and not OS X. – MangoHands Oct 28 '14 at 14:28
  • Can't get how to input PPAGE, NPAGE and INS on my keyboard. PPAGE = Previous Page = Page Down = Fn + Down? – Anton Rudeshko Dec 25 '14 at 09:02
  • I am still not able to use Shift+F2 keybinding. Any hints? – nopper Mar 26 '15 at 19:58
  • @nopper Shift+F2 is `[1;2Q`. I added a comment in the main answer describing how to determine these key codes. – MangoHands Mar 27 '15 at 21:04
  • I left the terminal type at "xterm-256color" and found no problems with tmux (2.1) or byobu (5.101). Doing this, all the arrow-related commands worked out of the box. F2, F3 and F4 had to be binded manually, and so did all modified Fn keys, except for shift, which was already set up. – Martín Valdés de León Apr 03 '16 at 03:46
  • To switch between split panes use `F12` then `Tab` (if `Shift` + `F4` doesn't work). (Or in place of `F12` whatever your escape sequence is - `ctrl`+`A` / `ctrl`+`S` etc) – Chris Apr 04 '16 at 10:16
  • To split horizontally `F12` -> `|`. To switch between panes you can also use `F12` -> `o` and `F12` -> `;`. – Chris Apr 04 '16 at 10:34
  • Awesome! I potentially useful note is that I thought I could get away with not setting TERM=linux, but then it turns out that raw F-key presses wouldn't work. So I found that both that plus the manual mapping key mappings were required. – nedned Dec 06 '18 at 08:22
  • It seems that in iTerm2's preferences for profile's key, there is a preset named "xterm Defaults" that already contains many of these bindings. – dodecaplex Aug 21 '20 at 08:11
  • This iTerm2 profile .json file works out of the box, which you can download and import directly: https://gist.github.com/zetas/918e8e8ae11a1342ed2e727fce566e74. It works for me. (After going for option 2 manually and painfully, but unsuccessfully due to some strange issues with F2/F3/F4/F5 buttons after the change.) – HaiXin Tie Mar 04 '21 at 01:40