nvim-unception.txt

nvim-unception.txt
                                                            *nvim-unception*
INTRODUCTION                                                *unception*

        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.

SETTINGS                                               *nvim-unception-settings*

        IMPORTANT: The nested Neovim session (i.e. the Neovim session that is
    launched from within a terminal buffer) is the session that dictates this
    plugin's behavior. These settings must be read into the nested session.
    What this means is that you cannot set these options in the Neovim
    server/host session alone after Neovim is already running. These values
    must be set sometime during initialization, before the nested session
    loads the plugin, and likely cannot be lazy loaded.

        To put it simply, these settings can be placed in your initialization
    files (e.g. |init.vim|), but will not work if directly calling |:let| in
    the server session after you've already launched Neovim.

*g:unception_delete_replaced_buffer*                     bool (default=false)

        Must be set during initialization. Cannot be set after Neovim is
    already running. See |nvim-unception-settings| for more info.

        When true, causes the Neovim session running the local server to
    delete the buffer under the cursor when a command is received from a
    Neovim client session (i.e. a session launched from within a terminal
    buffer) if that buffer is not visible in any other windows.

        Has no effect when |g:unception_open_buffer_in_new_tab| is true.

        Note: The deleted buffer should always be the terminal buffer that was
    used to launch the new Neovim session, but there are no checks in place
    that mandate that this will always be the case. If the cursor was somehow
    moved quickly enough to another terminal buffer between the time the client
    sends the command and the server receives it, this could technically cause
    deletion of the wrong buffer.


*g:unception_open_buffer_in_new_tab*                     bool (default=false)

        Must be set during initialization. Cannot be set after Neovim is
    already running. See |nvim-unception-settings| for more info.

        When true, causes the server Neovim session to open files/directories
    in a new tab rather than placing them in the window that has focus.


*g:unception_enable_flavor_text*                         bool (default=true)

        Must be set during initialization. Cannot be set after Neovim is
    already running. See |nvim-unception-settings| for more info.

        When true, causes unception to echo a message whenever it is
    triggered.


*g:unception_block_while_host_edits*                     bool (default=false)

        Must be set during initialization. Cannot be set after Neovim is
    already running. See |nvim-unception-settings| for more info.

        When true, if unception detects that the session of Neovim has been
    launched from within a terminal buffer, the file passed as an argument
    will be opened in the host session, and the terminal will be blocked until
    |QuitPre| is triggered on the buffer. Note that only a single, filepath
    argument may be passed when this is enabled.

        If |g:unception_open_buffer_in_new_tab| is true, the new buffer will
    be opened in a new tab rather than in the current window. If false, the
    new buffer will be opened in the current window, making the buffer under
    the cursor hidden, and restoring its visibility to the current window when
    |QuitPre| is triggered.

        This can be useful for command-line tools that are expected to launch
    an editor, such as git. By setting the core editor to:
    `nvim --cmd 'let g:unception_block_while_host_edits=1'`
    one can edit their commit messages launched from a terminal buffer
    directly in the host session.


*g:unception_disable*                                    bool (default=false)

        When true, disables nvim-unception.


EVENTS                                                 *nvim-unception-events*

*UnceptionEditRequestReceived*

        A |User| event that is triggered when a request to edit a
    file/directory is received from a nested Neovim session, launched from a
    terminal buffer.

        Below is an example of Lua code that creates an |autocmd| that would
    print "Hello world!" whenever this event is triggered:
>
    vim.api.nvim_create_autocmd(
        "User",
        {
            pattern = "UnceptionEditRequestReceived",
            callback = function()
                print("Hello world!")
            end
        }
    )
<

vim:ft=help:norl: