Shortcut to basic tmux.conf file. Save as ~/.tmux.conf.

Shortcut to my tmux.conf file. Save as ~/.tmux.conf.

Shortcut to another simple tmux.conf file, but without tmux-resurrect. Save as ~/.tmux.conf.




This post describes some commands that can be used to make a ~/.tmux.conf file.

Basically, this file customises the appearance and behaviour/shortcuts of your tmux, similarly to how your ~/.vimrc file customises the appearance of Vim.

The .tmux.conf file(s) below are based on the one described in provided by this book, as well as the one provided by this post (originally found here) and this post.

A .tmux.conf file

The following .tmux.conf files can be saved to ~/.tmux.conf.

  • The tmux file I use can be downloaded here: tmux.conf.

Note that, if you are using OSX, you will need to create the ~/.tmux-osx.conf (described at the end of this post)

  • The same tmux file, but including commented out tmux-resurrect and reattach-to-user-namespace lines: simpletmuxconf.txt

We will go through various blocks piece-by-piece. Once you know what everything does, you will be able to modify your own .tmux.conf to have the shortcuts/colours you prefer.

Note that any line starting with a # is a comment.

Changing the Prefix key

The following block at the top of the .tmux.conf file changes the Prefix key from the default Ctrl b to Ctrl a (which is easier to handle with one hand). Note that in the conf file, these are encoded as C-b and C-a, respectively.

#Priority: prefix key and reloading tmux.conf:
#-------------------------------------------------------#
#change prefix from C-b to C-a
unbind C-b 
set -g prefix C-a  
 
#bind C-a C-a to 'home', or start of line, which was C-a previously  
bind C-a send-prefix
#-------------------------------------------------------#

Let us look at the key lines individually. The first line:

unbind C-b 

stops Ctrl b from being the Prefix key.

The next two lines:

set -g prefix C-a  
bind C-a send-prefix

assign Ctrl a to be the Prefix key.

Reloading ~/.tmux.conf

While you are building/making changes to your .tmux.conf file, you may want to see how your changes affect your tmux session, without having to open a new session. The following reloads the .tmux.conf file, even while you are in an active session, using the key combination Prefix r.

bind r source-file ~/.tmux.conf \; display "Reloaded ~/.tmux.conf"  

It also displays a short message saying that .tmux.conf file has been reloaded. This is a very useful shortcut!

General settings

Below are several general commands that handle various settings. We'll go through the commands one at a time.

#Terminal admin:
#-------------------------------------------------------#
#set mouse off/on - if off, forces you to use keyboard with prefix-[
set -g mouse on
 
#256 colours
set -g default-terminal "screen-256color"
 
# start with window 1 (instead of 0)
set -g base-index 1
 
# start with pane 1
set -g pane-base-index 1
 
# use vi mode
setw -g mode-keys vi
set -g status-keys vi
 
# allow utf8 support
setw -g utf8 on
#-------------------------------------------------------#

The first command allows the mouse to be used to resize panes, scroll in panes, etc:

set -g mouse on

The next command allows 256 colours to be used in the terminal:

set -g default-terminal "screen-256color"

Usually, sessions, windows and panes are numbered starting from 0. The next two lines change this, so that the windows and panes are numbered starting from 1. There is currently no easy way to ensure that sessions are numbered starting from 1.

set -g base-index 1
set -g pane-base-index 1

The final line lets tmux use utf8 (special) characters. This allows for the time to be displayed in the status bar (more on this later):

setw -g utf8 on

Pane colours

The below block of code sets the colours of the active/inactive panes, and the borders of the panes. The ability to distinguish the active/inactive pane backgrounds is a feature of tmux 2.1.

#-------------------------------------------------------#
#Pane colours
#-------------------------------------------------------#
# set inactive/active window styles
set -g window-style 'fg=colour247,bg=colour236'
set -g window-active-style 'fg=colour250,bg=black'
 
#pane border
set -g pane-border-bg colour235
set -g pane-border-fg colour238
set -g pane-active-border-bg colour236
set -g pane-active-border-fg colour51
#-------------------------------------------------------#

The pictures below show how the inactive panes are slightly greyed, and that the border of the active panes is cyan.

vim pane is active

In the above figure, the Vim pane on the left is active.

bash pane is active

In the above figure, the bash pane in the top-right corner is active.

Vim colourscheme settings

In order for the inactive window style to be applied to Vim panes, it is necessary to check the line in your colourscheme.vim file that starts with hi Normal, e.g.

hi Normal           guifg=#e6e1de ctermfg=7 guibg=#2b2b2b ctermbg=235 gui=none

The problem with this line is the two terms guibg= and ctermbg=235. If these terms are deleted, as in:

hi Normal           guifg=#e6e1de ctermfg=7 gui=none

or

hi Normal           guifg=#e6e1de ctermfg=none gui=none

then the inactive style will be applied to Vim panes. Thanks to Nicholas Marriott for answering my question about this! (For some reason, I had difficulty replying to the Google Groups post, but another user later filled in the details).

Pane navigation and management

The below block of code sets the colours of the active/inactive panes, and the borders of the panes. The ability to distinguish the active/inactive pane backgrounds is a feature of tmux 2.1.

#-------------------------------------------------------#
#PANE NAVIGATION/MANAGEMENT
#-------------------------------------------------------#
# splitting panes
bind \ split-window -h -c '#{pane_current_path}'
bind - split-window -v -c '#{pane_current_path}'
 
# open new panes in current path
bind c new-window -c '#{pane_current_path}'
 
# Use Alt-arrow keys WITHOUT PREFIX KEY to switch panes
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D
#-------------------------------------------------------#

The first two lines:

bind \ split-window -h -c '#{pane_current_path}'
bind - split-window -v -c '#{pane_current_path}'

allow windows to be split into panes, using

  • Prefix - to split horizontally (top/bottom half)
  • Prefix \ to split vertically (left/right half)

On an American keyboard, the \ key is the same as the | key, and the - and | shapes suggest the splits that will be created.

Panes can be further subdivided by using these commands again. The final bit of the command forces the new panes to open in the same path.

The next line:

bind c new-window -c '#{pane_current_path}'

ensures that a new window will open in the same path as the previous window. You can switch between windows using Prefix n and Prefix p.

Finally, the four lines

bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

allow one to move between panes by holding the Alt key and pressing the arrow keys. Note that while C- refers to the Ctrl key, M- refers to the 'meta' key, which is usually the Alt key.

Note: if you are using iTerm as your terminal emulator, you may need to check your settings for the 'meta' key: iTerm → Preferences → Profiles → Keys → Left/Right option keys acts as: +Esc

Additional navigation keys

It is also possible to Alt h,j,k,l to navigate panes (Vim navigation keys), using the following:

bind -n M-h select-pane -L
bind -n M-l select-pane -R
bind -n M-k select-pane -U
bind -n M-j select-pane -D

However, this is not used in my .tmux.conf file. If you do decide to try this option out, but later want to remove these shortcuts, you can unbind the keys using the following:

unbind -n M-h
unbind -n M-l
unbind -n M-k
unbind -n M-j

Resizing panes

Although it is possible to resize panes using the mouse (and dragging), the following commands make it easy to resize panes using keyboard shortcuts.

#Resizing panes:
bind -r j resize-pane -D 2
bind -r k resize-pane -U 2
bind -r h resize-pane -L 2
bind -r l resize-pane -R 2

When you are in a specific pane:

  • prefix j to move horizontal pane border downwards
  • prefix k to move horizontal pane border upwards
  • prefix h to move vertical pane border left
  • prefix l to move vertical pane border right

The nice thing is, because the -r flag was used, you only need to press prefix for the first pane resize, and afterwards you can just press Alt j,k,h,l (note how these are the standard Vim movement keys).

For example, to adjust the height of a pane, first press prefix Alt j, and then you can just press Alt j or Alt k to toggle the height setting.

Also, note that when there is more than one horiztonal border, the lower border is moved, and when there is more than one vertical border, the right-hand border is moved (two minutes playing with the commands will make things clear).

Copy-pasting between panes

The following shortcuts were taken from this very useful post, and allow easy coopy/pasting between panes.

#-------------------------------------------------------#
#Pane copy/pasting
#-------------------------------------------------------#
bind-key -t vi-copy 'v' begin-selection
bind-key -t vi-copy 'y' copy-selection
bind C-v paste-buffer
#-------------------------------------------------------#
  • In tmux, use prefix [ to switch to 'copy' mode. You can then press v to switch to 'visual' mode, and start highlighting text.
  • Use Vim keys b,w,h,l, etc, to highlight more text.
  • Use y to copy text to system clipboard.
  • Move to another pane/location.
  • Finally, use prefix Ctrl v to paste text in another pane.

It is possible to change the key-binding to enter 'copy' mode to prefix Esc (as in Vim) using the following:

unbind [
bind-key -t vi-copy 'v' begin-selection
bind Escape copy-mode

but I prefer not to use this binding; it seems unnecessary.

Note: One could alternatively bind prefix p to be paste, but this would overwrite the command which changes windows to the previous window. I prefer to use prefix Ctrl v, which may be familiar for ex-Windows users.

Note: to exit 'copy' mode, simply press Enter.

Note: This post shows that the default commands for OSX are:

  • prefix [ - enter copy mode
  • Enter - copy
  • prefix ] - paste

Setting the escape time

This is a quick command (but helpful) to change the 'escape time', and make tmux more responsive to commands:

#-------------------------------------------------------#
#Setting escape time delay to be smaller 
#to make tmux more responsive to commands
#-------------------------------------------------------#
set -s escape-time 1
#-------------------------------------------------------#

Creating status line

This (very long) block creates the status bar (the toolbar at the bottom of the screen) and sets its colours. The commands are explained below.

#-------------------------------------------------------#
# STATUS LINE/TOOLBAR AT BOTTOM OF SCREEN
#-------------------------------------------------------#
 
# Set background of status line to black
#-------------------------------------------------------#
set -g status-bg black
 
 
#Colours for messages
#-------------------------------------------------------#
# enable activity alerts
setw -g monitor-activity on
set -g visual-activity on
 
#Show reloaded message in bright white
set -g message-fg white
set -g message-bg default
set -g message-attr bright
#-------------------------------------------------------#
 
 
# Status line left side
#-------------------------------------------------------#
# Session: 0 1 1 settings
set -g status-left-length 40 
set -g status-left "#[fg=colour245]Session: #S #[fg=colour84]#I #[fg=colour75]#P"
#-------------------------------------------------------#
 
 
#Window/pane type in centre
#-------------------------------------------------------#
#move bash* to centre
set -g status-justify centre
 
# set the color of the window list (name of the pane)
setw -g window-status-fg colour75
setw -g window-status-bg default 
setw -g window-status-attr dim
#-------------------------------------------------------#
 
 
#Time and date on right-hand side
#-------------------------------------------------------#
# Status line right side
# e.g. 28 Nov 18:15
set -g status-right "#[fg=colour245]%d %b #[fg=colour256] %R"
 
# Update the status bar every sixty seconds (for the time)
set -g status-interval 60
#-------------------------------------------------------#
 
#-------------------------------------------------------#
#END OF STATUS LINE MESSAGES
#-------------------------------------------------------#

Let's got through these blocks one at a time. First,

# Set background of status line to black
#-------------------------------------------------------#
set -g status-bg black

sets the background of the status bar to be black.

The following:

#Colours for messages
#-------------------------------------------------------#
# enable activity alerts
setw -g monitor-activity on
set -g visual-activity on

enables notification messages which indicate when something happens in another window. When this occurs, the window name in the status bar is highlighted, as in the example below, which shows that there was activity in the R session in the second window (in this case, an R command finished its computation).

activity in second window

The above figure shows that there was activity in the second window, which is an R session.

The following block:

#Show reloaded message in bright white
set -g message-fg white
set -g message-bg default
set -g message-attr bright

sets the colour of messages to bright white. Instead of using default, the background could be set to black, but it is not necessary here.

We now start the set the colours of the three pieces of the status line (left, middle and right). On the left-hand side, the colours of the block Session: X Y Z are set using:

# Status line left side
#-------------------------------------------------------#
# Session: X Y Z settings
set -g status-left-length 40 
set -g status-left "#[fg=colour245]Session: #S #[fg=colour84]#I #[fg=colour75]#P"

Here, the first number X is number of the session (and is dark grey), the second number Y is the window number (and is green), and the third number Z is the pane number (and is blue).

The middle block:

#Window/pane type in centre
#-------------------------------------------------------#
#move bash* to centre
set -g status-justify centre
 
# set the color of the window list (name of the pane)
setw -g window-status-fg colour75
setw -g window-status-bg default 
setw -g window-status-attr dim
#-------------------------------------------------------#

moves the part specifying the window names to the centre, and sets the colour to blue.

The right-hand block, which specifies the time, is set using:

#Time and date on right-hand side
#-------------------------------------------------------#
# Status line right side
# e.g. 28 Nov 18:15
set -g status-right "#[fg=colour245]%d %b #[fg=colour256] %R"
 

The final two lines refresh the status bar every 60 seconds, so the time is always accurate (to the minute).

# Update the status bar every sixty seconds (for the time)
set -g status-interval 60

Choosing your own colours

In order to see the colour codes (numbers 0 to 255, note that 0 is black), save the following script

for i in {0..255} ; do
    printf "\x1b[38;5;${i}mcolours${i}\n"
done

from this post as tmuxcolours.sh, then set it as executable and run it using:

chmod a+x tmuxcolours.sh 
./tmuxcolours.sh 

will display the colours in the terminal.

Optional: tmux-resurrect

See this post for directions to set up tmux-resurrect and for the commands to include in your .tmux.conf

Optional: running other apps from inside tmux

I like to use the Skim PDF viewer, which I usually open (in OSX) using

open -a Skim myfile.pdf

However, if you try this from inside tmux, you will might get an error message. The way to fix this, according to this post, is to install reattach-to-user-namespace using brew

brew install reattach-to-user-namespace

then add the following at the end of your.tmux.conf:

#-------------------------------------------------------#
#reattach-to-user-namespace must be installed
#-------------------------------------------------------#
#the following line refers to the file ~/.tmux-osx.conf
if-shell 'test "$(uname)" = "Darwin"' 'source ~/.tmux-osx.conf'
#-------------------------------------------------------#

this line checks if OSX is running, and if so, then runs the code in ~/.tmux-osx.conf. This allows the same .tmux.conf file to be used in OSX and Linux.

To complete things, create the file ~/.tmux-osx.conf containing

#if osx, use reattach-to-user-namesapce
set-option -g default-command "reattach-to-user-namespace -l ${SHELL}"

which allows reattach-to-user-namespace to handle the problem, and Skim should open correctly.

Note: you will need to kill the tmux session, and reopen tmux in order for the changes to be introduced (for some reason, simply reloading the .tmux.conf file will not be enough.

Conclusion

This post has sought to introduce a few useful commands for a .tmux.conf. Try each command out individually, reloading .tmux.conf using prefix r after each addition, to see how each command works.