Tmux

From charlesreid1

How I Use Tmux

This is a short guide to how I use tmux to make my life easier and supercharge my vim muscle memory.

First, all tmux configurations go in ~/.tmux.conf. Tmux config files contain the same tmux commands you can execute from the command line, but without the "tmux" in front.

Find my full .tmux.conf file in the following locations:

The tmux configuration contains a few things:

  • Native vim keyboard bindings for tmux
  • Extra layer of custom vim key bindings to make navigating tmux panes and vim panes at the same time possible/easier
  • Sourcing other external tmux scripts (and linking those to keyboard shortcuts)

The last bullet point is key for creating customized tmux panel/window layouts. Complex tmux commands laying out a particular workspace configuration, including multiple windows, programs to run inside of each panel, and the ability to create new workspaces each time or enter a shared workspace, make this an extremely versatile way to define an infinite number of custom, multi-panel layouts that will save your work and be accessible from multiple shell windows.

In addition to all of this, you can bind these layouts to particular keyboard shortcuts or function names, enabling you to pull them up with a few keystrokes.

#Vim_Integration (section below) covers both how to enable native tmux vim bindings, and the custom vim keybindings mentioned above (to ease navigation of both tmux panels and vim panels).

#Sourcing_External_Scripts covers how to source scripts and bind that action to a keyboard shortcut.

Keyboard Shortcuts Overview

Using the customizations mentioned above and detailed below, a normal workflow looks like this:

Start tmux with the tmux command

Create a split screen, the default way:

  • Horizontal: Control-a =
  • Vertical: Control-a %

The more common of the two is a vertical split, so this has its own special shortcut:

  • Vertical: Control-A v

Navigating amongst the windows uses a lot of vim key bindings:

To move the cursor to the left pane: Control-a h

To move the cursor to the right pane: Control-a l

To move the cursor to the top pane: Control-a k

To move the cursor to the bottom pane: Control-a j

Moving Around with Vim and Tmux

To alternate among split window panes in vim, you can use the Control-w prefix, plus the usual hjkl movement commands, to navigate amongst panes. Those all map to the vim keybindings in tmux, but with Control-a as the prefix.

So to move to the left panel of a split vim window, I would use Control-w h, but to move to the left panel of a tmux vertical split layout, I would use Control-a h.

Managing Tmux Sessions

To detach from a session, use Control-a d

Once you've created and detached from multiple sessions, the tmux sessions will start to accumulate. Check on them: 

$ tmux ls
0: 1 windows (created Tue Aug 13 19:53:19 2019) [116x33]
2: 1 windows (created Tue Aug 13 23:09:04 2019) [116x33]
4: 1 windows (created Tue Aug 13 23:09:36 2019) [116x33]
6: 1 windows (created Tue Aug 13 23:09:45 2019) [116x33]

To attach to a session, use the short version of attach (a) and use the -t flag to specify the title of the session (the left-most integer numbers, in the above case) 

$ tmux a -t 0

To detach, use Control-a d

To clear out the attached session, use Control-a x

To kill sessions from the command line, use the kill-sessions verb: 

$ tmux kill-session -t 0
$ tmux kill-session -t 2
$ tmux kill-session -t 4
$ tmux kill-session -t 6

Vim Integration

Tmux and vim integration:

  • Set up vim keyboard shortcuts in the tmux config file
  • Add more vim-like keyboard shortcuts to navigate between panels
  • Create scripts and/or keyboard shortcuts that apply a certain session template (resizes panes, etc.)

Vim shortcuts in tmux config file

This turns on vi-like shortcuts in tmux (not really sure what this does, to be honest): 

# vi is good
setw -g mode-keys vi

Add more vim-like keyboard shortcuts

First, add some keyboard shortcuts that make navigating splits and windows more like navigating splits and windows in vim: 

# use vim-like keys for splits and windows
# 
#   Control-A plus:
# 
#   s = horizontal split
#   v = vertical split
#   h = pick left pane
#   j = pick down pane
#   k = pick up pane
#   l = pick right pane
# 
bind v split-window -h -c "#{pane_current_path}"
bind s split-window -v -c "#{pane_current_path}"
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
bind C-h select-pane -L
bind C-l select-pane -R

# smart pane switching with awareness of vim splits
# 
# Control plus:
# 
#   h = pick left pane
#   j = pick left pane
#   k = pick left pane
#   l = pick left pane
#   \ = pick another pane (?)
#
bind -n C-h run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-h) || tmux select-pane -L"
bind -n C-j run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-j) || tmux select-pane -D"
bind -n C-k run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-k) || tmux select-pane -U"
bind -n C-l run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys C-l) || tmux select-pane -R"
bind -n C-\ run "(tmux display-message -p '#{pane_current_command}' | grep -iqE '(^|\/)vim$' && tmux send-keys 'C-\\') || tmux select-pane -l"

Now add a few more shortcuts to make life easier: 

# Control-A then Control-L clears the screen
bind C-l send-keys 'C-l'

# Control-A then Control-O swaps out windows in their respective positions
bind C-o rotate-window

# Control-A plus + makes existing windows have horizontal layout
bind + select-layout main-horizontal

# Control-A plus = makes existing windows have vertical layout
bind = select-layout main-vertical

Add scripts or keyboard shortcuts for session templates

The following file should be stashed in your home dir next to your tmux config file (or anywhere else that's convenient).

This is a tmux file that defines a particular session arrangement. This session arrangement is fairly simple, it is a top-bottom horizontal split, with the bottom window taking up about 20% of the space and with the top window having the "vim" command run in it.

~/.tmux.session1 

# https://stackoverflow.com/a/5753059
new-session -A -s dev -n dev
send-keys 'vim' C-m
split-window -v -p 20
select-pane -t 1

Now, you can set a tmux keyboard shortcut to source this file when the keyboard shortcut is triggered. This will run these commands and set up a new tmux session called "dev" that has the specified configuration.

To bind this to the "s" key, as in Control-A then s to apply this panel configuration, add this to ~/.tmux.conf: 

# Set up easy go-to sessions with shortcuts
bind s source-file ~/.tmux.session1

List of Keyboard Shortcuts

The following is a list of keyboard shortcuts for tmux, for both "vi mode" and "emacs mode": 

       Function                vi             emacs
       Back to indentation     ^              M-m
       Clear selection         Escape         C-g
       Copy selection          Enter          M-w
       Cursor down             j              Down
       Cursor left             h              Left
       Cursor right            l              Right
       Cursor to bottom line   L
       Cursor to middle line   M              M-r
       Cursor to top line      H              M-R
       Cursor up               k              Up
       Delete entire line      d              C-u
       Delete to end of line   D              C-k
       End of line             $              C-e
       Goto line               :              g
       Half page down          C-d            M-Down
       Half page up            C-u            M-Up
       Next page               C-f            Page down
       Next word               w              M-f
       Paste buffer            p              C-y
       Previous page           C-b            Page up
       Previous word           b              M-b
       Quit mode               q              Escape
       Scroll down             C-Down or J    C-Down
       Scroll up               C-Up or K      C-Up
       Search again            n              n
       Search backward         ?              C-r
       Search forward          /              C-s
       Start of line           0              C-a
       Start selection         Space          C-Space
       Transpose chars                        C-t

Sourcing External Scripts

As demonstrated above, you can populate a file with tmux commands, and link that to a keyboard shortcut.

For example, if the file ~/.tmux.foobar contains tmux commands, the following will link that to the keyboard shortcut (prefix)-p (for example, Control-A then p): 

bind p source-file ~/.tmux.foobar

My full .tmux.conf

Find my full .tmux.conf file in the following locations:

Links

Tmux cheat sheet: https://gist.github.com/afair/3489752

Why tmux: http://dominik.honnef.co/posts/2010/10/why_you_should_try_tmux_instead_of_screen/

An intricate tmux conf: https://github.com/rosshadden/dotfiles/blob/master/src/.tmux.conf

Flags

Retrieved from "https://charlesreid1.com/w/index.php?title=Tmux&oldid=26743"