{"id":18625659,"url":"https://github.com/urbainvaes/vim-tmux-pilot","last_synced_at":"2025-04-11T04:32:38.170Z","repository":{"id":93072027,"uuid":"129136989","full_name":"urbainvaes/vim-tmux-pilot","owner":"urbainvaes","description":"Unified navigation of splits and tabs in nvim and tmux","archived":false,"fork":false,"pushed_at":"2020-06-04T12:28:10.000Z","size":69,"stargazers_count":87,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T09:47:40.031Z","etag":null,"topics":["tmux","vim"],"latest_commit_sha":null,"homepage":"","language":"Vim script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urbainvaes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-11T18:26:46.000Z","updated_at":"2023-05-17T13:24:46.000Z","dependencies_parsed_at":"2023-06-04T16:00:36.633Z","dependency_job_id":null,"html_url":"https://github.com/urbainvaes/vim-tmux-pilot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbainvaes%2Fvim-tmux-pilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbainvaes%2Fvim-tmux-pilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbainvaes%2Fvim-tmux-pilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbainvaes%2Fvim-tmux-pilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urbainvaes","download_url":"https://codeload.github.com/urbainvaes/vim-tmux-pilot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248345202,"owners_count":21088231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tmux","vim"],"created_at":"2024-11-07T04:35:33.122Z","updated_at":"2025-04-11T04:32:38.129Z","avatar_url":"https://github.com/urbainvaes.png","language":"Vim script","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vim-tmux-pilot\n\nInspired by [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator),\nthis plugin further extends the `\u003cc-{h,l}\u003e` mappings to switch between `vim` or `tmux` tabs when no `vim` or `tmux` split is available,\nsimilarly to the behavior of the [i3](https://i3wm.org) window manager in a workspace with both tabs and splits.\nIt can additionally be configured to automatically create a container when there isn't any in the specified direction.\n\n## Installation\n\nI recommend using [vim-plug](https://github.com/junegunn/vim-plug)\nand sourcing the appropriate file from `~/.tmux.conf`.\n\nIn `~/.vimrc`, add:\n```vim\nPlug 'urbainvaes/vim-tmux-pilot'\n\n\" Uncomment to enable navigation of vim tabs\n\" let g:pilot_mode='wintab'\n\n\" Uncomment to enable creation of vim splits automatically\n\" let g:pilot_boundary='create'\n\n\" Uncomment to use the modifier `Alt` instead of `Control`\n\" let g:pilot_key_h='\u003ca-h\u003e'\n\" let g:pilot_key_j='\u003ca-j\u003e'\n\" let g:pilot_key_k='\u003ca-k\u003e'\n\" let g:pilot_key_l='\u003ca-l\u003e'\n\" let g:pilot_key_p='\u003ca-\\\u003e'\n```\nIn `~/.tmux.conf`, add:\n```tmux\n# Uncomment to enable navigation of tmux tabs\n# PILOT_MODE=wintab\n\n# Uncomment to enable creation of tmux splits automatically\n# PILOT_BOUNDARY=create\n\n# Uncomment to use the modifier `Alt` instead of `Control`\n# PILOT_KEY_H='M-h'\n# PILOT_KEY_J='M-j'\n# PILOT_KEY_K='M-k'\n# PILOT_KEY_L='M-l'\n# PILOT_KEY_P='M-\\'\n\nPILOT_ROOT=$HOME/.vim/plugged/vim-tmux-pilot\nsource-file $PILOT_ROOT/pilot.tmux\n\n# Add binding 'prefix C-l' to send 'C-l' to underlying program\nbind C-l send-keys C-l\n```\nNote that the `$PILOT_ROOT` environment variable needs to be defined for the plugin to work,\nand that it is important to use `$HOME` and not the tilde (`~`),\nas tilde expansion won't be performed on `PILOT_ROOT`.\n\n## Usage\n\nTo avoid ambiguities,\nwe use the simplified terminology {`vim`,`tmux`}-{splits,tabs} and\nthe abbreviations {v,t}{splits,tabs}\nto refer to `vim`-{windows,tabs} and `tmux`-{panes,windows}, respectively.\nThe 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}`;\nsee below for details.\n\nIn the general case where `vim` is used inside a `tmux` session,\nthe order of precedence when `\u003cctrl-h\u003e` or `\u003cctrl-l\u003e` is issued from `vim` is as follows:\n\n| Config               | `g:pilot_mode = 'winonly'` | `g:pilot_mode = 'wintab'`     |\n| ------               | -------                    | -----------                   |\n| `PILOT_MODE=winonly` | vsplit → tsplit            | vsplit → tsplit → vtab        |\n| `PILOT_MODE=wintab`  | vsplit → tsplit → ttab     | vsplit → tsplit → vtab → ttab |\n\nThe 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'`.\nThis ensures a slightly more consistent behaviour,\nin the sense that `\u003cc-l\u003e\u003cc-h\u003e` will always bring us back to where we started from.\n\nWhen trying to move across a boundary of the navigation space,\ni.e. when there isn't any container to move to in the specified direction,\nthe plugin will perform one of the following actions,\nbased on the configuration variables `g:pilot_boundary` and `PILOT_BOUNDARY`,\nwhich need not coincide:\n\n- If the behaviour at the boundary is set to **create**,\n  a container corresponding to the type of lowest precedence will be created.\n  This way, the behaviour is consistent between containers\n  (i.e. containers that are at the boundary of the navigation space do not receive more features for it).\n  In vim, the command employed to create a new horizontal (resp. vertical) window is either `split` (resp. `vsplit`) or `new` (resp. `vnew`),\n  depending on the value of `g:pilot_split_or_new`.\n\n- If the behaviour at the boundary is set to **reflect**,\n  the focus will move to the opposite container of lowest precedence.\n  If there isn't one,\n  containers of higher precedence will be used,\n  or the key will be sent to the running program if no container is available.\n\n- If the behaviour at the boundary is set to **ignore**,\n  the key is simply ignored (in `vim`)\n  or fed to the program running in the container (in `tmux`).\n\nInternally, the `tmux` command `showenv [-g]` is used to read configuration variables,\nso these variables can be changed on the fly from within `tmux` using the command `setenv [-g]`.\nVariables in the local environment (declared without the `-g` flag)\ntake precedence over variables in the global environement.\nFor example, in a shell:\n```bash\n\u003e # Set PILOT_BOUNDARY to 'create' for this session\n\u003e tmux setenv PILOT_BOUNDARY create\n\u003e\n\u003e # Set PILOT_BOUNDARY to 'reflect' for this and other sessions\n\u003e tmux setenv -g PILOT_BOUNDARY reflect\n```\n\n## Customization\n\nIn `vim`:\n\n| Config                 | Default (other values)               | Description                          |\n| ------                 | -------                              | -----------                          |\n| `g:pilot_mode`         | `'winonly'` (`'wintab`')             | Mode of operation                    |\n| `g:pilot_boundary`     | `'ignore'` (`'create'`, `'reflect'`) | Boundary condition                   |\n| `g:pilot_precedence`   | `'tsplit'` (`'vtab'`)                | Precedence between vtabs and tsplits |\n| `g:pilot_split_or_new` | `new` (`split`)                      | Use `split` or `new` for new windows |\n| `g:pilot_key_h`        | `'\u003cc-h\u003e'`                            | Keybinding to left motion            |\n| `g:pilot_key_j`        | `'\u003cc-j\u003e'`                            | Keybinding to down motion            |\n| `g:pilot_key_k`        | `'\u003cc-k\u003e'`                            | Keybinding to up motion              |\n| `g:pilot_key_l`        | `'\u003cc-l\u003e'`                            | Keybinding to right motion           |\n| `g:pilot_key_p`        | `'\u003cc-\\\u003e'`                            | Keybinding to to previous split      |\n\nIn `tmux`:\n\n| Config           | Default (other values)         | Description                        |\n| ------           | -------                        | -----------                        |\n| `PILOT_MODE`     | `winonly` (`wintab`)           | Mode of operation                  |\n| `PILOT_BOUNDARY` | `ignore` (`create`, `reflect`) | Boundary condition                 |\n| `PILOT_ROOT`     | Empty (must be set)            | Root directory of `vim-tmux-pilot` |\n| `PILOT_IGNORE`   | Empty                          | Applications to ignore             |\n| `PILOT_KEY_H`    | `'C-h'`                        | Keybinding to left                 |\n| `PILOT_KEY_J`    | `'C-j'`                        | Keybinding to down                 |\n| `PILOT_KEY_K`    | `'C-k'`                        | Keybinding to up                   |\n| `PILOT_KEY_L`    | `'C-l'`                        | Keybinding to right                |\n| `PILOT_KEY_P`    | `'C-\\'`                        | Keybinding to previous split       |\n\nThe keybindings defined in `vim` and `tmux` must coincide for the plugin to work.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbainvaes%2Fvim-tmux-pilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furbainvaes%2Fvim-tmux-pilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbainvaes%2Fvim-tmux-pilot/lists"}