github github
star 128
alert-circle 5
users 3
git-branch 3



20 days ago


A plugin that leverages Neovim's built-in RPC functionality to simplify opening files from within Neovim's terminal emulator without unintentionally nesting sessions.

Terminal buffers will no longer enter a state of "inception" in which an instance of Neovim is open within an instance of Neovim. Instead, the desired files and directories will be opened by the "host" Neovim session, which leverages :argadd to update its own arguments.

Working with Git

There are a few options for using Neovim as your editor for git from within Neovim itself.

The first option is to make git defer editing to the host session, and block until the host unloads the buffer being edited. This can be done by setting your git core.editor to pass the g:unception_block_while_host_edits=1 argument (like this). Note that the terminal will be blocked until the commit buffer is unloaded.

Here's an example workflow with this flag set:

Note that if Neovim's 'hidden' option is set, the buffer will not be unloaded upon running :wq. Instead :bdelete will need to be called on the git commit message buffer to trigger the BufUnload event and unblock the shell.

Alternatively, if you would like to be able to edit using Neovim directly inside of a nested session, you can disable unception altogether by setting your git core.editor to pass the g:unception_disable=1 argument (like this).

Lastly, setting your core.editor to another file editor, such as GNU nano would also work.

Can this work with terminal-toggling plugins?

Yep! See the wiki for setup info.


Neovim 0.7 or later.


Using vim-plug:

Plug 'samjwill/nvim-unception'

Using packer.nvim:

use "samjwill/nvim-unception"

How does it work?

The plugin tells Neovim to automatically start a local server listening to a named pipe at launch. Upon launching a new Neovim session within a terminal emulator buffer, the arguments are forwarded to the aforementioned Neovim server session via the pipe, and the server session replaces the buffer under the cursor (the terminal buffer) with the first file/directory argument specified.


This plugin works well enough for me but your mileage may vary. If you find an issue, feel free to create one detailing the problem on the GitHub repo, and I'll try to fix it if I'm able. If you run into a problem, Unception can be temporarily disabled when launching Neovim like so: nvim --cmd "let g:unception_disable=1"

Other Neovim command-line arguments that do not involve editing a file or directory may not work as expected from within the terminal emulator (e.g. passing -b to edit in binary mode when inside of a terminal buffer will not propagate binary mode to the file when it's unnested, and opening a file as read-only when the server session is not set to read-only mode will not result in a read-only buffer). See :help vim-arguments for how these are typically used. Note that any arguments that might not work when launched from within a Neovim terminal buffer should work just fine when launching Neovim normally. They should also behave as as they do by default if you pass the disable flag described above, even if launched from within a terminal buffer.


For usage details and options (such as opening the file buffers in new tabs rather than the current window), see doc/nvim-unception.txt, or, after installation, run :help nvim-unception.