screen to tmux: A Humble Quickstart Guide « My Humble Corner

An online friend named bmc_ on Twitter introduced me to tmux. It reportedly has simpler, cleaner code than screen, which implies that it’s more robust, in addition to more very useful features.

The problem is tmux is very different from screen. It wasn’t at all easy to jump straight into tmux, without doing a thorough read of the man pages, which is not exactly how great first impressions are made.

That’s why I decided to write this.

This quick-start guide will assume you are familiar with screen.

“Let the Wild Rumpus Begin”

Launch yourself into tmux:

tmux

Ctrl+B is your tmux shortcut (just like Ctrl+A used to be in screen).

You’re looking at your first window, which has only one pane. We’ll call this your first prompt. Log into irc or something “persistent”.

Split your window horizontally to create a new pane:

[Ctrl+b] "

You can now work in this second prompt while observing the first.

These shortcuts allows you to swap in Alt+Tab style:

[Ctrl+b] {
[Ctrl+b] }

You can use these keys to move between panes:

[Ctrl+b] [Up|Down|Left|Right]

Let’s say, though, that you want to open a third prompt in that bottom area, without losing your second. Creating a new window causes you to lose view of your first prompt, which has your persistent task like IRC. We could add a new pane by splitting the bottom pane vertically:

[Ctrl+b] %

This splits valuable screen space, though, and you only want to be using one prompt in that bottom space at a time anyway.

Let’s try this. Create a new window:

[Ctrl+b] c

This space is going to be a “holding” area for your second prompt until you’re done with your third. (We have to do this because of a difference in how panes are utilized. Screen looks at panes as permanent fixtures of your workspace until you say otherwise, whereas tmux looks at panes as specific to a prompt, unless said otherwise, and will close that pane when the prompt closes.)

For the curious, a list of open windows can be found here:

[Ctrl+b] w

Type something into this new window so you can tell the difference between it and the others. Now go back to the first window:

[Ctrl+b] 0

Focus the bottom pane using the Up/Down keys mentioned previously, and then type this:

[Ctrl+b] :swapp -s 1.0 # means “swap prompt in window #1 pane #0 with the current prompt”

With any luck that bottom pane now contains your third prompt, and the second prompt will be in the new window.

Copying Window History

By default, tmux keeps 2000 lines of “window history”. This is what screen calls scrollback.

You can enter copy mode and view this history by typing:

[Ctrl+b] PageUp

The “q” key quits this mode.

If you want to take advantage of copy mode, use Space to mark the first character of your selection, and Enter to mark the end. To paste, use the following shortcut:

[Ctrl+b] =

This shortcut will also bring up a list of paste buffers if there is more than one.

More Pane Management

(No pun intended.)

You can also “break” a pane out of its current window into an entirely new window:

[Ctrl+b] !

You can also do the reverse, and “join” an existing pane from another window into the current window:

[Ctrl+b] :joinp -h -s 0.0 -p 75 # join window #0 pane #0 horizontally, giving it 75% of the screen space

If you decide you don’t like the size of a pane, you can use the following shortcuts to resize the current pane:

[Ctrl+b] Alt+[Up|Down|Left|Right]

Interestingly enough, any shortcut involving directional keys can be used over and over rapidly. As soon as there are any pauses, however, tmux stops listening and you’ll have to re-execute the shortcut again.

Window and pane numbers can be looked up as follows:

[Ctrl+b] w # for window numbers
[Ctrl+b] q # for pane numbers

Built-in Help

You can find a list of keybindings here:

[Ctrl+b] ?

Use the “q” key to get out of this and other interactive modes.

Leaving and Coming Back Again

Exiting a window means either causing all prompts to close (via “exit” in each for example) or moving panes within a window to other windows (via “joinp” for example) until a window has no more panes. At either point, the window closes.

If your window is misbehaving, you can “kill” it by typing:

[Ctrl+b] &

Similarly, tmux will close when there are no more windows in a session.

If you want to leave your windows intact but close the terminal or ssh connection, you can detach and reattach later. Detaching works just like screen:

[Ctrl+b] d

Last, but not least, you can reattach to the existing session as follows:

tmux a

Feedback Welcome

This gets you started. The man page is well written, but very long. If you think I missed something important, or need help with a particular use of tmux, comment below.

Updated 2011/08/30 12:20 EDT – Added a bit of text on window history, and added more sections to break this page up a bit better.
Updated 2011/08/31 14:42 EDT – Added more about closing windows and sessions, thanks to David in comments.

screen to tmux: A Humble Quickstart Guide « My Humble Corner