Tmuxinator
Create and manage tmux sessions easily.
Installation
gem install tmuxinator
Editor and Shell
tmuxinator uses your shell's default editor for opening files. If you're not sure what that is type:
echo $EDITOR
For me that produces "vim" If you want to change your default editor simply put a line in ~/.bashrc that changes it. Mine looks like this:
export EDITOR='vim'
tmux
The recommended version of tmux to use is 1.8. Your mileage may vary for earlier versions. Refer to the FAQ for any odd behaviour.
base-index
If you use a base-index
other than the default, please be sure to also set the pane-base-index
set-window-option -g pane-base-index 1
Completion
Download the appropriate completion file from the repo and source
the file.
The following are example where the completion file has been downloaded into
~/.bin
.
bash
Add the following to your ~/.bashrc
:
source ~/.bin/tmuxinator.bash
zsh
Add the following to your ~/.zshrc
:
source ~/.bin/tmuxinator.zsh
fish
Move tmuxinator.fish
to your completions
folder:
cp ~/.bin/tmuxinator.fish ~/.config/fish/completions/
Usage
A working knowledge of tmux is assumed. You should understand what windows and panes are in tmux. If not please consult the man pages for tmux.
Create a project
Create or edit your projects with:
tmuxinator new [project]
For editing you can also use tmuxinator open [project]
. new
is aliased to
o
,open
, e
, edit
and n
. Your default editor ($EDITOR
) is used to open the file.
If this is a new project you will see this default config:
# ~/.tmuxinator/sample.yml
name: sample
root: ~/
# Optional. tmux socket
# socket_name: foo
# Runs before everything. Use it to start daemons etc.
# pre: sudo /etc/rc.d/mysqld start
# Runs in each window and pane before window/pane specific commands. Useful for setting up interpreter versions.
# pre_window: rbenv shell 2.0.0-p247
# Pass command line options to tmux. Useful for specifying a different tmux.conf.
# tmux_options: -f ~/.tmux.mac.conf
# Change the command to call tmux. This can be used by derivatives/wrappers like byobu.
# tmux_command: byobu
# Specifies (by name or index) which window will be selected on project startup. If not set, the first window is used.
# startup_window: logs
windows:
- editor:
layout: main-vertical
panes:
- vim
- guard
- server: bundle exec rails s
- logs: tail -f log/development.log
Windows
The windows option allows the specification of any number of tmux windows. Each window is denoted by a YAML array entry, followed by a name and command to be run.
windows:
- editor: vim
Window specific root
An optional root option can be specified per window:
name: test
root: ~/projects/company
windows:
- small_project:
root: ~/projects/company/small_project
panes:
- start this
- start that
This takes precedence over the main root option.
Panes
Note that if you wish to use panes, make sure that you do not have .
in your project name. tmux uses .
to delimit between window and pane indices,
and tmuxinator uses the project name in combination with these indices to target the correct pane or window.
Panes are optional and are children of window entries, but unlike windows, they do not need a name. In the following example, the editor
window has 2 panes, one running vim, the other guard.
windows:
- editor:
layout: main-vertical
panes:
- vim
- guard
The layout setting gets handed down to tmux directly, so you can choose from one of the five standard layouts or specify your own.
Interpreter Managers & Environment Variables
To use tmuxinator with rbenv, RVM, NVM etc, use the pre_window
option.
pre_window: rbenv shell 2.0.0-p247
These command(s) will run before any subsequent commands in all panes and windows.
Passing directly to send-keys
tmuxinator passes commands directly to send keys. This differs from simply chaining commands together using &&
or ;
, in that
tmux will directly send the commands to a shell as if you typed them in. This allows commands to be executed on a remote server over
SSH for example.
To support this both the window and pane options can take an array as an argument:
name: sample
root: ~/
windows:
- stats:
- ssh stats@example.com
- tail -f /var/log/stats.log
- logs:
layout: main-vertical
panes:
- logs:
- ssh logs@example.com
- cd /var/logs
- tail -f development.log
ERB
Project files support ERB for reusability across environments. Eg:
root: <%= ENV["MY_CUSTOM_DIR"] %>
Starting a session
This will fire up tmux with all the tabs and panes you configured.
tmuxinator start [project]
Shorthand
A shorthand alias for tmuxinator can also be used.
mux [command]
Other Commands
Copy an existing project. Aliased to c
and cp
tmuxinator copy [existing] [new]
List all the projects you have configured. Aliased to l
and ls
tmuxinator list
Remove a project. Aliased to rm
tmuxinator delete [project]
Remove all tmuxinator configs, aliases and scripts. Aliased to i
tmuxinator implode
Examines your environment and identifies problems with your configuration
tmuxinator doctor
Shows tmuxinator's help. Aliased to h
tmuxinator help
Shows the shell commands that get executed for a project
tmuxinator debug [project]
Shows tmuxinator's version.
tmuxinator version
FAQ
Window names are not displaying properly?
Add export DISABLE_AUTO_TITLE=true
to your .zshrc
or .bashrc
Contributing
To contribute, please read the contributing guide.
Copyright
Copyright (c) 2010-2014 Allen Bargi, Christopher Chow. See LICENSE for further details.