github github
stars 212
issues 8
subscribers 5
forks 4



3 months ago


A plugin that leverages Neovim's built-in RPC functionality to simplify opening files from within Neovim's terminal emulator without 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

The best way to work with git from within a terminal buffer is to make git defer editing to the host session, and block until the host quits 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 and its buffer will be hidden until Neovim's QuitPre event is triggered for the commit buffer, after which, the terminal buffer will be restored to its original location.

Here's an example workflow with this flag set:

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.


Neovim 0.7 or later.


Using lazy.nvim:

return {
    init = function()
        -- Optional settings go here!
        -- e.g.) vim.g.unception_open_buffer_in_new_tab = true

Using packer.nvim:

use {
    setup = function()
        -- Optional settings go here!
        -- e.g.) vim.g.unception_open_buffer_in_new_tab = true

Using vim-plug:

Plug 'samjwill/nvim-unception'


For usage details and additional 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.

Can this work with terminal-toggling plugins?

Yep! See the wiki for setup info.

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.