Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/remi/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.
https://github.com/remi/teamocil
tmux
Last synced: 28 days ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/remi/teamocil
- Owner: remi
- License: mit
- Created: 2011-02-05T18:09:52.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2021-03-10T12:26:11.000Z (over 3 years ago)
- Last Synced: 2024-10-14T13:06:17.928Z (28 days ago)
- Topics: tmux
- Language: Ruby
- Homepage:
- Size: 203 KB
- Stars: 2,354
- Watchers: 42
- Forks: 101
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-tmux - teamocil
README
Teamocil is a simple tool used to automatically create
windows and panes in tmux with YAML files.
---
## Installation
```bash
# 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
```bash
$ 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](https://github.com/remiprev/teamocil/tree/0.4-stable) 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
```yaml
windows:
- name: sample-two-panes
root: ~/Code/sample/www
layout: even-horizontal
panes:
- git status
- rails server
```
```
.------------------.------------------.
| (0) | (1) |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
'------------------'------------------'
```
### Simple three pane window
```yaml
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
```yaml
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
```yaml
windows:
- name: sample-two-panes
root: ~/Code/sample/www
layout: even-horizontal
panes:
- rails server
- commands:
- rails console
focus: true
```
```
.------------------.------------------.
| (0) | (1) |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
'------------------'------------------'
```
## Extras
### Zsh autocompletion
To get autocompletion when typing `teamocil ` in a zsh session, add this line to your `~/.zshrc` file:
```zsh
compctl -g '~/.teamocil/*(:t:r)' teamocil
```
[zsh-completions](https://github.com/zsh-users/zsh-completions) also provides
additional completion definitions for Teamocil.
### Bash autocompletion
To get autocompletion when typing `teamocil ` in a bash session, add this line to your `~/.bashrc` file:
```bash
complete -W "$(teamocil --list)" teamocil
```
### Fish autocompletion
To get autocompletion when typing `teamocil ` in a fish session,
add the following file `~/.config/fish/completions/teamocil.fish` with
the following content:
```fish
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:
```bash
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.
```yaml
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](https://github.com/remiprev/teamocil/issues), just like these fine
folks did:
* [@garno](https://github.com/garno)
* [@jbourassa](https://github.com/jbourassa)
* [@bdimcheff](https://github.com/bdimcheff)
* [@jscheel](https://github.com/jscheel)
* [@mklappstuhl](https://github.com/mklappstuhl)
## License
Teamocil is © 2011-2016 [Rémi Prévost](http://exomel.com) and may be freely
distributed under the [MIT license](https://github.com/remiprev/teamocil/blob/master/LICENSE.md).
See the `LICENSE.md` file for more information.