12/4/2016

GitHub - tmuxinator/tmuxinator: Manage complex tmux sessions easily

Personal Open source Business Explore

Pricing Blog Support

tmuxinator / tmuxinator
Code

Issues 46

Watch 152

Pull requests 10

Projects 0

Pulse

Sign in

This repository Search

Star 6,007

Sign up
Fork 392

Graphs

Manage complex tmux sessions easily

611 commits
Branch: master

4 branches

29 releases

98 contributors

New pull request

Find file

J3RN committed on GitHub Merge pull request #464 from seanmalloy/testmoretmuxversions

bin
completion
lib
spec
.gitignore
.rspec
.rubocop.yml
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
Gemfile
LICENSE
README.md
Rakefile
code_of_conduct.md
tmuxinator.gemspec

MIT
Clone or download

Latest commit 6df10d1 on Oct 12

Alias mux to tmuxinator; Remove mux symlink.

Completion scripts do not need execute perm.
Updated Changelog for 0.9.0
introduce and use noroot fixture/factory in project_spec
Ignore tags file.
Update to RSpec 3.0.
Add rubocop linter exception
Update TravisCI matrix and Gem deps
Update TravisCI matrix and Gem deps
Suggest contributors use 'rake test'
Update TravisCI matrix and Gem deps
Bump year to 2016
Remove name duplication
Removed Hound tasks
adding j3rn's email to COC
Update TravisCI matrix and Gem deps

4 months ago
4 months ago
2 months ago
2 months ago
3 years ago
3 years ago
6 months ago
2 months ago
2 months ago
8 months ago
2 months ago
11 months ago
3 months ago
8 months ago
9 months ago
2 months ago

README.md

Tmuxinator
gemversion

0.9.0

coverage 99%

codeclimate 2.3

dependencies outofdate

gitter joinchat

Create and manage tmux sessions easily.

https://github.com/tmuxinator/tmuxinator

1/7

12/4/2016

GitHub - tmuxinator/tmuxinator: Manage complex 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.

baseindex

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.
https://github.com/tmuxinator/tmuxinator

2/7

12/4/2016

bash

GitHub - tmuxinator/tmuxinator: Manage complex tmux sessions easily

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. Please note
that dots can't be used in project names as tmux uses them internally to delimit between windows and panes. 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.
# tmux_command: byobu

This can be used by derivatives/wrappers like 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

https://github.com/tmuxinator/tmuxinator

3/7

12/4/2016

GitHub - tmuxinator/tmuxinator: Manage complex tmux sessions easily

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.
https://github.com/tmuxinator/tmuxinator

4/7

12/4/2016

GitHub - tmuxinator/tmuxinator: Manage complex tmux sessions easily

Custom attachment and post commands

You can set tmuxinator to skip autoattaching to the session by using the attach option.
attach: false

You can also run arbitrary commands by using the post option. This is useful if you want to attach to tmux in a non
standard way (e.g. for a program that makes use of tmux control mode like iTerm2).
post: tmux -CC attach

Passing directly to sendkeys

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"] %>

You can also pass arguments to your projects, and access them with ERB. Simple arguments are available in an array
named @args.
Eg:
$ tmuxinator start project foo

# ~/.tmuxinator/project.yml
name: project
root: ~/<%= @args[0] %>
...

You can also pass keyvalue pairs using the format key=value. These will be available in a hash named @settings.
https://github.com/tmuxinator/tmuxinator

5/7

12/4/2016

Eg:

GitHub - tmuxinator/tmuxinator: Manage complex tmux sessions easily

$ tmuxinator start project workspace=~/workspace/todo

# ~/.tmuxinator/project.yml
name: project
root: ~/<%= @settings["workspace"] %>
...

Starting a session
This will fire up tmux with all the tabs and panes you configured.
tmuxinator start [project] -n [name]

If you use the optional [name] argument, it will start a new tmux session with the custom name provided. This is to
enable reuse of a project without tmux session name collision.
If there is a ./.tmuxinator.yml file in the current working directory but not a named project file in ~/.tmuxinator,
tmuxinator will use the local file. This is primarily intended to be used for sharing tmux configurations in complex
development environments.

Shorthand

The shell completion files also include a shorthand alias for tmuxinator that can be used in place of the full name.
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

https://github.com/tmuxinator/tmuxinator

6/7

12/4/2016

GitHub - tmuxinator/tmuxinator: Manage complex tmux sessions easily

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) 20102016 Allen Bargi, Christopher Chow. See LICENSE for further details.

2016 GitHub, Inc. Terms Privacy Security Status Help

https://github.com/tmuxinator/tmuxinator

Contact GitHub API Training Shop Blog About

7/7