Mucks

Assists with environment management when using tmux.

Installation

$ gem install mucks

Configuration

Two configuraiton files are required. They are expected to exist in ~/.mucks

Session (sessions.yaml)

This file contains a list of sessions, which may then contain values for one of two options. These options are mutually exclusive.

1. A list of other sessions to open.
2. A path and layout.
    * The path is the path that will be used in the session.
    * The layout is which layout will be used from the layout configuration.

A sessions.yaml might look something like this:

all:
  - user
  - mucks
user:
  path: '~'
  layout: base
mucks:
  path: ~/source/gems/mucks
  layout: mucks

This provides 3 sessions (all, user, and mucks).

  • all - A session comprised of other sessions (user and mucks)
  • user - A session that will have the user's home folder as the root and use the base layout.
  • mucks - A session that will have the user's home folder as the root and use the mucks layout.

Layout (layouts.yaml)

This file contains a list of layouts, which themselves may contain layouts.

These layouts are simply commands that will be run upon successful creation of a session.

A layouts.yaml might look something like this:

base:
  - tmux split-window -h -p 66

hg_layout:
  - tmux send-keys 'hg inall' C-m
  - tmux send-keys 'hg outall' C-m
  - tmux send-keys 'hg status' C-m

  - base
  - tmux select-pane  -t 1
  - tmux send-keys 'ruby ~/.vim/bundle/vim_test_runner/test_runner' C-m
  - tmux split-window -v -p 25
  - tmux select-pane  -t 3

mucks:
  - hg_layout
  - tmux send-keys 'vi ~/.mucks/layouts.yaml' C-m
  - tmux send-keys ':vsp ~/.mucks/sessions.yaml' C-m
  - tmux send-keys ':vsp lib/mucks/mucks.rb' C-m

Only base and mucks are used by sessions.yaml, but mucks references hg_layout, which in turn references base. These will all get interpolated when it is time to run the commands. mucks all -n would show the exact commands that would be executed.

set_path

This should only be useful when using tmux under cygwin. Linux-based operating systems honor the options that set the path for new sessions/windows

There is a special set_path command that will be replaced with the following command:

tmux send-keys 'cd "[session_path]"' C-m

where session_path is the path associated with the session that is being started.

A specific path may be used (instead of the session path) by simply including it after the set_path command.

All paths will be wrapped with quotes as shown above.

Running

You may chain sessions together or run them one at a time:

$ mucks foo bar -d

will do the same thing as:

$ mucks foo -d
$ mucks bar -d

By default, the user will be taken to the last session that is started. To prevent this, use the -d flag.

Command Line Options

  • -d (Detach) Do not attach to the last session in the list.
  • -v (Verbose) Detailed output about what is happening.
  • -n (Dry-Run) Do net execute any commands, simply output them to STDOUT.
  • -ls (List) List all sessions that are in sessions.yaml.

These commands may be used together in any combination, in any order, with the exception of -ls (it short-circuits, so any specified sessions will not be started).

You may also put them together in one chain (-dvn is the same as -d -v -n).

Did You Just Re-Invent Tmuxinator?

No.

To be fair, there was a point when I thought that's what I was doing. Mucks started as a teeny, tiny, lightweight script that was highly customized to my configuration and workflow, but it grew into something more useful as I DRY'd things up and wanted to use my tiny script across devices.

... so I packaged it up in a gem.

Disambiguation

I looked into using Tmuxinator prior to doing the work to make Mucks into a gem.

At that time, there was what I considered to be a major flaw. I have tried a number of layouts and will likely continue to try more. Tmuxinator makes it (too) hard to customize layouts, in my opinion. To get the same layout specified in hg_layout above, Tmuxinator would have you do this:

layout: e388,374x104,0,0{127x104,0,0[127x77,0,0,0,127x26,0,78,2],246x104,128,0,1}

At the time that Mucks was published, the Tmuxinator readme pointed to this link on StackOverflow explaining how to generate these values for custom layouts.

I have no idea what that line means or how to make minor adjustments to it. I know exactly what every line in layouts.yaml means and exactly how to change it to suit my whims.

Final Thought

I have outlined how to use Mucks and what I believe the major difference is between Mucks and Tmuxinator, but ultimately, it is up to you to determine which tool suits your needs best.

Contributions

The main repo is on Bitbucket, NOT on Github. Please open issues and make pull requests there.