tmux-resurrect/README.md

188 lines
5.9 KiB
Markdown
Raw Normal View History

# Tmux Resurrect
2014-08-25 19:52:07 +00:00
Restore `tmux` environment after a system restart.
2014-08-26 14:07:04 +00:00
2014-08-30 14:24:54 +00:00
Tmux is great, except when you have to restart the computer. You lose all the
2014-08-27 19:31:10 +00:00
running programs, working directories, pane layouts etc.
There are helpful management tools out there, but they require initial
configuration and continuous updates as your workflow evolves or you start new
projects.
2014-08-30 14:24:54 +00:00
`tmux-resurrect` saves all the little details from your tmux environment so it
2014-08-29 17:12:28 +00:00
can be completely restored after a system restart (or when you feel like it).
No configuration is required. You should feel like you never quit tmux.
2014-08-27 19:31:10 +00:00
2014-11-09 15:42:53 +00:00
It even (optionally) [restores vim and neovim sessions](#restoring-vim-and-neovim-sessions)!
2014-08-27 23:09:55 +00:00
2014-08-30 08:48:59 +00:00
### Screencast
[![screencast screenshot](/video/screencast_img.png)](https://vimeo.com/104763018)
2014-08-27 23:09:55 +00:00
### Key bindings
2014-09-20 20:45:37 +00:00
- `prefix + Ctrl-s` - save
- `prefix + Ctrl-r` - restore
2014-08-31 09:35:58 +00:00
2014-09-20 20:45:37 +00:00
`prefix + Alt-s` and `prefix + Alt-r` key bindings are now deprecated.
2014-08-31 09:35:58 +00:00
For custom key bindings, add to `.tmux.conf`:
2014-09-10 11:26:14 +00:00
set -g @resurrect-save 'S'
set -g @resurrect-restore 'R'
2014-08-27 23:09:55 +00:00
2014-08-27 19:31:10 +00:00
### About
This plugin goes to great lengths to save and restore all the details from your
`tmux` environment. Here's what's been taken care of:
- all sessions, windows, panes and their order
- current working directory for each pane
- **exact pane layouts** within windows (even when zoomed)
2014-08-27 19:31:10 +00:00
- active and alternative session
- active and alternative window for each session
2014-08-29 15:04:00 +00:00
- windows with focus
2014-08-27 19:31:10 +00:00
- active pane for each window
2014-08-28 23:04:03 +00:00
- programs running within a pane! More details in the
[configuration section](#configuration).
2014-11-09 15:42:53 +00:00
- restoring vim/neovim sessions (optional). More details in
[restoring vim and neovim sessions](#restoring-vim-and-neovim-sessions).
2014-11-21 13:47:57 +00:00
- restoring bash history (optional, \*experimental*). More details in
2014-10-20 21:16:56 +00:00
[restoring bash history](#restoring-bash-history-experimental).
2014-08-27 19:31:10 +00:00
Requirements / dependencies: `tmux 1.9` or higher, `bash`.
2014-08-26 22:11:13 +00:00
2014-09-20 11:23:42 +00:00
`tmux-resurrect` is idempotent! It will not try to restore panes or windows that
already exist.
2014-11-21 13:47:57 +00:00
### FAQ
> I have a problem: first pane/window is not restoring!
Check out
[this wiki page](https://github.com/tmux-plugins/tmux-resurrect/wiki/Help:-issues-with-the-first-window)
for the explanation and problem solution.
2014-08-26 14:07:04 +00:00
### Installation with [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) (recommended)
Add plugin to the list of TPM plugins in `.tmux.conf`:
set -g @tpm_plugins ' \
tmux-plugins/tpm \
tmux-plugins/tmux-resurrect \
'
2014-08-26 14:07:04 +00:00
Hit `prefix + I` to fetch the plugin and source it. You should now be able to
use the plugin.
### Manual Installation
Clone the repo:
$ git clone https://github.com/tmux-plugins/tmux-resurrect ~/clone/path
2014-08-26 14:07:04 +00:00
Add this line to the bottom of `.tmux.conf`:
run-shell ~/clone/path/resurrect.tmux
2014-08-26 14:07:04 +00:00
Reload TMUX environment:
# type this in terminal
$ tmux source-file ~/.tmux.conf
You should now be able to use the plugin.
2014-08-27 19:31:10 +00:00
### Configuration
2014-08-30 14:24:54 +00:00
Configuration is not required, but it enables extra features.
2014-08-28 23:04:03 +00:00
Only a conservative list of programs is restored by default:<br/>
2014-11-09 15:42:53 +00:00
`vi vim nvim emacs man less more tail top htop irssi`.
2014-08-27 19:31:10 +00:00
- Restore additional programs with the setting in `.tmux.conf`:
2014-08-27 19:31:10 +00:00
set -g @resurrect-processes 'ssh psql mysql sqlite3'
2014-08-27 19:31:10 +00:00
- Programs with arguments should be double quoted:
set -g @resurrect-processes 'some_program "git log"'
- Start with tilde to restore a program whose process contains target name:
set -g @resurrect-processes 'irb pry "~rails server" "~rails console"'
2014-09-01 19:18:15 +00:00
- Use `->` to specify a command to be used when restoring a program (useful if
the default restore command fails ):
set -g @resurrect-processes 'some_program "grunt->grunt development"'
2014-08-27 19:31:10 +00:00
- Don't restore any programs:
set -g @resurrect-processes 'false'
2014-08-27 19:31:10 +00:00
- Restore **all** programs (be careful with this!):
set -g @resurrect-processes ':all:'
2014-08-27 19:31:10 +00:00
2014-11-09 15:42:53 +00:00
#### Restoring vim and neovim sessions
2014-08-27 23:09:55 +00:00
2014-11-09 15:42:53 +00:00
- save vim/neovim sessions. I recommend
[tpope/vim-obsession](https://github.com/tpope/vim-obsession) (as almost every
plugin, it works for both vim and neovim).
2014-08-27 23:09:55 +00:00
- in `.tmux.conf`:
2014-11-09 15:42:53 +00:00
# for vim
2014-09-10 11:26:14 +00:00
set -g @resurrect-strategy-vim 'session'
2014-11-09 15:42:53 +00:00
# for neovim
set -g @resurrect-strategy-nvim 'session'
2014-08-27 23:09:55 +00:00
2014-11-09 15:42:53 +00:00
`tmux-resurrect` will now restore vim and neovim sessions if `Sessions.vim` file
is present.
2014-08-27 23:09:55 +00:00
2014-10-06 10:59:14 +00:00
#### Resurrect save dir
By default Tmux environment is saved to a file in `~/.tmux/resurrect` dir.
Change this with:
set -g @resurrect-dir '/some/path'
2014-10-17 20:40:15 +00:00
#### Restoring bash history (experimental)
In `.tmux.conf`:
2014-11-21 13:47:57 +00:00
set -g @resurrect-save-bash-history 'on'
2014-10-17 20:40:15 +00:00
2014-10-20 21:16:56 +00:00
Bash `history` for individual panes will now be saved and restored. Due to
technical limitations, this only works for panes which have no program running in
foreground when saving. `tmux-resurrect` will send history write command
to each such pane. To prevent these commands from being added to history themselves,
add `HISTCONTROL=ignoreboth` to your `.bashrc` (this is set by default in Ubuntu).
2014-10-17 20:40:15 +00:00
### Other goodies
- [tmux-copycat](https://github.com/tmux-plugins/tmux-copycat) - a plugin for
regex searches in tmux and fast match selection
- [tmux-yank](https://github.com/tmux-plugins/tmux-yank) - enables copying
highlighted text to system clipboard
- [tmux-open](https://github.com/tmux-plugins/tmux-open) - a plugin for quickly
opening highlighted file or a url
2014-08-27 19:31:10 +00:00
### Reporting bugs and contributing
Both contributing and bug reports are welcome. Please check out
[contributing guidelines](CONTRIBUTING.md).
2014-08-27 19:31:10 +00:00
### Credits
2014-08-27 23:09:55 +00:00
[Mislav Marohnić](https://github.com/mislav) - the idea for the plugin came from his
2014-11-21 13:47:57 +00:00
[tmux-session script](https://github.com/mislav/dotfiles/blob/2036b5e03fb430bbcbc340689d63328abaa28876/bin/tmux-session).
2014-08-27 19:31:10 +00:00
2014-08-30 12:40:38 +00:00
### Other
Here's another script that tries to solve the same problem:
[link](http://brainscraps.wikia.com/wiki/Resurrecting_tmux_Sessions_After_Reboot).
2014-08-30 15:30:30 +00:00
It even has the same name, even though I discovered it only after publishing
`v1.0` of this plugin.
2014-08-30 12:40:38 +00:00
2014-08-25 19:52:07 +00:00
### License
[MIT](LICENSE.md)