*nnn.vim* File manager for vim/neovim powered by n³.
*nnn*
>
  __   __     __   __     __   __     __   __   __     __    __
 /\ "-.\ \   /\ "-.\ \   /\ "-.\ \   /\ \ / /  /\ \   /\ "-./  \
 \ \ \-.  \  \ \ \-.  \  \ \ \-.  \  \ \ \'/   \ \ \  \ \ \-./\ \
  \ \_\\"\_\  \ \_\\"\_\  \ \_\\"\_\  \ \__|    \ \_\  \ \_\ \ \_\
   \/_/ \/_/   \/_/ \/_/   \/_/ \/_/   \/_/      \/_/   \/_/  \/_/
<

=============================================================================
CONTENTS *nnn-help*

  Introduction .......................... |nnn-intro|
    Requirements .......................... |nnn-req|
  Usage ................................. |nnn-usage|
    Commands .............................. |nnn-commands|
    Mappings .............................. |nnn-mappings|
    Configurations ........................ |nnn-config|
    Functions ............................. |nnn-func|
    Highlights ............................ |nnn-hl|
  Miscellaneous ......................... |nnn-misc|
  Explorer-FAQ .......................... |nnn-explorer-faq|
  Troubleshooting ....................... |nnn-troubleshooting|
  Credits ............................... |nnn-credits|

=============================================================================
Introduction                                                        *nnn-intro*

This plugins attempts to make n³ the file manager companion for vim. Use it
to create, remove, move files or to quickly select files in n³ and open them
in vim all without leaving vim. It achieves these but utilizing the built-in
terminal feature of vim and neovim.

-----------------------------------------------------------------------------
Requirements                                                          *nnn-req*

1. n³
2. `has('nvim') || has('terminal')` i.e. terminal support
3. Optional `has('nvim-0.5') || has('popupwin')` for floating window
4. Optional n³ v4.3(+) needed for file-explorer mode

=============================================================================
Usage                                                               *nnn-usage*

-----------------------------------------------------------------------------
Picker                                                                 *Picker*

By running |:NnnPicker| or calling the |nnn#pick()| function, a new terminal
buffer opens running an n³ process in picker mode.

Once you select (see https://github.com/jarun/nnn/wiki/concepts#selection)
one or more files and press enter, vim quits the n³ window and opens the
first selected file and add the remaining files to the arg list/buffer
list. If |nnn#session| is enabled, then n³ will remember where you left off of
when you reopen it.

Pressing enter on a file in n³ will pick any earlier selection (or the hovered
file if no selection exists) and exit n³.

-----------------------------------------------------------------------------
Explorer                                                             *Explorer*

To open n³ as a file-explorer use the command |:NnnExplorer|. The command
accepts optional path similar to |:NnnPicker|. In explorer mode pressing
`Enter` will pick a file but keep the n³ window open. Running |:NnnExplorer|
while an explorer window is active on that tab will toggle/close it.

NOTE: In order to use explorer mode n³ version 4.3 (or above) must be
installed.

-----------------------------------------------------------------------------

NOTE: Pressing `l` or <Right> on a file would open it instead of picking.
Use `-o` via |nnn#command| to disable this.

You may have to set `set hidden` to make floating window work.

To discard selection and/or exit, press q.

Press <c-g> to quit n³ and `cd` into the last directory.

-----------------------------------------------------------------------------
Commands                                                         *nnn-commands*

:NnnPicker                                                         *:NnnPicker*
                  Opens an n³ window.
:NnnExplorer                                                     *:NnnExplorer*
                  Opens an n³ file-explorer.

-----------------------------------------------------------------------------
Mappings                                                         *nnn-mappings*

Default mappings. Can be disabled by setting |g:nnn#set_default_mappings| to 0.

<leader>n
                  Runs |:NnnPicker|.
<C-w>
                  Window navigation prefix key. Same as <C-\><C-n><C-w> or
                  <C-w> in normal mode.


-----------------------------------------------------------------------------
Configurations                                                     *nnn-config*

g:nnn#set_default_mappings                         *g:nnn#set_default_mappings*
                  Default: 1
                  Enable default mappings.
                  Examples:
>
                  " Disable default mappings
                  let g:nnn#set_default_mappings = 0

                  " Set your own
                  nnoremap <silent> <leader>nn :NnnPicker<CR>

                  " Or override
                  " Start n³ in the current file's directory
                  nnoremap <leader>n :NnnPicker '%:p:h'<CR>
<

g:nnn#layout                                                     *g:nnn#layout*
                  Default:
                    neovim: { 'window': { 'width': 0.9, 'height': 0.6 } }
                    vim: 'enew'
                  Display type for the n³ buffer. Default is a floating window
                  on neovim and |enew| on vim. |enew| has a special behavior
                  to act as a "split explorer" reusing the current window and
                  brings back the last buffer if nothing is selected.
                  Examples:
>
                  " Opens the n³ window in a split
                  let g:nnn#layout = 'new' " or vnew, tabnew etc.

                  " Or pass a dictionary with window size
                  let g:nnn#layout = { 'left': '~20%' } " or right, up, down

                  " Floating window
                  let g:nnn#layout = { 'window': { 'width': 0.9, 'height': 0.6, 'highlight': 'Debug' } }
                  " Options:
                  " width, height, yoffset, xoffset : number
                  " highlight : highlight group assign to the border
                  " border : border style - 'rounded' / 'sharp' / 'none'
<
g:nnn#explorer_layout                                   *g:nnn#explorer_layout*

                  Default:  { 'left': '20%' }

                  Same as g:nnn#layout but for the explorer mode.


g:nnn#action                                                     *g:nnn#action*
                  Default: {}
                  Additional key-binding set for the n³ buffer for opening
                  files in different ways. Nothing is set by default to not
                  override n³'s own key-bindings.
                  Examples:
>
                  function! CopyLinestoRegister(lines)
                    let joined_lines = join(a:lines, "\n")
                    if len(a:lines) > 1
                      let joined_lines .= "\n"
                    endif
                    echom joined_lines
                    let @+ = joined_lines
                  endfunction

                  let g:nnn#action = {
                        \ '<c-t>': 'tab split',
                        \ '<c-x>': 'split',
                        \ '<c-v>': 'vsplit',
                        \ '<c-o>': function('CopyLinestoRegister') }

                  For example, when inside an n³ window, pressing <C-t> will
                  open the selected file in a tab, instead of the current
                  window. <C-x> will open in a split an so on. Meanwhile for
                  multi selected files will be loaded in the buffer list.

                  And finally you can pass a FuncRef and the array of selected
                  lines will be passed to that function.

                  Another example, cd into selected file's directory:

                  function! CdSelectedFile(lines)
                    let dir = a:lines[-1]
                    if filereadable(dir)
                      let dir = fnamemodify(dir, ':h')
                    endif
                    execute 'cd' dir
                  endfunction

                  let g:nnn#action = { '<c-w>': function('CdSelectedFile') }
<

g:nnn#session                                                   *g:nnn#session*
                  Default: 'none'
                  How n³ should utilize sessions. Default is 'none' meaning
                  no persistent sessions. Other options are 'local' for the
                  same n³ session across a vim session, or 'global' for the
                  same n³ session across everywhere.
>
                  " use the same nnn session within a vim session, for
                  " example, so that consecutive uses of :Np will remember
                  " where you last left off
                  let g:nnn#session = 'local'
<

g:nnn#command                                                   *g:nnn#command*
                  Default: 'nnn'
                  When you want to override the default n³ command and add
                  some extra flags.
                  Example you want to start n³ in detail mode.
>
                  let g:nnn#command = 'nnn -d'

                  " or pass some env variables
                  let g:nnn#command = 'NNN_TRASH=1 nnn -d'
<

g:nnn#replace_netrw                                       *g:nnn#replace_netrw*
                  Default: 0
                  Open n³ instead of netrw when opening a directory.


g:nnn#statusline                                             *g:nnn#statusline*
                  Default: 1
                  The n³ statusline. Set to 0 to disable.

g:nnn#shell                                                      *g:nnn#shell*
                  Default: &shell
                  The shell to run the terminal window.

require('nnn').setup{}                                         *nnn-lua-setup*
                  Default: same as Vimscript defaults
                  An alternative way to configure n³ more suitable for
                  init.lua users. For example:
>
                  require('nnn').setup{
                      set_default_mappings = false,
                      session = 'global',
                      layout = { left = '20%' }
                  }
<


-----------------------------------------------------------------------------
Functions                                                            *nnn-func*

nnn#pick([{dir}][,{opts}])                                         *nnn#pick()*
                  Can be called with custom directory and additional options
                  such as opening file in splits or tabs. Basically a more
                  configurable version of |:NnnPicker| command.

                  {dir} : (string) a directory.
                  {opts}: (dict) can be:
                    edit   : type of window the select file will be open. Or
                             pass a FuncRef and array of selected files will
                             be passed to that function.
                    layout : same as |g:nnn#layout| and overrides it if
                             specified.
                    session: set to 0 to disable session regardless of
                             |g:nnn#session| value.

                  Example:
>
                  call nnn#pick('~/some-directory', { 'edit': 'vertical split' })
<
nnn#explorer([{dir}][,{opts}])                                 *nnn#explorer()*
                  Same as |nnn#pick()| but for explorer mode.

-----------------------------------------------------------------------------
Highlights                                                             *nnn-hl*

The following are the highlight groups that are used:

NnnNormal       Window. Linked to |hl-Normal|.

NnnNormalNC     Non-current window. Linked to |hl-Normal|.

NnnNormalFloat  Floating window. Linked to |hl-Normal|.

NnnBorder       Floating window border. Linked to |hl-FloatBorder| or
                |hl-Comment|.

NnnVertSplit    Explorer window VertSplit. Linked to |hl-VertSplit|. (requires
                |winhighlight| from neovim).

=============================================================================
Miscellaneous                                                        *nnn-misc*

You can define env variables in `vimrc` and n³ will detect it.
>
                  let $NNN_TRASH=1
<
=============================================================================
Explorer FAQ                                                 *nnn-explorer-faq*

* How to auto start explorer when vim opens?

>
                  " Start NnnExplorer and leave the cursor in it.
                  autocmd VimEnter * call nnn#explorer()

                  " Start NnnExplorer and put the cursor back in the other window.
                  autocmd VimEnter * call nnn#explorer() | wincmd p | stopinsert

                  " If a file is specified, start NnnExplorer and move the cursor to the file window.
                  autocmd StdinReadPre * let s:std_in=1
                  autocmd VimEnter * if argc() > 0 || exists("s:std_in") | call nnn#explorer() | wincmd p | stopinsert | endif
<

* How to auto close vim when explorer is the last window remaining?

>
                  " Exit Vim if NnnExplorer is the only window remaining in the only tab.
                  autocmd BufEnter * if tabpagenr('$') == 1 && winnr('$') == 1 && &filetype ==# 'nnn' | quit! | endif

                  " Close the tab if NnnExplorer is the only window remaining in it.
                  autocmd BufEnter * if winnr('$') == 1 && &filetype ==# 'nnn' | quit! | endif
<
=============================================================================
Troubleshooting                                           *nnn-troubleshooting*

These are some common problems that one might run into. Follow the instruction
and add relevant code snippet into your `vimrc` or `init.vim` to fix them.

* Files being renamed randomly: This can happen when using `AutoComplPop`
plugin.
>
                  function! AutoCmpNNN()
                      call acp#disable()
                      autocmd BufLeave <buffer> call acp#enable()
                      autocmd BufEnter <buffer> call acp#disable()
                  endfunction
                  autocmd FileType nnn call AutoCmpNNN()
<

* Explorer buffer gets wiped when opening a file: This can happen when using
`miniBufExpl` plugin. The workaround is to make sure `miniBufExpl` is open
before calling `:NnnExplorer`.
>
                  let g:miniBufExplBuffersNeeded = 1
<

=============================================================================
Credits                                                           *nnn-credits*

Main n³ program by Arun Prakash Jana
github: https://github.com/jarun

Vim/neovim plugin maintained by Michael Chris Lopez
github: https://github.com/mcchrish

Source codes:
n³: https://github.com/jarun/nnn
vim plugin: https://github.com/mcchrish/nnn.vim

=============================================================================
vim:tw=78:ts=2:et:ft=help:norl:
