remi / Teamocil

Teamocil is a simple tool used to automatically create
windows and panes in tmux with YAML files.

Installation

# Install the `teamocil` Ruby gem
$ gem install teamocil

# Create your layout directory
$ mkdir ~/.teamocil

# Edit ~/.teamocil/sample.yml (look for sample layouts in this very `README.md`)
$ teamocil --edit sample

# Launch tmux
$ tmux

# Run your newly-created sample layout
$ teamocil sample

Usage

$ teamocil [options] [layout-name]

Global options

Layout options

Upgrading

Teamocil 1.0 is a complete rewrite (from scratch!) of Teamocil. The code is now very much simpler, cleaner and easier to maintain.

The downside of that is that several features were dropped during the rewrite process, mostly because I didn’t actually use/need them and I got tired of maintaining features I don’t think are useful.

You might have to clean up your layout files after upgrading to 1.0. I’m sorry about that. The documentation in README.md should help you find which keys are now supported.

The 0.4-stable branch is still available with the old code. Feel free to fork the repository and add back as many features as you want :)

Configuration

Session

Windows

Panes

A pane can either be a String or a Hash. If it’s a String, Teamocil will treat it as a single-command pane.

Examples

Simple two pane window

windows:
  - name: sample-two-panes
    root: ~/Code/sample/www
    layout: even-horizontal
    panes:
      - git status
      - rails server

.------------------.------------------.
| (0)              | (1)              |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Simple three pane window

windows:
  - name: sample-three-panes
    root: ~/Code/sample/www
    layout: main-vertical
    panes:
      - vim
      - commands:
        - git pull
        - git status
      - rails server

.------------------.------------------.
| (0)              | (1)              |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |------------------|
|                  | (2)              |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Simple four pane window

windows:
  - name: sample-four-panes
    root: ~/Code/sample/www
    layout: tiled
    panes:
      - vim
      - foreman start web
      - git status
      - foreman start worker

.------------------.------------------.
| (0)              | (1)              |
|                  |                  |
|                  |                  |
|                  |                  |
|------------------|------------------|
| (2)              | (3)              |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Two pane window with focus in second pane

windows:
  - name: sample-two-panes
    root: ~/Code/sample/www
    layout: even-horizontal
    panes:
      - rails server
      - commands:
          - rails console
        focus: true

.------------------.------------------.
| (0)              | (1) <focus here> |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
|                  |                  |
'------------------'------------------'

Extras

Zsh autocompletion

To get autocompletion when typing teamocil <Tab> in a zsh session, add this line to your ~/.zshrc file:

compctl -g '~/.teamocil/*(:t:r)' teamocil

zsh-completions also provides additional completion definitions for Teamocil.

Bash autocompletion

To get autocompletion when typing teamocil <Tab> in a bash session, add this line to your ~/.bashrc file:

complete -W "$(teamocil --list)" teamocil

Fish autocompletion

To get autocompletion when typing teamocil <Tab> in a fish session, add the following file ~/.config/fish/completions/teamocil.fish with the following content:

complete -x -c teamocil -a '(teamocil --list)'

Custom window layout

Teamocil supports all the window layout names supported by tmux.

• even-horizontal
• even-vertical
• main-horizontal
• main-vertical
• tiled

However, it also supports the custom format understood by tmux. This is especially useful if you want to manually resize your panes and keep using that layout in the future.

You can grab the layout for the current window by running this command:

tmux list-windows -F "#{window_active} #{window_layout}" | grep "^1" | cut -d " " -f 2

You can then use the result as the layout key for any Teamocil window object.

windows:
  - name: sample-two-uneven-panes
    layout: 00c7,158x38,0,0[158x9,0,0,37,158x28,0,10,39]
    panes:
      - echo foo
      - echo bar

Contributors

Feel free to contribute and submit issues/pull requests on GitHub, just like these fine folks did:

• @garno
• @jbourassa
• @bdimcheff
• @jscheel
• @mklappstuhl

License

Teamocil is © 2011-2016 Rémi Prévost and may be freely distributed under the MIT license. See the LICENSE.md file for more information.