DOCSEARCHbyAlgolia
Submit Docs

tmux-resurrect

repository·master·Indexed 12 days ago

https://github.com/tmux-plugins/tmux-resurrect

A tmux plugin that saves and restores your tmux environment, including sessions, windows, panes, layouts, and working directories, after a system restart. It supports custom key bindings, save/restore hooks, and configurable program restoration for tools like Vim, Neovim, and Emacs.

Tokens
4.5K
Snippets
15
Records
26
Agent score
94%

What's inside tmux-resurrect

  2. Use Save & Restore Hooks to run custom commands

    master
    Hooks allow you to execute custom shell commands during the tmux session save and restore processes. Most hooks receive no arguments, but some provide specific context (like the state file path) to your commands. You configure these by setting tmux options in your .tmux.conf using the @resurrect-hook-* prefix.

  3. Program restoration behavior and safety

    master

    When restoring a session, tmux-resurrect attempts to restart the programs that were active.

    • Default Behavior: To prevent accidental execution of destructive or resource-intensive processes, the plugin uses a conservative default list of programs (e.g., vim, less, tail, htop).
    • Customization: You can add more programs to the restoration list or, if preferred, use an option to prevent the restoration of any programs entirely.

  4. Understand usage differences between tmuxinator and tmux-resurrect

    master

    The two tools operate on different scopes:

    • tmuxinator: Focuses on managing individual tmux sessions (projects) via configuration files and CLI commands.
    • tmux-resurrect: Manages the entire tmux environment. It saves and restores all active sessions together as a single state.

    Workflow Adjustments

    When switching to tmux-resurrect, adopt these habits:

    • Keep sessions running: Instead of using a CLI to start a new project (e.g., mux new [project]), keep all your project sessions running in the background. Switch between them using prefix + s.
    • Avoid killing sessions: Do not use tmux kill-session for projects you intend to work on later. Simply leave them running; tmux-resurrect will handle the persistence.
    • Primary use cases: You only need to interact with tmux-resurrect when:
      1. Saving the environment immediately before shutting down or restarting your computer.
      2. Restoring the environment after booting up your computer.

  5. How to use tilde, arrow, and asterisk for program restoration

    master

    When tmux-resurrect saves a session, it often saves the absolute path to the executable (e.g., /usr/bin/ruby script/rails server). A simple string match like rails server will fail because it doesn't match the full path. Use these symbols to fix matching and command appearance:

    1. ~ (Tilde): Enables partial matching. "~rails server" tells the plugin: "If the string rails server is found anywhere in the process name, restore it."
    2. -> (Arrow): Defines the command to be executed. "~rails server->rails server" restores the process but makes the command line look like rails server instead of the long absolute path.
    3. * (Asterisk): Preserves arguments. "~rails server->rails server *" ensures that if you ran rails server -p 3000, the -p 3000 part is also restored.

    Debugging Workflow

    If a program isn't restoring:

    1. Set up your environment manually in tmux.
    2. Save the tmux environment.
    3. Open ~/.tmux/resurrect/last to find the exact, full process string used by the system.
    4. Use that string to construct your @resurrect-processes configuration using ~ and ->.

  6. What tmux-resurrect restores

    master

    The plugin saves and restores the following details of your tmux environment:

    • All sessions, windows, panes, and their order.
    • Current working directory for each pane.
    • Exact pane layouts within windows (including zoomed panes).
    • Active and alternative sessions.
    • Active and alternative windows for each session.
    • Windows with focus.
    • Active pane for each window.
    • "Grouped sessions" (useful for multiple monitors).
    • Programs running within a pane (see restoring programs for details).

    Optional features (require additional configuration):

    • Restoring Vim and Neovim sessions.
    • Restoring pane contents.
    • Restoring a previously saved environment.

  7. Migrate from tmuxinator to tmux-resurrect

    master

    If you are moving from tmuxinator to tmux-resurrect, follow these steps to transfer your current tmux environment state:

    1. Install tmux-resurrect.
    2. Open all existing tmuxinator projects in your current tmux environment.
    3. Verify all projects are open by pressing prefix + s and checking the session list.
    4. Perform a tmux-resurrect save.

    Once saved, tmux-resurrect will manage the state of all these sessions. You can then stop using tmuxinator for these projects.

  9. Install tmux-resurrect manually

    master

    If you do not use TPM, you can install the plugin manually:

    1. Clone the repository to a local directory (e.g., ~/clone/path).
    2. Add the following line to the bottom of your .tmux.conf file, replacing ~/clone/path with your actual path.
    3. Reload your tmux environment by running tmux source-file ~/.tmux.conf in your terminal.
    # 1. Clone the repo
$ git clone https://github.com/tmux-plugins/tmux-resurrect ~/clone/path

# 2. Add to .tmux.conf
run-shell ~/clone/path/resurrect.tmux

# 3. Reload tmux
$ tmux source-file ~/.tmux.conf

  11. Restore to a specific previous save point

    master

    Tmux Resurrect preserves all previous saves in the ~/.tmux/resurrect/ directory or ~/.local/share/tmux/resurrect (respecting ${XDG_DATA_HOME}). To restore to a specific point in time rather than the most recent save, follow these steps:

    1. Start a fresh tmux instance.
    2. Navigate to the resurrect directory: cd ~/.tmux/resurrect/ (or your specific data directory).
    3. Identify the timestamped save file you wish to restore.
    4. Create a symbolic link named last that points to your chosen save file: ln -sf <file_name> last
    5. Trigger the restore using the tmux-resurrect key binding: prefix + Ctrl-r.
    # Example: restoring a specific save from a timestamped file
cd ~/.tmux/resurrect/
ln -sf 202310271200 last
# Then in tmux:
# press prefix + Ctrl-r

  12. Restore NodeJS programs using Yarn

    master

    NodeJS tools like npm, gulp, or grunt often don't save their parameters in a way that tmux-resurrect can easily capture. A recommended workaround is to use yarn instead of npm or gulp directly, as it provides more consistent process visibility.

    Configuration Examples

    Using Yarn for watch commands:

    set -g @resurrect-processes '"~yarn watch"'
set -g @resurrect-processes '"~yarn watch->yarn watch"'

    Using Yarn for Gulp:

    set -g @resurrect-processes '"~yarn gulp test"'

    Using NVM with Gulp:

    set -g @resurrect-processes '"~yarn gulp test->nvm use && gulp test"'

    Handling Dash-separated commands

    If you have commands that differ only by a dash (e.g., gulp test and gulp test-it), tmux-resurrect might incorrectly truncate the second command. To fix this, wrap the argument in quotes in your config and ensure the ~/.tmux/resurrect/last file also contains quotes for that argument:

    set -g @resurrect-processes '"~yarn gulp "test-it"->gulp test-it"'