4 releases
0.5.7 | Aug 14, 2024 |
---|---|
0.5.6 | Aug 14, 2024 |
0.5.5 | Aug 14, 2024 |
0.5.4 | Aug 29, 2023 |
#472 in Command line utilities
61 downloads per month
75KB
1K
SLoC
tmux-backup
A backup & restore solution for Tmux sessions.
Version requirement: rustc 1.74+
Features
- Backup and restore of your tmux environment:
- tmux sessions windows, panes, with layout, titles & pane history
- current and last session.
- Fast: less than 1 sec for 16 sessions, 45 windows and 80 panes.
- Show the catalog of backups, with age, file size, content description & archive format
- 2 strategies are available:
- keep the
n
most recent backups - classic backup strategy:
- the lastest backup per hour for the past 24 hours (max 23 backups - exclude the past hour),
- the lastest backup per day for the past 7 days (max 6 backups - exclude the past 24 hours),
- the lastest backup per week of the past 4 weeks (max 3 backups - exclude the past week),
- the lastest backup per month of this year (max 11 backups - exclude the past month).
- keep the
- Because you decide where backups are stored, you can use both strategies, combining the benefits of high-frequency backups and on demand backups like in tmux-resurrect.
Getting started
After installation (see below), you can either use it from the command line, or via tmux bindings.
The catalog is located by default in $XDG_STATE_HOME/tmux-backup/
, or
§HOME/.state/tmux-backup
otherwise. The default strategy is "most-recent", but you can change
it with --strategy classic
. Check usage with tmux-backup --help
for detailed help.
View the catalog of existing backups
$ tmux-backup catalog list --details
Strategy: KeepMostRecent: 10
Location: `$HOME/.local/state/tmux-backup`
NAME AGE STATUS FILESIZE VERSION CONTENT
11. backup-20220907T224553.156103.tar.zst 2 days purgeable 644.17 kB 1.0 16 sessions 43 windows 79 panes
10. backup-20220907T224926.103771.tar.zst 2 days retainable 644.38 kB 1.0 16 sessions 43 windows 79 panes
9. backup-20220908T092341.125258.tar.zst 2 days retainable 654.76 kB 1.0 16 sessions 43 windows 79 panes
8. backup-20220909T224742.781818.tar.zst 18 hours retainable 599.64 kB 1.0 16 sessions 42 windows 77 panes
7. backup-20220909T225158.305403.tar.zst 18 hours retainable 600.32 kB 1.0 16 sessions 42 windows 79 panes
6. backup-20220910T152551.807672.tar.zst 1 hour retainable 608.79 kB 1.0 16 sessions 43 windows 80 panes
5. backup-20220910T165118.250800.tar.zst 29 minutes retainable 614.16 kB 1.0 16 sessions 43 windows 80 panes
4. backup-20220910T171812.893389.tar.zst 2 minutes retainable 614.33 kB 1.0 16 sessions 43 windows 80 panes
3. backup-20220910T172016.924711.tar.zst 11 seconds retainable 614.44 kB 1.0 16 sessions 43 windows 80 panes
2. backup-20220910T172019.320809.tar.zst 8 seconds retainable 614.42 kB 1.0 16 sessions 43 windows 80 panes
1. backup-20220910T172024.141993.tar.zst 3 seconds retainable 614.38 kB 1.0 16 sessions 43 windows 80 panes
11 backups: 10 retainable, 1 purgeable
If you installed the plugin config into tmux, then the default tmux bindings for listing backups are
prefix + b + l
to show the simple catalogprefix + b + L
to show the detailed catalog (adds the filesize, version & content columns)
Both of these bindings will open a tmux popup showing the catalog content.
Save the current tmux environment
$ tmux-backup save
✅ 16 sessions 43 windows 80 panes, persisted to `/Users/graelo/.local/state/tmux-backup/backup-20220910T171812.893389.tar.zst`
By default, the tmux binding for saving a new backup are
prefix + b + s
save and compact (delete purgeable backups)prefix + b + b
save but not compact the catalog
Both of these bindings will print the same report as above in the tmux status bar.
Restore from a backup
Typing tmux-backup restore
in your shell outside of tmux will
- start a tmux server if none is running
- restore all sessions from the latest backup
- but you still have to
tmux attach -t <your-last-session>
The same command typed in a shell inside tmux will erase session 0
(the default start
session) and restore your tmux environment in place.
By default, the tmux binding for restoring the latest backup is
prefix + b + r
restore sessions from the latest backup
Installation
Installing the binary
On macOS
brew install graelo/homebrew-tap/tmux-backup # will also install shell completions
On linux
curl \
https://github.com/graelo/tmux-backup/releases/download/v0.4.0/tmux-backup-x86_64-unknown-linux-gnu.tar.xz \
| tar xf - > /usr/local/bin/tmux-backup
chmod +x /usr/local/bin/tmux-backup
On linux, to install completions, type
tmux-backup generate-completion zsh|bash|fish > /path/to/your/completions/folder
Installing the tmux plugin hook
Type
mkdir ~/.tmux/plugins/tmux-backup
tmux-backup init > ~/.tmux/plugins/tmux-backup/tmux-backup.tmux
If you don't use tpm, just add this to your
.tmux.conf
:
source-file ~/.tmux/plugins/tmux-backup/tmux-backup.tmux
Alternatively, if you use tpm, declare the tmux-backup plugin to TPM in your ~/.tmux.conf
:
set -g @tpm_plugins ' \
tmux-plugins/tpm \
tmux-plugins/tmux-backup \ <-- here
tmux-plugins/tmux-copyrat \
tmux-plugins/tmux-yank \
tmux-plugins/tmux-resurrect \
tmux-plugins/tmux-sessionist \
'
The next time you start tmux, the tmux-backup.tmux
configuration will be loaded.
Caveats
- This is a beta version
- Does not handle multiple clients: help is welcome if you have clear scenarios for this.
- Does not handle session groups: help is also welcome.
License
Licensed under either of
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~14–25MB
~389K SLoC