Skip to main content

Control nvim processes using "nvr" commandline tool

Project description

neovim-remote
=============

.. image:: https://travis-ci.org/mhinz/neovim-remote.svg?branch=master
:target: https://travis-ci.org/mhinz/neovim-remote

.. image:: https://img.shields.io/pypi/wheel/neovim-remote.svg
:target: https://pypi.python.org/pypi/neovim-remote

.. image:: https://img.shields.io/pypi/v/neovim-remote.svg
:target: https://pypi.python.org/pypi/neovim-remote

.. image:: https://img.shields.io/pypi/pyversions/neovim-remote.svg
:target: https://pypi.python.org/pypi/neovim-remote

.. image:: https://img.shields.io/pypi/l/neovim-remote.svg
:target: https://pypi.python.org/pypi/neovim-remote
|
- `Intro <#intro>`__
- `Use case <#use-case>`__
- `Installation <#installation>`__
- `Usage <#usage>`__
- `Demos <#demos>`__
- `FAQ <#faq>`__

Intro
-----

**nvr** is a tool that helps controlling nvim processes.

It does two things:

1. adds back the ``--remote`` family of options (see ``man vim``)
2. helps controlling the current nvim from within ``:terminal``

To target a specific nvim process, use either the ``--servername``
option or set the environment variable ``$NVIM_LISTEN_ADDRESS``.

If the targeted address does not exist, nvr starts a new process on its
own by running "nvim". You can change the command by setting
``$NVR_CMD``.

Since ``$NVIM_LISTEN_ADDRESS`` is implicitely set by each nvim process,
you can call **nvr** from within Neovim (``:terminal``) without
specifying ``--servername``.

Use case
--------

Imagine Neovim is set as your default editor: ``EDITOR=nvim``.

Now run ``git commit``. In a regular shell, a new nvim process starts. In a
terminal buffer (``:terminal``), a new nvim process starts as well. Now you
have one nvim nested within another. You don't want that. Put this in your
vimrc:

.. code:: vim

if has('nvim')
let $VISUAL = 'nvr -cc split --remote-wait'
endif

That way, you get a new window for entering the commit message instead of a
nested nvim process.

Alternatively, you can make git always using nvr. In a regular shell, nvr will
create a new nvim process. In a terminal buffer, nvr will open a new buffer.

::

$ git config --global core.editor 'nvr --remote-wait-silent'

Installation
------------

::

$ pip3 install neovim-remote

On most systems this will be good enough.

If you get a "permission denied" error, don't use ``sudo`` to force it! Use
this instead:

::

$ pip3 install --user neovim-remote

..and make sure that ``~/.local/bin`` is in $PATH.

Usage
-----

Start a nvim process (which acts as a server) in one shell:

::

$ NVIM_LISTEN_ADDRESS=/tmp/nvimsocket nvim

And do this in another shell:

.. code:: shell

$ # Spares us from using --servername all the time:
$ export NVIM_LISTEN_ADDRESS=/tmp/nvimsocket
$ # This is optional, since nvr assumes /tmp/nvimsocket by default.

$ # 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 all listed buffers:
$ nvr --remote-expr "join(sort(map(filter(range(bufnr('$')), 'buflisted(v:val)'), 'bufname(v:val)')), "\""\n"\"")"
.config/git/config
vim/vimrc
zsh/.zprofile

See ``nvr -h`` for all options.

Demos
-----

*(Click on the GIFs to watch them full-size.)*

Using nvr from another shell: |Demo 1|

Using nvr from within ``:terminal``: |Demo 2|

.. |Demo 1| image:: https://github.com/mhinz/neovim-remote/raw/master/images/demo1.gif
.. |Demo 2| image:: https://github.com/mhinz/neovim-remote/raw/master/images/demo2.gif

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.

**Talking to nvr from Neovim?**

Imagine ``nvr --remote-wait file``. The buffer that represents "file" in Neovim
now has a local variable ``b:nvr``. It's a list of channels for each connected
nvr process.

If we wanted to create a command that disconnects all nvr processes with exit
code 1:

.. code:: vim

command! Cquit
\ if exists('b:nvr')
\| for chanid in b:nvr
\| silent! call rpcnotify(chanid, 'Exit', 1)
\| endfor
\| endif

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neovim-remote-1.8.1.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

neovim_remote-1.8.1-py3-none-any.whl (11.5 kB view details)

Uploaded Python 3

File details

Details for the file neovim-remote-1.8.1.tar.gz.

File metadata

  • Download URL: neovim-remote-1.8.1.tar.gz
  • Upload date:
  • Size: 8.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for neovim-remote-1.8.1.tar.gz
Algorithm Hash digest
SHA256 63e4c2d5228ab0a505c4ce84a566b344caecca11c1e1275c66eb04f2a7f9008f
MD5 d9aaa609a240bcc369fb23029b4690d1
BLAKE2b-256 0561a2b01cdcf74f02b762f61711c2ad102690017f37860b3dca7b138a6475d2

See more details on using hashes here.

File details

Details for the file neovim_remote-1.8.1-py3-none-any.whl.

File metadata

File hashes

Hashes for neovim_remote-1.8.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d84da3b99f108c84b810eef05c7d6207e25d5b557c59d48af42dae3e6925f09a
MD5 4a056e5043c66598c36cb77a4a4ccdc1
BLAKE2b-256 859a122669fc70778e517ed3579153b4ba7536956c1eca2bd94ceb02d804a0fb

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page