# Tmuxinator [![Gem Version](https://badge.fury.io/rb/tmuxinator.svg)](http://badge.fury.io/rb/tmuxinator) [![Build Status](https://secure.travis-ci.org/tmuxinator/tmuxinator.png?branch=master)](http://travis-ci.org/tmuxinator/tmuxinator?branch=master) [![Coverage Status](https://img.shields.io/coveralls/tmuxinator/tmuxinator.svg)](https://coveralls.io/r/tmuxinator/tmuxinator?branch=master) [![Code Climate](https://codeclimate.com/github/tmuxinator/tmuxinator/badges/gpa.svg)](https://codeclimate.com/github/tmuxinator/tmuxinator) [![Dependency Status](https://gemnasium.com/tmuxinator/tmuxinator.svg)](https://gemnasium.com/tmuxinator/tmuxinator) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tmuxinator/tmuxinator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) Create and manage tmux sessions easily. <table> <tbody> <tr align="center"> <td> <img src="https://user-images.githubusercontent.com/289949/44366875-1a6cee00-a49c-11e8-9322-76e70df0c88b.gif" alt="Screenshot" width="80%" /> </td> </tr> </tbody> </table> ## Installation ### Ruby gems ``` gem install tmuxinator ``` ### Homebrew ``` brew install tmuxinator ``` ## Editor and Shell tmuxinator uses your shell's default editor for opening files. If you're not sure what that is type: ``` bash 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 or later, with the exception of 2.5, which is **not** supported (see [issue 536](https://github.com/tmuxinator/tmuxinator/issues/536) for details). Your mileage may vary for earlier versions. Refer to the FAQ for any odd behaviour. ## 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](http://manpages.ubuntu.com/manpages/precise/en/man1/tmux.1.html#contenttoc6) 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 `n`,`open` to `o`, and `edit` to `e`. 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: ```yaml # ~/.tmuxinator/sample.yml name: sample root: ~/ # Optional. tmux socket # socket_name: foo # Note that the pre and post options have been deprecated and will be replaced by # project hooks. # Project hooks # Runs on project start, always # on_project_start: command # Run on project start, the first time # on_project_first_start: command # Run on project start, after the first time # on_project_restart: command # Run on project exit ( detaching from tmux session ) # on_project_exit: command # Run on project stop # on_project_stop: command # 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. ```yaml windows: - editor: vim ``` ### Window specific root An optional root option can be specified per window: ```yaml 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. ```yaml 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](http://manpages.ubuntu.com/manpages/precise/en/man1/tmux.1.html#contenttoc6) or [specify your own](http://stackoverflow.com/a/9976282/183537). **Please note the indentation here is deliberate. YAML's indentation rules can be confusing, so if your config isn't working as expected, please check the indentation.** For a more detailed explanation of _why_ YAML behaves this way, see [this](https://stackoverflow.com/questions/50594758/why-isnt-two-spaced-yaml-parsed-like-four-spaced-yaml/50600253#50600253) Stack Overflow question. **Note:** If you're noticing inconsistencies when using a custom layout it may be due [#651](https://github.com/tmuxinator/tmuxinator/issues/651). See [this comment](https://github.com/tmuxinator/tmuxinator/issues/651#issuecomment-497780424) for a workaround. ## Interpreter Managers & Environment Variables To use tmuxinator with rbenv, RVM, NVM etc, use the `pre_window` option. ```yaml pre_window: rbenv shell 2.0.0-p247 ``` These command(s) will run before any subsequent commands in all panes and windows. ## Custom session attachment You can set tmuxinator to skip auto-attaching to the session by using the `attach` option. ```yaml attach: false ``` 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), you can run arbitrary commands by using a project hook: ```yaml on_project_exit: tmux -CC attach ``` ## 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: ```yaml name: sample root: ~/ windows: - stats: - ssh firstname.lastname@example.org - tail -f /var/log/stats.log - logs: layout: main-vertical panes: - logs: - ssh email@example.com - cd /var/logs - tail -f development.log ``` ## ERB Project files support [ERB](https://en.wikipedia.org/wiki/ERuby#erb) for reusability across environments. Eg: ```yaml 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: ```bash $ tmuxinator start project foo ``` ```yaml # ~/.tmuxinator/project.yml name: project root: ~/<%= @args %> ... ``` You can also pass key-value pairs using the format `key=value`. These will be available in a hash named `@settings`. Eg: ```bash $ tmuxinator start project workspace=~/workspace/todo ``` ```yaml # ~/.tmuxinator/project.yml name: project root: ~/<%= @settings["workspace"] %> ... ``` ## Starting a session This will fire up tmux with all the tabs and panes you configured, `start` is aliased to `s`. ``` tmuxinator start [project] -n [name] -p [project-config] ``` 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. You can provide tmuxinator with a project config file using the optional `[project-config]` argument (e.g. `--project-config=path/to/my-project.yaml` or `-p path/to/my-project.yaml`). This option will override a `[project]` name (if provided) and a local tmuxinator file (if present). ## Shorthand The [shell completion files](#completion) 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 ``` 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 ``` ## Project Configuration Location Using environment variables, it's possible to define which directory tmuxinator will use when creating or searching for project config files. (See [PR #511](https://github.com/tmuxinator/tmuxinator/pull/511).) Tmuxinator will attempt to use the following locations (in this order) when creating or searching for existing project configuration files: - `$TMUXINATOR_CONFIG` - `$XDG_CONFIG_HOME/tmuxinator` - `~/.tmuxinator` ## 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](https://github.com/tmuxinator/tmuxinator/blob/master/CONTRIBUTING.md). ## Copyright Copyright (c) 2010-2019 Allen Bargi, Christopher Chow. See LICENSE for further details.