search

ethagnawl / rmuxinator

tmux session configuration utility
MIT License
54 stars 6 forks source link

readme

rmuxinator

Screenshot

What is this?

This project aims to be a successor to tmuxinator, which allows users to define tmux project profiles (e.g. open two windows, split each into three panes and run a series of commands in each). It is written in Rust and will be more dependable (config is typechecked where possible) and simpler to install. It's also a great excuse for me to learn more about Rust, its ecosystem and compiling/distributing binaries for various platforms.

TLDR; How do I use it?

Cargo

Source

cargo build

Documentation

Project Config

Projects are defined using toml.

For example:

attached = true
layout = "main-horizontal"
name = "example"
pane_name_user_option = "custom_pane_title"
start_directory = "/home/peter/projects/vim"
tmux_options = "-f /tmp/tmux.work.conf -L work-socket"

[[hooks]]
  command = "run-shell \"tmux display-message 'Hi from pane-focus-in hook!'\""
  name = "pane-focus-in"

[[windows]]
  layout = "tiled"
  name = "one"
  start_directory = "/home/peter/projects/sample-project"

  [[windows.panes]]
  commands = ["echo pane-one"]
  name = "Work"

  [[windows.panes]]
  commands = ["echo pane-two"]
  name = "Music"
  start_directory = "/home/peter/projects/rmuxinator/src"

  [[windows.panes]]
  commands = ["echo pane-three"]
  name = "RSS"

  [[windows.panes]]
  commands = ["echo hi one", "echo intermediate one", "echo bye one"]

[[windows]]
  name = "two"
  start_directory = "/home/peter/projects/sample-project"

  [[windows.panes]]
  commands = ["echo pane-one"]

  [[windows.panes]]
  commands = ["echo pane-two"]
  start_directory = "/home/peter/projects/rmuxinator/src"

  [[windows.panes]]
  commands = ["echo pane-three"]

  [[windows.panes]]
  commands = ["echo hi one", "echo intermediate one", "echo bye one"]

Configuration Options

Optional attributes will be noted below.

Project
Optional
Hooks
Windows
Optional
Panes
Optional

Commands

debug

Print the tmux commands that would be used to start and configure a tmux session using a path to a project config file: rmuxinator debug samples/Example.toml

start

Start a tmux session using a path to a project config file: rmuxinator start samples/Example.toml

Use as a library

rmuxinator can also be used as a library by other programs.

There are two ways to achieve this:

Config::new_from_config_path

This option accepts a path to an rmuxinator config file and is how the rmuxinator binary works. This is how this project's binary entrypoint works.

Example:

let config = rmuxinator::Config::new_from_config_path(&String::from("/home/pi/foo.toml")).map_err(|error| format!("Problem parsing config file: {}", error))?;
rmuxinator::run_start(config).map_err(|error| format!("Rmuxinator error: {}", error));

Config constructor

This option allows the caller to create an rmuxinator Config struct and then pass it to the run_start function.

The pi-wall-utils project (also maintained by ethagnawl) does this and can be used as a reference.

Example:

let rmuxinator_config = rmuxinator::Config {
    attached: true,
    hooks: vec![],
    layout: None,
    name: String::from("rmuxinator-library-example"),
    windows: vec![
        rmuxinator::Window {
            layout: None,
            name: None,
            panes: vec![rmuxinator::Pane {
                commands: vec![
                    String::from("echo 'hello!'"),
                ],
                name: None,
                start_directory: None,
            }],
            start_directory: None,
    }
    ];

};
rmuxinator::run_start(rmuxinator_config).map_err(|error| format!("Rmuxinator error: {}", error))

Known Issues and Workarounds

Custom Tmux Config

If you provide a custom tmux config file via tmux_options, you may need to restart your tmux server (tmux kill-server) before some/all of its changes will take effect. For example, changes to base-index and pane-base-index are known to require a restart in order to be detected and used as expected.

It might be possible to work around this issue but it needs more thought. The heavy handed option would be to have this library explicitly kill and restart the tmux server but that could have unintended consequences if other tmux sessions are in use.

Status

This project is currently a proof of concept and I'll be duplicating tmuxinator features and adding additional improvements as I can find time. Right now, it's capable of:

Still TODO:

Platforms

Here are the platforms rmuxinator is known to work on:

Resources