This post describes how to install and use tmux-resurrect, a method for saving tmux sessions.

Saving and restoring tmux sessions

Sometimes your computer may need to be restarted. However, a restart will kill any open or detached tmux sessions. An enterprising developer created tmux-resurrect to allow tmux sessions to survive a reboot by 'saving' them.

Installing tmux-resurrect

Following the instructions on the GitHub page, clone the repo to some location.

For the purposes of this and subsequent post, I recommend cloning while in the folder ~/build/tmux/, which will then create the folder ~/build/tmux/tmux-resurrect/:

mkdir -p ~/build/tmux/
cd ~/build/tmux
git clone https://github.com/tmux-plugins/tmux-resurrect

Then, place the following line at the end of the ~/.tmux.conf file:

run-shell ~/build/tmux/tmux-resurrect/resurrect.tmux

Finally, in order to have the pane contents restored, add the following line to the ~/.tmux.conf file:

set -g @resurrect-capture-pane-contents 'on'

See this post for more details on this last step.

That's it! It is ready to use.

Using tmux-resurrect

While in a tmux session, you can use the following (default) shortcuts:

prefix Ctrl-s save current tmux session
prefix Ctrl-r reload saved tmux session

Changing the default keys: my preferred method

However, I prefer to include the following in my .tmux.conf, which still uses prefix Ctrl-r and prefix Ctrl-s to restore and save, respectively, but first has a y/n check:

#change defaults for resurrect (two steps)
#1. unbind the current defaults C-s and C-r
unbind-key -T prefix C-s
unbind-key -T prefix C-r
   
#2. Still use prefix C-s and C-r, but now ask for (y/n) response before saving/restoring.
#This assumes tmux-resurrect is saved to ~/build/tmux/tmux-resurrect folder
bind-key -T prefix C-s confirm-before -p 'Save this tmux session? (y/n)' 'run-shell ~/build/tmux/tmux-resurrect/scripts/save.sh'
bind-key -T prefix C-r confirm-before -p 'Resurrect last tmux session? (y/n)' 'run-shell ~/build/tmux/tmux-resurrect/scripts/restore.sh'
 

The last two commands are long, and depend on specifying the correct path to tmux-resurrect (recall that I used ~/build/tmux/tmux-resurrect folder). See the end of the next post for more information about creating your own shortcuts for tmux (short answer: look at examples using prefix ?, but read the post for more details).

The reason I like to have the prompt, is that sometimes I amunkeyboardinated, and like to have a check that I am not restoring, when I am really trying to save. Also, it is very similar to prefix r, which in my .tmux.conf file is the shortcut to reload the .tmux.conf file (which doesn't do any harm).

Changing the default keys: alternative

However, if you simply want to change the defaults to something else, the tmux-resurrect author has made two easy-to-use commands (examples below):

#change tmux-resurrect save to prefix C-q
#set -g @resurrect-save 'C-q'
 
#change tmux-resurrect restore to prefix R (captial R)
#set -g @resurrect-restore 'R'

A note on restoring

Perhaps you will decide to save a session because you are forced to restart your computer/server (e.g. to install a necessary update). So, you hit prefix C-s, hit y (using my preferred method of a 'prompt-check'), and the session is saved. You exit tmux (prefix d), and restart.

When you restart, the tmux server will have been killed (that is why we use tmux-resurrect...) - so how do you restore?

Start a new session simply with

tmux

and then immediately use the restore command (e.g. prefix Ctrl-r). I have found that if you first split windows, use ls, etc, then the restore will not work. So the point is, only try and restore from a completely blank/fresh session.

How tmux-resurrect works

Well, this is only a very short description, but is worthwhile knowing at least what extra files are created in order to enable tmux-resurrect to work.

Basically, it saves files to:

~/.tmux/resurrect/

and then reloads the data from there. Obviously, the author deserves huge credit for creating this very useful tool. It especially great that pane contents are saved. There is even a way to restore bash history, although it is (currently) only experimental, so I prefer not to use this option.