codehead / teamocil

There's no I in Teamocil. At least not where you think. Teamocil is a simple tool used to automatically create windows and panes in tmux with YAML files.

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

Option	Description
--list	Lists all available layouts in ~/.teamocil

Layout options

Option	Description
--layout	Takes a custom file path to a YAML layout file instead of [layout-name]
--here	Uses the current window as the layout’s first window
--edit	Opens the layout file with $EDITOR instead of executing it
--show	Shows the layout content instead of executing it

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

Key	Description
name	The tmux session name
windows	An Array of windows

Windows

Key	Description
name	The tmux window name (required)
root	The path where all panes in the window will be started
layout	The layout that will be set after all panes are created by Teamocil
panes	An Array of panes
focus	If set to true, the window will be selected after the layout has been executed
options	A Hash of options that will be set with the set-window-option command

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.

Key	Description
commands	An Array of commands that will be ran when the pane is created
focus	If set to true, the pane will be selected after the layout has been executed

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.