<h1 align="center">nvim remote</h1>
<h6 align="center">forked from https://github.com/mhinz/neovim-remote</h6>
<p align='center'>
<img alt="PyPI - Version" src="https://img.shields.io/pypi/v/nvim-remote?style=for-the-badge&logo=pypi">
<img alt="GitHub tag (with filter)" src="https://img.shields.io/github/v/tag/1995parham/nvim-remote?style=for-the-badge&logo=github">
<img alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/1995parham/nvim-remote/ci.yml?style=for-the-badge&logo=github">
</p>
This package provides an executable called **nvr** which solves these cases:
- Controlling nvim processes from the shell. E.g. opening files in another
terminal window.
- Opening files from within `:terminal` without starting a nested nvim process.
---
- [Installation](#installation)
- [Theory](#theory)
- [First steps](#first-steps)
- [Typical use cases](#typical-use-cases)
- [Demos](#demos)
- [FAQ](#faq)
---
## Installation
```bash
pip3 install nvim-remote
pipx install nvim-remote
```
## Theory
`nvim` always starts a server. Get its address with `:echo v:servername`. Or
specify an address at startup: `nvim --listen /tmp/nvimsocket`.
`nvr` (the client) will use any address given to it via `--servername`,
`$NVIM_LISTEN_ADDRESS` (obsolete in nvim but still supported in `nvr`), or
defaults to `/tmp/nvimsocket`.
If the targeted address does not exist, `nvr` starts a new process by running
"nvim". You can change the command by setting `$NVR_CMD`. _(This requires
forking, so it won't work on Windows.)_
## First steps
Start a nvim process (which acts as a server) in one shell:
```bash
nvim --listen /tmp/nvimsocket
```
And do this in another shell:
```bash
# nvr uses /tmp/nvimsocket by default, so we're good.
# Open two files:
nvr --remote file1 file2
# Send keys to the current buffer:
nvr --remote-send 'iabc<esc>'
# Enter insert mode, insert 'abc', and go back to normal mode again.
# Evaluate any VimL expression, e.g. get the current buffer:
nvr --remote-expr 'bufname("")'
README.md
```
<details>
<summary>click here to see all nvr options</summary>
```bash
$ nvr -h
usage: nvr [arguments]
Remote control Neovim processes.
If no process is found, a new one will be started.
$ nvr --remote-send 'iabc<cr><esc>'
$ nvr --remote-expr 'map([1,2,3], "v:val + 1")'
Any arguments not consumed by options will be fed to --remote-silent:
$ nvr --remote-silent file1 file2
$ nvr file1 file2
All --remote options take optional commands.
Exception: --remote-expr, --remote-send.
$ nvr +10 file
$ nvr +'echomsg "foo" | echomsg "bar"' file
$ nvr --remote-tab-wait +'set bufhidden=delete' file
Open files in a new window from a terminal buffer:
$ nvr -cc split file1 file2
Use nvr from git to edit commit messages:
$ git config --global core.editor 'nvr --remote-wait-silent'
optional arguments:
-h, --help show this help message and exit
--remote [<file> [<file> ...]]
Use :edit to open files. If no process is found, throw
an error and start a new one.
--remote-wait [<file> [<file> ...]]
Like --remote, but block until all buffers opened by
this option get deleted or the process exits.
--remote-silent [<file> [<file> ...]]
Like --remote, but throw no error if no process is
found.
--remote-wait-silent [<file> [<file> ...]]
Combines --remote-wait and --remote-silent.
--remote-tab [<file> [<file> ...]]
Like --remote, but use :tabedit.
--remote-tab-wait [<file> [<file> ...]]
Like --remote-wait, but use :tabedit.
--remote-tab-silent [<file> [<file> ...]]
Like --remote-silent, but use :tabedit.
--remote-tab-wait-silent [<file> [<file> ...]]
Like --remote-wait-silent, but use :tabedit.
--remote-send <keys> Send key presses.
--remote-expr <expr> Evaluate expression and print result in shell.
--servername <addr> Set the address to be used. This overrides the default
"/tmp/nvimsocket" and $NVIM_LISTEN_ADDRESS.
--serverlist Print the TCPv4 and Unix domain socket addresses of
all nvim processes.
-cc <cmd> Execute a command before every other option.
-c <cmd> Execute a command after every other option.
-d Diff mode. Use :diffthis on all to be opened buffers.
-l Change to previous window via ":wincmd p".
-o <file> [<file> ...]
Open files via ":split".
-O <file> [<file> ...]
Open files via ":vsplit".
-p <file> [<file> ...]
Open files via ":tabedit".
-q <errorfile> Read errorfile into quickfix list and display first
error.
-s Silence "no server found" message.
-t <tag> Jump to file and position of given tag.
--nostart If no process is found, do not start a new one.
--version Show the nvr version.
Development: https://github.com/mhinz/neovim-remote
Happy hacking!
```
</details>
## Typical use cases
- **Open files from within `:terminal` without starting a nested nvim process.**
Easy-peasy! Just `nvr file`.
This works without any prior setup, because `$NVIM` is always set for all
children of the nvim process, including `:terminal`, and `nvr` will default
to that address.
I often work with two windows next to each other. If one contains the
terminal, I can use `nvr -l foo` to open the file in the other window.
- **Open files always in the same nvim process no matter which terminal you're in.**
Just `nvr -s` starts a new nvim process with the server address set to
`/tmp/nvimsocket`.
Now, no matter which terminal you are in, `nvr file` will always work on
that nvim process. That is akin to `emacsclient` from Emacs.
- **Use nvr in plugins.**
Some plugins rely on the `--remote` family of options from Vim. Nvim had to
remove those when they switched to outsource a lot of manual code to libuv.
These options are [planned to be added back](https://github.com/neovim/neovim/issues/1750), though.
In these cases nvr can be used as a drop-in replacement. E.g.
[vimtex](https://github.com/lervag/vimtex) can be configured to use nvr to
jump to a certain file and line: [read](https://github.com/lervag/vimtex/blob/80b96c13fe9edc5261e9be104fe15cf3bdc3173d/doc/vimtex.txt#L1702-L1708).
- **Use nvr as git editor.**
Imagine Neovim is set as your default editor via `$VISUAL` or `$EDITOR`.
Running `git commit` in a regular shell starts a nvim process. But in a
terminal buffer (`:terminal`), a new nvim process starts as well. Now you
have one nvim nested within another.
If you do not want this, put this in your vimrc:
```vim
if has('nvim')
let $GIT_EDITOR = 'nvr -cc split --remote-wait'
endif
```
That way, you get a new window for inserting the commit message instead of a
nested nvim process. But git still waits for nvr to finish, so make sure to
delete the buffer after saving the commit message: `:w | bd`.
If you don't like using `:w | bd` and prefer the good old `:wq` (or `:x`),
put the following in your vimrc:
```vim
autocmd FileType gitcommit,gitrebase,gitconfig set bufhidden=delete
```
To use nvr from a regular shell as well:
git config --global core.editor 'nvr --remote-wait-silent'
- **Use nvr as git mergetool.**
If you want to use nvr for `git difftool` and `git mergetool`, put this in
your gitconfig:
```
[diff]
tool = nvr
[difftool "nvr"]
cmd = nvr -s -d $LOCAL $REMOTE
[merge]
tool = nvr
[mergetool "nvr"]
cmd = nvr -s -d $LOCAL $BASE $REMOTE $MERGED -c 'wincmd J | wincmd ='
```
`nvr -d` is a shortcut for `nvr -d -O` and acts like `vim -d`, thus it uses
`:vsplit` to open the buffers. If you want them to be opened via `:split`
instead, use `nvr -d -o`.
When used as mergetool and all four buffers got opened, the cursor is in the
window containing the $MERGED buffer. We move it to the bottom via `:wincmd
J` and then equalize the size of all windows via `:wincmd =`.
- **Use nvr for scripting.**
You might draw some inspiration from [this Reddit
thread](https://www.reddit.com/r/neovim/comments/aex45u/integrating_nvr_and_tmux_to_use_a_single_tmux_per).
## Demos
_(Click on the GIFs to watch them full-size.)_
Using nvr from another shell: 
Using nvr from within `:terminal`: 
## FAQ
- **How to open directories?**
`:e /tmp` opens a directory view via netrw. Netrw works by hooking into certain
events, `BufEnter` in this case (see `:au FileExplorer` for all of them).
Unfortunately Neovim's API doesn't trigger any autocmds on its own, so simply
`nvr /tmp` won't work. Meanwhile you can work around it like this:
nvr /tmp -c 'doautocmd BufEnter'
- **Reading from stdin?**
Yes! E.g. `echo "foo\nbar" | nvr -o -` and `cat file | nvr --remote -` work just
as you would expect them to work.
- **Exit code?**
If you use a [recent enough
Neovim](https://github.com/neovim/neovim/commit/d2e8c76dc22460ddfde80477dd93aab3d5866506), nvr will use the same exit code as the linked nvim.
E.g. `nvr --remote-wait <file>` and then `:cquit` in the linked nvim will make
nvr return with 1.
- **How to send a message to all waiting clients?**
If you open a buffer with any of the _wait_ options, that buffer will get a
variable `b:nvr`. The variable contains a list of channels wheres each
channel is a waiting nvr client.
Currently nvr only understands the `Exit` message. You could use it to
disconnect all waiting nvr clients at once:
```vim
command! DisconnectClients
\ if exists('b:nvr')
\| for client in b:nvr
\| silent! call rpcnotify(client, 'Exit', 1)
\| endfor
\| endif
```
- **Can I have auto-completion for bash/fish?**
If you want basic auto-completion for bash, you can source [this
script](contrib/completion.bash) in your .bashrc.
This also completes server names with the `--servername` option.
If you want auto-completion for fish, you can add [this
file](contrib/completion.fish) to your fish completions dir.
Raw data
{
"_id": null,
"home_page": "https://github.com/1995parham/nvim-remote",
"name": "nvim-remote",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "nvim-remote,neovim-remote,nvr",
"author": "Parham Alvani",
"author_email": "parham.alvani@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c6/a1/e45712f25c4464d1fe4ddd8f606fd6ee7c465eaabdc738419fef2a62345f/nvim_remote-4.0.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">nvim remote</h1>\n<h6 align=\"center\">forked from https://github.com/mhinz/neovim-remote</h6>\n<p align='center'>\n <img alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/nvim-remote?style=for-the-badge&logo=pypi\">\n <img alt=\"GitHub tag (with filter)\" src=\"https://img.shields.io/github/v/tag/1995parham/nvim-remote?style=for-the-badge&logo=github\">\n <img alt=\"GitHub Workflow Status (with event)\" src=\"https://img.shields.io/github/actions/workflow/status/1995parham/nvim-remote/ci.yml?style=for-the-badge&logo=github\">\n</p>\n\nThis package provides an executable called **nvr** which solves these cases:\n\n- Controlling nvim processes from the shell. E.g. opening files in another\n terminal window.\n- Opening files from within `:terminal` without starting a nested nvim process.\n\n---\n\n- [Installation](#installation)\n- [Theory](#theory)\n- [First steps](#first-steps)\n- [Typical use cases](#typical-use-cases)\n- [Demos](#demos)\n- [FAQ](#faq)\n\n---\n\n## Installation\n\n```bash\npip3 install nvim-remote\n\npipx install nvim-remote\n```\n\n## Theory\n\n`nvim` always starts a server. Get its address with `:echo v:servername`. Or\nspecify an address at startup: `nvim --listen /tmp/nvimsocket`.\n\n`nvr` (the client) will use any address given to it via `--servername`,\n`$NVIM_LISTEN_ADDRESS` (obsolete in nvim but still supported in `nvr`), or\ndefaults to `/tmp/nvimsocket`.\n\nIf the targeted address does not exist, `nvr` starts a new process by running\n\"nvim\". You can change the command by setting `$NVR_CMD`. _(This requires\nforking, so it won't work on Windows.)_\n\n## First steps\n\nStart a nvim process (which acts as a server) in one shell:\n\n```bash\nnvim --listen /tmp/nvimsocket\n```\n\nAnd do this in another shell:\n\n```bash\n# nvr uses /tmp/nvimsocket by default, so we're good.\n\n# Open two files:\nnvr --remote file1 file2\n\n# Send keys to the current buffer:\nnvr --remote-send 'iabc<esc>'\n# Enter insert mode, insert 'abc', and go back to normal mode again.\n\n# Evaluate any VimL expression, e.g. get the current buffer:\nnvr --remote-expr 'bufname(\"\")'\nREADME.md\n```\n\n<details>\n<summary>click here to see all nvr options</summary>\n\n```bash\n$ nvr -h\nusage: nvr [arguments]\n\nRemote control Neovim processes.\n\nIf no process is found, a new one will be started.\n\n $ nvr --remote-send 'iabc<cr><esc>'\n $ nvr --remote-expr 'map([1,2,3], \"v:val + 1\")'\n\nAny arguments not consumed by options will be fed to --remote-silent:\n\n $ nvr --remote-silent file1 file2\n $ nvr file1 file2\n\nAll --remote options take optional commands.\nException: --remote-expr, --remote-send.\n\n $ nvr +10 file\n $ nvr +'echomsg \"foo\" | echomsg \"bar\"' file\n $ nvr --remote-tab-wait +'set bufhidden=delete' file\n\nOpen files in a new window from a terminal buffer:\n\n $ nvr -cc split file1 file2\n\nUse nvr from git to edit commit messages:\n\n $ git config --global core.editor 'nvr --remote-wait-silent'\n\noptional arguments:\n -h, --help show this help message and exit\n --remote [<file> [<file> ...]]\n Use :edit to open files. If no process is found, throw\n an error and start a new one.\n --remote-wait [<file> [<file> ...]]\n Like --remote, but block until all buffers opened by\n this option get deleted or the process exits.\n --remote-silent [<file> [<file> ...]]\n Like --remote, but throw no error if no process is\n found.\n --remote-wait-silent [<file> [<file> ...]]\n Combines --remote-wait and --remote-silent.\n --remote-tab [<file> [<file> ...]]\n Like --remote, but use :tabedit.\n --remote-tab-wait [<file> [<file> ...]]\n Like --remote-wait, but use :tabedit.\n --remote-tab-silent [<file> [<file> ...]]\n Like --remote-silent, but use :tabedit.\n --remote-tab-wait-silent [<file> [<file> ...]]\n Like --remote-wait-silent, but use :tabedit.\n --remote-send <keys> Send key presses.\n --remote-expr <expr> Evaluate expression and print result in shell.\n --servername <addr> Set the address to be used. This overrides the default\n \"/tmp/nvimsocket\" and $NVIM_LISTEN_ADDRESS.\n --serverlist Print the TCPv4 and Unix domain socket addresses of\n all nvim processes.\n -cc <cmd> Execute a command before every other option.\n -c <cmd> Execute a command after every other option.\n -d Diff mode. Use :diffthis on all to be opened buffers.\n -l Change to previous window via \":wincmd p\".\n -o <file> [<file> ...]\n Open files via \":split\".\n -O <file> [<file> ...]\n Open files via \":vsplit\".\n -p <file> [<file> ...]\n Open files via \":tabedit\".\n -q <errorfile> Read errorfile into quickfix list and display first\n error.\n -s Silence \"no server found\" message.\n -t <tag> Jump to file and position of given tag.\n --nostart If no process is found, do not start a new one.\n --version Show the nvr version.\n\nDevelopment: https://github.com/mhinz/neovim-remote\n\nHappy hacking!\n```\n\n</details>\n\n## Typical use cases\n\n- **Open files from within `:terminal` without starting a nested nvim process.**\n\n Easy-peasy! Just `nvr file`.\n\n This works without any prior setup, because `$NVIM` is always set for all\n children of the nvim process, including `:terminal`, and `nvr` will default\n to that address.\n\n I often work with two windows next to each other. If one contains the\n terminal, I can use `nvr -l foo` to open the file in the other window.\n\n- **Open files always in the same nvim process no matter which terminal you're in.**\n\n Just `nvr -s` starts a new nvim process with the server address set to\n `/tmp/nvimsocket`.\n\n Now, no matter which terminal you are in, `nvr file` will always work on\n that nvim process. That is akin to `emacsclient` from Emacs.\n\n- **Use nvr in plugins.**\n\n Some plugins rely on the `--remote` family of options from Vim. Nvim had to\n remove those when they switched to outsource a lot of manual code to libuv.\n These options are [planned to be added back](https://github.com/neovim/neovim/issues/1750), though.\n\n In these cases nvr can be used as a drop-in replacement. E.g.\n [vimtex](https://github.com/lervag/vimtex) can be configured to use nvr to\n jump to a certain file and line: [read](https://github.com/lervag/vimtex/blob/80b96c13fe9edc5261e9be104fe15cf3bdc3173d/doc/vimtex.txt#L1702-L1708).\n\n- **Use nvr as git editor.**\n\n Imagine Neovim is set as your default editor via `$VISUAL` or `$EDITOR`.\n\n Running `git commit` in a regular shell starts a nvim process. But in a\n terminal buffer (`:terminal`), a new nvim process starts as well. Now you\n have one nvim nested within another.\n\n If you do not want this, put this in your vimrc:\n\n ```vim\n if has('nvim')\n let $GIT_EDITOR = 'nvr -cc split --remote-wait'\n endif\n ```\n\n That way, you get a new window for inserting the commit message instead of a\n nested nvim process. But git still waits for nvr to finish, so make sure to\n delete the buffer after saving the commit message: `:w | bd`.\n\n If you don't like using `:w | bd` and prefer the good old `:wq` (or `:x`),\n put the following in your vimrc:\n\n ```vim\n autocmd FileType gitcommit,gitrebase,gitconfig set bufhidden=delete\n ```\n\n To use nvr from a regular shell as well:\n\n git config --global core.editor 'nvr --remote-wait-silent'\n\n- **Use nvr as git mergetool.**\n\n If you want to use nvr for `git difftool` and `git mergetool`, put this in\n your gitconfig:\n\n ```\n [diff]\n tool = nvr\n [difftool \"nvr\"]\n cmd = nvr -s -d $LOCAL $REMOTE\n [merge]\n tool = nvr\n [mergetool \"nvr\"]\n cmd = nvr -s -d $LOCAL $BASE $REMOTE $MERGED -c 'wincmd J | wincmd ='\n ```\n\n `nvr -d` is a shortcut for `nvr -d -O` and acts like `vim -d`, thus it uses\n `:vsplit` to open the buffers. If you want them to be opened via `:split`\n instead, use `nvr -d -o`.\n\n When used as mergetool and all four buffers got opened, the cursor is in the\n window containing the $MERGED buffer. We move it to the bottom via `:wincmd\nJ` and then equalize the size of all windows via `:wincmd =`.\n\n- **Use nvr for scripting.**\n\n You might draw some inspiration from [this Reddit\n thread](https://www.reddit.com/r/neovim/comments/aex45u/integrating_nvr_and_tmux_to_use_a_single_tmux_per).\n\n## Demos\n\n_(Click on the GIFs to watch them full-size.)_\n\nUsing nvr from another shell: \n\nUsing nvr from within `:terminal`: \n\n## FAQ\n\n- **How to open directories?**\n\n `:e /tmp` opens a directory view via netrw. Netrw works by hooking into certain\n events, `BufEnter` in this case (see `:au FileExplorer` for all of them).\n\n Unfortunately Neovim's API doesn't trigger any autocmds on its own, so simply\n `nvr /tmp` won't work. Meanwhile you can work around it like this:\n\n nvr /tmp -c 'doautocmd BufEnter'\n\n- **Reading from stdin?**\n\n Yes! E.g. `echo \"foo\\nbar\" | nvr -o -` and `cat file | nvr --remote -` work just\n as you would expect them to work.\n\n- **Exit code?**\n\n If you use a [recent enough\n Neovim](https://github.com/neovim/neovim/commit/d2e8c76dc22460ddfde80477dd93aab3d5866506), nvr will use the same exit code as the linked nvim.\n\n E.g. `nvr --remote-wait <file>` and then `:cquit` in the linked nvim will make\n nvr return with 1.\n\n- **How to send a message to all waiting clients?**\n\n If you open a buffer with any of the _wait_ options, that buffer will get a\n variable `b:nvr`. The variable contains a list of channels wheres each\n channel is a waiting nvr client.\n\n Currently nvr only understands the `Exit` message. You could use it to\n disconnect all waiting nvr clients at once:\n\n ```vim\n command! DisconnectClients\n \\ if exists('b:nvr')\n \\| for client in b:nvr\n \\| silent! call rpcnotify(client, 'Exit', 1)\n \\| endfor\n \\| endif\n ```\n\n- **Can I have auto-completion for bash/fish?**\n\n If you want basic auto-completion for bash, you can source [this\n script](contrib/completion.bash) in your .bashrc.\n\n This also completes server names with the `--servername` option.\n\n If you want auto-completion for fish, you can add [this\n file](contrib/completion.fish) to your fish completions dir.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Control nvim processes using \"nvr\" commandline tool",
"version": "4.0.0",
"project_urls": {
"Homepage": "https://github.com/1995parham/nvim-remote",
"Repository": "https://github.com/1995parham/nvim-remote"
},
"split_keywords": [
"nvim-remote",
"neovim-remote",
"nvr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1b486916ef7a15e7b9a89e9ca170331a4766f1c599f5092570b8cfc7d02f66a",
"md5": "1d9b6f88c39f5ba3e28478b66e06b9fd",
"sha256": "2070bbc7fe973530be47dbd68b0a0d26322d177b3f19493ceb107411d10f9095"
},
"downloads": -1,
"filename": "nvim_remote-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d9b6f88c39f5ba3e28478b66e06b9fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12563,
"upload_time": "2023-12-05T05:19:16",
"upload_time_iso_8601": "2023-12-05T05:19:16.214405Z",
"url": "https://files.pythonhosted.org/packages/e1/b4/86916ef7a15e7b9a89e9ca170331a4766f1c599f5092570b8cfc7d02f66a/nvim_remote-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c6a1e45712f25c4464d1fe4ddd8f606fd6ee7c465eaabdc738419fef2a62345f",
"md5": "7616ae1c50070b568c79a0ba3f77d6c7",
"sha256": "ffc78a69e84a9ea113dea6291014c3666565ce5c1ae5112b7c58832682540f6d"
},
"downloads": -1,
"filename": "nvim_remote-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "7616ae1c50070b568c79a0ba3f77d6c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13810,
"upload_time": "2023-12-05T05:19:17",
"upload_time_iso_8601": "2023-12-05T05:19:17.888958Z",
"url": "https://files.pythonhosted.org/packages/c6/a1/e45712f25c4464d1fe4ddd8f606fd6ee7c465eaabdc738419fef2a62345f/nvim_remote-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-05 05:19:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "1995parham",
"github_project": "nvim-remote",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nvim-remote"
}
JSON
