GitHub - remi/teamocil at 0.4-stable (original) (raw)

Teamocil

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

Usage

$ gem install teamocil $ mkdir ~/.teamocil $ teamocil --edit sample $ tmux $ teamocil sample

Options

• --here opens the session in the current window, do not create an empty first window.
• --layout takes a custom file path to a YAML layout file.
• --edit opens the layout file (whether or not --layout is used) with $EDITOR.
• --list lists all available layouts in ./.teamocil or $TEAMOCIL_PATH.
• --show show the layout content instead of executing it.

Layout file structure

A layout file is a single YAML file located in ~/.teamocil or $TEAMOCIL_PATH (eg. ~/.teamocil/my-project.yml).

Session

You can wrap your entire layout file in a session and Teamocil will rename the current session (so that you can find it more easily when running tmux list-sessions) before creating your windows.

Keys

• name (the name of the session)

Example

session: name: "my-awesome-session" windows: [windows list]

Windows

If you are not using a top-level session key, then the first key of your layout file will be windows, an array of window items.

Item keys

• name (the name that will appear in tmux statusbar)
• root (the directory in which every pane will be created)
• filters (a hash of before and after commands to run for each pane)
• clear (whether or not to prepend a clear command before the before filters list)
• layout (a layout name or serialized string supported by the tmux select-layout command)
• panes (an array of pane items)
• options (a hash of tmux options, see man tmux for a list)

Notes

If you want to use a custom value for the layout key, running this command will give you the layout of the current window:

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

You can then use the value as a string, like so:

• name: "a-window-with-weird-layout" layout: "4d71,204x51,0,0{101x51,0,0,114,102x51,102,0[102x10,102,0,118,102x40,102,11,115]}" panes: …

Example

windows:

• name: "my-first-window" clear: true options: synchronize-panes: true root: "~/Projects/foo-www" filters: before: - "echo 'Let’s use ruby-1.9.3 for each pane in this window.'" - "rbenv local 1.9.3-p374" panes: [panes list]
• name: "my-second-window" layout: tiled root: "~/Projects/foo-api" panes: [panes list]
• name: "my-third-window" layout: main-vertical root: "~/Projects/foo-daemons" panes: [panes list]

Panes

Every window must define an array of panes that will be created within it. A vertical or horizontal pane will be created, depending on whether the width or height parameter is used. If a layout option is used for the window, the width and height attributes won’t have any effect.

Item keys

• cmd (the commands to initially execute in the pane)
• width (the pane width, in percentage)
• height (the pane width, in percentage)
• target (the pane to set focus on before creating the current one)
• focus (the pane to set focus on after initializing all the panes for a window)

Example

windows:

• name: "my-first-window" root: "~/Projects/foo-www" layout: even-vertical filters: before: "rbenv local 2.0.0-p0" after: "echo 'I am done initializing this pane.'" panes:
  • cmd: "git status"
  • cmd: "bundle exec rails server --port 4000" focus: true
  • cmd:
    • "sudo service memcached start"
    • "sudo service mongodb start"

Layout examples

See more example files in the examples directory.

Simple two panes window

Content of ~/.teamocil/sample-1.yml

windows:

• name: "sample-two-panes" root: "~/Code/sample/www" layout: even-horizontal panes:
  • cmd: ["pwd", "ls -la"]
  • cmd: "rails server --port 3000"

Result of $ teamocil sample-1

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

Four tiled panes window

Content of ~/.teamocil/sample-2.yml

windows:

• name: "sample-four-panes" root: "~/Code/sample/www" layout: tiled panes:
  • cmd: "pwd"
  • cmd: "pwd"
  • cmd: "pwd"
  • cmd: "pwd"

Result of $ teamocil sample-2

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

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

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

ERB support

You can use ERB in your layouts. For example, you can use an environment variable in a layout like so:

windows:

• name: "erb-example" root: <%= ENV['MY_PROJECT_ROOT'] %> panes:
  • cmd: "pwd"

Todo list

• Making sure the layout is valid before executing it (ie. throw exceptions).
• Add more specs.

Contributors

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

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

Take a look at the spec folder before you do, and make sure bundle exec rake spec passes after your modifications :)

License

Teamocil is © 2011-2014 Rémi Prévost and may be freely distributed under the MIT license. See the LICENSE file.