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:
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.