README.md 4.68 KB
Newer Older
1
# Tmux Resurrect
Bruno Sutic's avatar
Bruno Sutic committed
2

Kevin Ji's avatar
Kevin Ji committed
3
[![Build Status](https://travis-ci.org/tmux-plugins/tmux-resurrect.svg?branch=master)](https://travis-ci.org/tmux-plugins/tmux-resurrect)
Bruno Sutic's avatar
Bruno Sutic committed
4

Bruno Sutic's avatar
Bruno Sutic committed
5
Restore `tmux` environment after system restart.
Bruno Sutic's avatar
Bruno Sutic committed
6

Michael Mior's avatar
Michael Mior committed
7
Tmux is great, except when you have to restart the computer. You lose all the
Bruno Sutic's avatar
Bruno Sutic committed
8
9
10
11
12
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.

Michael Mior's avatar
Michael Mior committed
13
`tmux-resurrect` saves all the little details from your tmux environment so it
Bruno Sutic's avatar
Bruno Sutic committed
14
15
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.
Bruno Sutic's avatar
Bruno Sutic committed
16

Bruno Sutic's avatar
Bruno Sutic committed
17
18
It even (optionally)
[restores vim and neovim sessions](docs/restoring_vim_and_neovim_sessions.md)!
Bruno Sutic's avatar
Bruno Sutic committed
19

20
21
Automatic restoring and continuous saving of tmux env is also possible with
[tmux-continuum](https://github.com/tmux-plugins/tmux-continuum) plugin.
22

23
24
25
26
### Screencast

[![screencast screenshot](/video/screencast_img.png)](https://vimeo.com/104763018)

Bruno Sutic's avatar
Bruno Sutic committed
27
28
### Key bindings

Bruno Sutic's avatar
Bruno Sutic committed
29
30
- `prefix + Ctrl-s` - save
- `prefix + Ctrl-r` - restore
31

Bruno Sutic's avatar
Bruno Sutic committed
32
33
34
35
36
37
38
### 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
39
- **exact pane layouts** within windows (even when zoomed)
Bruno Sutic's avatar
Bruno Sutic committed
40
41
- active and alternative session
- active and alternative window for each session
Bruno Sutic's avatar
Bruno Sutic committed
42
- windows with focus
Bruno Sutic's avatar
Bruno Sutic committed
43
- active pane for each window
Bruno Sutic's avatar
Bruno Sutic committed
44
- "grouped sessions" (useful feature when using tmux with multiple monitors)
Bruno Sutic's avatar
Bruno Sutic committed
45
- programs running within a pane! More details in the
Bruno Sutic's avatar
Bruno Sutic committed
46
47
48
49
50
51
  [restoring programs doc](docs/restoring_programs.md).

Optional:

- [restoring vim and neovim sessions](docs/restoring_vim_and_neovim_sessions.md)
- [restoring pane contents](docs/restoring_pane_contents.md)
52
- [restoring a previously saved environment](docs/restoring_previously_saved_environment.md)
Bruno Sutic's avatar
Bruno Sutic committed
53

54
Requirements / dependencies: `tmux 1.9` or higher, `bash`.
Bruno Sutic's avatar
Bruno Sutic committed
55

56
57
Tested and working on Linux, OSX and Cygwin.

Bruno Sutic's avatar
Bruno Sutic committed
58
`tmux-resurrect` is idempotent! It will not try to restore panes or windows that
59
60
already exist.<br/>
The single exception to this is when tmux is started with only 1 pane in order
Bruno Sutic's avatar
Bruno Sutic committed
61
to restore previous tmux env. Only in this case will this single pane be
62
overwritten.
Bruno Sutic's avatar
Bruno Sutic committed
63

Bruno Sutic's avatar
Bruno Sutic committed
64
65
66
67
### Installation with [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) (recommended)

Add plugin to the list of TPM plugins in `.tmux.conf`:

Bruno Sutic's avatar
Bruno Sutic committed
68
    set -g @plugin 'tmux-plugins/tmux-resurrect'
Bruno Sutic's avatar
Bruno Sutic committed
69
70
71
72
73
74
75
76

Hit `prefix + I` to fetch the plugin and source it. You should now be able to
use the plugin.

### Manual Installation

Clone the repo:

77
    $ git clone https://github.com/tmux-plugins/tmux-resurrect ~/clone/path
Bruno Sutic's avatar
Bruno Sutic committed
78
79
80

Add this line to the bottom of `.tmux.conf`:

81
    run-shell ~/clone/path/resurrect.tmux
Bruno Sutic's avatar
Bruno Sutic committed
82

Bruno Sutic's avatar
Bruno Sutic committed
83
Reload TMUX environment with: `$ tmux source-file ~/.tmux.conf`.
Bruno Sutic's avatar
Bruno Sutic committed
84
85
You should now be able to use the plugin.

Bruno Sutic's avatar
Bruno Sutic committed
86
### Docs
87

88
89
- [Guide for migrating from tmuxinator](docs/migrating_from_tmuxinator.md)

Bruno Sutic's avatar
Bruno Sutic committed
90
**Configuration**
91

Bruno Sutic's avatar
Bruno Sutic committed
92
- [Changing the default key bindings](docs/custom_key_bindings.md).
Sergey Vlasov's avatar
Sergey Vlasov committed
93
- [Setting up hooks on save & restore](docs/hooks.md).
Bruno Sutic's avatar
Bruno Sutic committed
94
- Only a conservative list of programs is restored by default:<br/>
95
  `vi vim nvim emacs man less more tail top htop irssi weechat mutt`.<br/>
Bruno Sutic's avatar
Bruno Sutic committed
96
97
98
99
  [Restoring programs doc](docs/restoring_programs.md) explains how to restore
  additional programs.
- [Change a directory](docs/save_dir.md) where `tmux-resurrect` saves tmux
  environment.
100

Bruno Sutic's avatar
Bruno Sutic committed
101
**Optional features**
102

Bruno Sutic's avatar
Bruno Sutic committed
103
104
105
- [Restoring vim and neovim sessions](docs/restoring_vim_and_neovim_sessions.md)
  is nice if you're a vim/neovim user.
- [Restoring pane contents](docs/restoring_pane_contents.md) feature.
106

Bruno Sutic's avatar
Bruno Sutic committed
107
**Experimental features (also optional)**
108

109
- [restoring shell history](docs/restoring_shell_history.md)
110

111
112
113
114
115
116
117
118
### 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
Bruno Sutic's avatar
Bruno Sutic committed
119
120
- [tmux-continuum](https://github.com/tmux-plugins/tmux-continuum) - automatic
  restoring and continuous saving of tmux env
121

Bruno Sutic's avatar
Bruno Sutic committed
122
123
### Reporting bugs and contributing

124
125
Both contributing and bug reports are welcome. Please check out
[contributing guidelines](CONTRIBUTING.md).
Bruno Sutic's avatar
Bruno Sutic committed
126
127
128

### Credits

Bruno Sutic's avatar
Bruno Sutic committed
129
[Mislav Marohnić](https://github.com/mislav) - the idea for the plugin came from his
Bruno Sutic's avatar
Bruno Sutic committed
130
[tmux-session script](https://github.com/mislav/dotfiles/blob/2036b5e03fb430bbcbc340689d63328abaa28876/bin/tmux-session).
Bruno Sutic's avatar
Bruno Sutic committed
131

Bruno Sutic's avatar
Bruno Sutic committed
132
133
### License
[MIT](LICENSE.md)