Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jceb/vmux
vim/neovim session handler within tmux
https://github.com/jceb/vmux
Last synced: about 2 months ago
JSON representation
vim/neovim session handler within tmux
- Host: GitHub
- URL: https://github.com/jceb/vmux
- Owner: jceb
- License: gpl-3.0
- Created: 2016-05-24T04:59:34.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-18T10:06:21.000Z (over 1 year ago)
- Last Synced: 2024-07-11T20:13:45.794Z (2 months ago)
- Language: Python
- Size: 74.2 KB
- Stars: 86
- Watchers: 3
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# [vmux](http://github.com/jceb/vmux)
vim/neovim/kakoune session handler within tmux
# Demo
[](https://asciinema.org/a/46634)
# Features
- Each `tmux` session has its own editor session
- One global editor session can be started
- Suports [gvim, vim](http://vim.org/), [neovim](http://neovim.org/) and
[kakoune](http://kakoune.org/)
- Seamless integration with `gvim`, `vim`, `nvim`, `kak` through wrapper scripts
that directly call `vmux` - keep your muscle's memory :-)
- Once a session has been started in one editor, e.g. `nvim`, the session will
be reused even if another editor is called, e.g. `vim` or `kak`
- A new session is started if the old session doesn't exist anymore
- Automatically select tmux pane running the local or global vim session
# Installation
Python3 is required as well as `tmux` and `vim`, `gvim` or `nvim`.
## Via PyPI
Install `vmux` using `pip`:
```bash
pip install vmux
```
## From Source
Clone the repository and install vmux:
```bash
git clone https://github.com/jceb/vmux.git
cd vmux
make DESTDIR=~/.local install
# if wrapper scripts are desired, install them as well
make DESTDIR=~/.local all
# add ~/.local/bin to PATH variable
export PATH="${HOME}/.local/bin:${PATH}"
```
# Usage
Start editor session through `vmux` or `vim.vmux`, `nvim.vmux` and `gvim.vmux`
wrapper scripts:
```bash
tmux
vmux MYFILE
# split tmux window
vmux MY_OTHERFILE
```
Once a session has been started, it doesn't matter anymore which editor has been
used. `vmux` will open every file in the existing session even if a wrapper
script of a different editor is used.
# Customization
Define default editor:
```bash
# export environment variable VMUX_EDITOR, either vim or nvim
export VMUX_EDITOR=nvim
```
Define path to the real editor executables. This is required if the wrapper
scripts are used that will hide the real editors in `$PATH`.
```bash
export VMUX_REALEDITOR_GNVIM=/usr/bin/gnvim
export VMUX_REALEDITOR_GVIM=/usr/bin/gvim
export VMUX_REALEDITOR_KAK=/usr/bin/kak
export VMUX_REALEDITOR_NVIM=/usr/bin/nvim
export VMUX_REALEDITOR_NVIM_QT=/usr/bin/nvim-qt
export VMUX_REALEDITOR_NVR=/usr/bin/nvr
export VMUX_REALEDITOR_VIM=/usr/bin/vim
```
Define that a global session should be started. One global and multiple local
sessions can exists next to one another:
```bash
export VMUX_GLOBAL=1
```
Define that the tmux pane shall not be selected automatically:
```bash
export VMUX_NOT_SELECT_PANE=1
```
Define socket path for `nvim`:
```bash
export VMUX_NVIM_SESSION_DIR=~/.cache/nvim_sessions
```
Turn on debugging:
```bash
export VMUX_DEBUG=1
```
# How it works
When `vmux` is called, it defines a variable `VMUX_SESSION_` that is unique
to the current `tmux` session. The value of the variable is set to `` that
is used as session name for `vim.vmux` and `nvim.vmux`. Furthermore, the global
session that is started through `gvim.vmux` is stored in the environment
variables `VMUX_SESSION` and `VMUX_GLOBAL_PANE`. The session name is set to
`global`.
# Known issues
I noticed with neovim that the session socket doesn't always get removed when it
ends. This might causes vmux to permanently fail to start a new session. It can
be manually resolved by deleting the stalled socket file in neovim's session
folder.
# Similar projects
- [tmux-omnivim](https://github.com/andy-lang/tmux-omnivim) creates one global
session while `vmux` creates one session per `tmux` session and it also
supports one global session next to multiple local sessions.
- creates one global
- [neovim-remote](https://github.com/mhinz/neovim-remote)
[tmux-nvr](https://github.com/carlocab/tmux-nvr) creates one global session
while `vmux` creates one session per `tmux` session and it also supports one
global session next to multiple local sessions.