https://github.com/urbainvaes/vim-tmux-pilot
Unified navigation of splits and tabs in nvim and tmux
https://github.com/urbainvaes/vim-tmux-pilot
tmux vim
Last synced: about 1 year ago
JSON representation
Unified navigation of splits and tabs in nvim and tmux
- Host: GitHub
- URL: https://github.com/urbainvaes/vim-tmux-pilot
- Owner: urbainvaes
- License: mit
- Created: 2018-04-11T18:26:46.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-06-04T12:28:10.000Z (about 6 years ago)
- Last Synced: 2025-03-25T09:47:40.031Z (about 1 year ago)
- Topics: tmux, vim
- Language: Vim script
- Homepage:
- Size: 67.4 KB
- Stars: 87
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vim-tmux-pilot
Inspired by [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator),
this plugin further extends the `` mappings to switch between `vim` or `tmux` tabs when no `vim` or `tmux` split is available,
similarly to the behavior of the [i3](https://i3wm.org) window manager in a workspace with both tabs and splits.
It can additionally be configured to automatically create a container when there isn't any in the specified direction.
## Installation
I recommend using [vim-plug](https://github.com/junegunn/vim-plug)
and sourcing the appropriate file from `~/.tmux.conf`.
In `~/.vimrc`, add:
```vim
Plug 'urbainvaes/vim-tmux-pilot'
" Uncomment to enable navigation of vim tabs
" let g:pilot_mode='wintab'
" Uncomment to enable creation of vim splits automatically
" let g:pilot_boundary='create'
" Uncomment to use the modifier `Alt` instead of `Control`
" let g:pilot_key_h=''
" let g:pilot_key_j=''
" let g:pilot_key_k=''
" let g:pilot_key_l=''
" let g:pilot_key_p=''
```
In `~/.tmux.conf`, add:
```tmux
# Uncomment to enable navigation of tmux tabs
# PILOT_MODE=wintab
# Uncomment to enable creation of tmux splits automatically
# PILOT_BOUNDARY=create
# Uncomment to use the modifier `Alt` instead of `Control`
# PILOT_KEY_H='M-h'
# PILOT_KEY_J='M-j'
# PILOT_KEY_K='M-k'
# PILOT_KEY_L='M-l'
# PILOT_KEY_P='M-\'
PILOT_ROOT=$HOME/.vim/plugged/vim-tmux-pilot
source-file $PILOT_ROOT/pilot.tmux
# Add binding 'prefix C-l' to send 'C-l' to underlying program
bind C-l send-keys C-l
```
Note that the `$PILOT_ROOT` environment variable needs to be defined for the plugin to work,
and that it is important to use `$HOME` and not the tilde (`~`),
as tilde expansion won't be performed on `PILOT_ROOT`.
## Usage
To avoid ambiguities,
we use the simplified terminology {`vim`,`tmux`}-{splits,tabs} and
the abbreviations {v,t}{splits,tabs}
to refer to `vim`-{windows,tabs} and `tmux`-{panes,windows}, respectively.
The term "navigation space" is used to refer to the set of existing containers that can be accessed via the keys `c-{h,j,k,l}`;
see below for details.
In the general case where `vim` is used inside a `tmux` session,
the order of precedence when `` or `` is issued from `vim` is as follows:
| Config | `g:pilot_mode = 'winonly'` | `g:pilot_mode = 'wintab'` |
| ------ | ------- | ----------- |
| `PILOT_MODE=winonly` | vsplit → tsplit | vsplit → tsplit → vtab |
| `PILOT_MODE=wintab` | vsplit → tsplit → ttab | vsplit → tsplit → vtab → ttab |
The variable `g:pilot_precedence` can be set to `'vtab'` to give `vim` tabs a precedence higher than that of `tmux` splits when `g:pilot_mode == 'wintab'`.
This ensures a slightly more consistent behaviour,
in the sense that `` will always bring us back to where we started from.
When trying to move across a boundary of the navigation space,
i.e. when there isn't any container to move to in the specified direction,
the plugin will perform one of the following actions,
based on the configuration variables `g:pilot_boundary` and `PILOT_BOUNDARY`,
which need not coincide:
- If the behaviour at the boundary is set to **create**,
a container corresponding to the type of lowest precedence will be created.
This way, the behaviour is consistent between containers
(i.e. containers that are at the boundary of the navigation space do not receive more features for it).
In vim, the command employed to create a new horizontal (resp. vertical) window is either `split` (resp. `vsplit`) or `new` (resp. `vnew`),
depending on the value of `g:pilot_split_or_new`.
- If the behaviour at the boundary is set to **reflect**,
the focus will move to the opposite container of lowest precedence.
If there isn't one,
containers of higher precedence will be used,
or the key will be sent to the running program if no container is available.
- If the behaviour at the boundary is set to **ignore**,
the key is simply ignored (in `vim`)
or fed to the program running in the container (in `tmux`).
Internally, the `tmux` command `showenv [-g]` is used to read configuration variables,
so these variables can be changed on the fly from within `tmux` using the command `setenv [-g]`.
Variables in the local environment (declared without the `-g` flag)
take precedence over variables in the global environement.
For example, in a shell:
```bash
> # Set PILOT_BOUNDARY to 'create' for this session
> tmux setenv PILOT_BOUNDARY create
>
> # Set PILOT_BOUNDARY to 'reflect' for this and other sessions
> tmux setenv -g PILOT_BOUNDARY reflect
```
## Customization
In `vim`:
| Config | Default (other values) | Description |
| ------ | ------- | ----------- |
| `g:pilot_mode` | `'winonly'` (`'wintab`') | Mode of operation |
| `g:pilot_boundary` | `'ignore'` (`'create'`, `'reflect'`) | Boundary condition |
| `g:pilot_precedence` | `'tsplit'` (`'vtab'`) | Precedence between vtabs and tsplits |
| `g:pilot_split_or_new` | `new` (`split`) | Use `split` or `new` for new windows |
| `g:pilot_key_h` | `''` | Keybinding to left motion |
| `g:pilot_key_j` | `''` | Keybinding to down motion |
| `g:pilot_key_k` | `''` | Keybinding to up motion |
| `g:pilot_key_l` | `''` | Keybinding to right motion |
| `g:pilot_key_p` | `''` | Keybinding to to previous split |
In `tmux`:
| Config | Default (other values) | Description |
| ------ | ------- | ----------- |
| `PILOT_MODE` | `winonly` (`wintab`) | Mode of operation |
| `PILOT_BOUNDARY` | `ignore` (`create`, `reflect`) | Boundary condition |
| `PILOT_ROOT` | Empty (must be set) | Root directory of `vim-tmux-pilot` |
| `PILOT_IGNORE` | Empty | Applications to ignore |
| `PILOT_KEY_H` | `'C-h'` | Keybinding to left |
| `PILOT_KEY_J` | `'C-j'` | Keybinding to down |
| `PILOT_KEY_K` | `'C-k'` | Keybinding to up |
| `PILOT_KEY_L` | `'C-l'` | Keybinding to right |
| `PILOT_KEY_P` | `'C-\'` | Keybinding to previous split |
The keybindings defined in `vim` and `tmux` must coincide for the plugin to work.
## License
MIT