# `tmux-backup`
[](https://crates.io/crates/tmux-backup)
[](https://docs.rs/tmux-backup)
[](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
[](https://doc.rust-lang.org/edition-guide/rust-2024/index.html)
[](https://github.com/graelo/tmux-backup/actions/workflows/ci-essentials.yml)
A backup & restore solution for Tmux sessions.
Version requirement: _rustc 1.95+_
## 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).
- 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
```console
$ 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 catalog
- `prefix + 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
```console
$ 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
```shell
brew install graelo/homebrew-tap/tmux-backup # will also install shell completions
```
On linux, grab the standalone binary for your architecture from the
[latest release](https://github.com/graelo/tmux-backup/releases/latest)
(`x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`):
```shell
curl -L -o /usr/local/bin/tmux-backup \
https://github.com/graelo/tmux-backup/releases/latest/download/tmux-backup-x86_64-unknown-linux-musl
chmod +x /usr/local/bin/tmux-backup
```
Or download the archive — it bundles the binary together with the README
and license files. Pick the version explicitly:
```shell
VERSION=v0.5.16 # adjust to the desired release
curl -L https://github.com/graelo/tmux-backup/releases/download/"${VERSION}"/tmux-backup-"${VERSION}"-x86_64-unknown-linux-musl.tar.xz \
| tar -xJ
sudo install -m 755 tmux-backup-"${VERSION}"-x86_64-unknown-linux-musl/tmux-backup /usr/local/bin/
```
On linux, to install completions, type
```shell
### Verifying release artifacts
Every release artifact ships a build provenance attestation signed by
GitHub Actions. Verify a download before installing with the
[GitHub CLI](https://cli.github.com/):
```shell
# Standalone binary
gh attestation verify tmux-backup-x86_64-unknown-linux-musl \
--repo graelo/tmux-backup
# Archive
gh attestation verify tmux-backup-v0.5.16-x86_64-unknown-linux-musl.tar.xz \
--repo graelo/tmux-backup
```
Both `.zip` and `.tar.xz` archives plus the standalone binaries for every
target are covered.
### Installing the tmux plugin hook
Type
```shell
mkdir ~/.tmux/plugins/tmux-backup
tmux-backup init > ~/.tmux/plugins/tmux-backup/tmux-backup.tmux
```
If you don't use [tpm](https://github.com/tmux-plugins/tpm), just add this to
your `.tmux.conf`:
```text
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`:
```tmux
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
- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- [MIT license](http://opensource.org/licenses/MIT)
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.