*dirvish.txt*	directory viewer

==============================================================================
OVERVIEW                                                             *dirvish*

Dirvish is a minimalist directory viewer. It basically dumps a list of paths
into a Vim buffer and provides some sugar to work with those paths. It works
with built-in Vim mechanisms instead of inventing peripheral imitations.

Because each Dirvish buffer-name is the literal directory path, you can |:cd|
to the directory, >
  :cd %
create a new file, >
  :edit %foo.txt
|expand()| the directory path, >
  :let &titlestring = expand('%', 1)
and use complementary plugin commands like |]f|/|[f| (unimpaired.vim).

Because each dirvish buffer is just a list of paths, you can use normal Vim
commands to |y|ank, |:read|, |gf|, etc. The built-in CTRL-W mappings also work
as expected.

It's totally fine to slice, dice, and smash any Dirvish buffer: it will never
modify the filesystem. If you edit the buffer, Dirvish automatically disables
|conceal| so you can see the full text.

Dirvish is designed to work with built-in Vim concepts where possible. Tim
Pope's plugins demonstrate this theme; more plugins should too. Re-use of
concepts multiplies the utility of those concepts; conversely if a plugin does
not reuse a concept, both that concept and the new one are made mutually less
valuable--the sum is less than the parts--because the user must learn or
choose from two slightly different things instead of one augmented system.

==============================================================================
MAPPINGS                                                    *dirvish-mappings*

Global ~
    <Plug>(dirvish_up)
    -               Opens the [count]th parent directory of the current file.
    <Plug>(dirvish_split_up)
                    Opens the [count]th parent in a new window.
    <Plug>(dirvish_vsplit_up)
                    Opens the [count]th parent in a new, vertical window.

Buffer-local (filetype=dirvish) ~
    g?              Shows this help.
    [count]R        Reloads the current directory. (|:edit| works too.)
                    Sets |g:dirvish_mode| to [count], if given.
                    Mnemonic: higher [count] => more files.
    <Plug>(dirvish_quit)
    q               Quits and returns to the original file.
    gq              Alias to "q". May be removed in the future.
    <2-LeftMouse>
    i
    <CR>            Opens file at cursor.
    {Visual}I
    {Visual}<CR>    Opens selected files.
    o               Opens file in a new window.
    {Visual}O       Opens each selected file in a new window.
    a               Opens file in a new, vertical window.
    {Visual}A       Opens each selected file in a new, vertical window.
    K               Shows file info. [count] shows directory size.
    {Visual}K       Shows info for selected files. [count] shows directory size.
    p               Previews file at cursor.
    CTRL-N          Previews the next file.
    CTRL-P          Previews the previous file.
    <Plug>(dirvish_arg)
    x               Adds/removes file to/from the local |arglist|.
    {Visual}x       Adds selected files to the local arglist.
    dax             Starts a new empty local arglist.
    .               Inserts ":! {path}" into the command-line.
    {Visual}.       Inserts "|:Shdo|  {}" into the command-line.
    [count].        Inserts "|:Shdo|! {}" into the command-line.
    ~               Opens your home directory.
    cd              Sets the local |current-directory|. |:lcd|
    [count]cd       Sets the global |current-directory|. |:cd|

Buffer-local (:Shdo) ~
                                                    *Z!* *dirvish-Z!*
    Z!              Saves and executes a |:Shdo| shell-script. Closes the
                    window if the script succeeded.

==============================================================================
COMMANDS                                                    *dirvish-commands*

:Dirvish [path]                                             *dirvish-:Dirvish*
    Opens the directory at [path], or its parent if [path] is a file, or the
    parent of the current file if [path] is not given.

:[range]Shdo[!] {cmd}                               *:Shdo* *dirvish-:Shdo*
    Generates a shell script with {cmd} applied to [range] and the respective
    filepath inserted wherever {} appears in {cmd}. The window-local directory
    is initialized to the current Dirvish directory. If bang ! is given the
    |arglist| is used instead of [range].

    For example, to rename a list of visual-selected files: >
        :'<,'>Shdo mv {} {}-copy.txt
<    Run the script with |Z!| or ":!%".

==============================================================================
FUNCTIONS                                                  *dirvish-functions*

                                                              *dirvish#open()*
[range]dirvish#open({cmd}, {bg})
    Performs {cmd} ("edit", "vsplit", "split", "tabedit") on the files in
    [range]. {bg} must be 0 (opens in current window) or 1 (opens in the
    "background").

                                                       *dirvish#add_icon_fn()*
dirvish#add_icon_fn(fn)
    Registers a function {fn} to decide the "icon" for each path in a Dirvish
    buffer. Returns id for use with |dirvish#remove_icon_fn()|. If multiple
    functions are registered: the first function to return non-whitespace for
    a given path, wins. Best practice: if you don't have anything meaningful
    to show for a given path, return empty string (or whitespace).

    {fn} is any |Funcref| that takes a path (string) and returns a single
    character (the "icon"). Example: >
        call dirvish#add_icon_fn({p -> p[-1:]=='/'?'📂':'📄'})
<

                                                    *dirvish#remove_icon_fn()*
dirvish#remove_icon_fn(fn_id)
    Unregisters the function associated with {fn_id} returned from
    |dirvish#add_icon_fn()|.

==============================================================================
OPTIONS                                                      *dirvish-options*

g:dirvish_mode = 1                                  *g:dirvish_mode*
    Controls which files are listed and how they are presented.
    1:        'suffixes' and 'wildignore' determine sorting and visibility.
    2:        Shows all files, in the order returned by |glob()|.
    ":{cmd}": Ex-command |:execute|d after listing files.

    Mnemonic: higher number => more files.

g:dirvish_relative_paths = 0                        *g:dirvish_relative_paths*
    0:        List full (absolute) paths in the Dirvish buffer.
    1:        List paths relative to the |current-directory|.
              (Recommended for Vim 7.3 because it lacks |conceal|).

|BufNew| fires the first time a directory is opened (and not yet loaded).
Note: Use expand("<afile>") to get the new buffer name (not "%").

|FileType| fires after Dirvish has loaded: all mappings, options, and content
can be overridden by handling that event. Example: >

    augroup dirvish_config
      autocmd!

      " Map `t` to open in new tab.
      autocmd FileType dirvish
        \  nnoremap <silent><buffer> t :call dirvish#open('tabedit', 0)<CR>
        \ |xnoremap <silent><buffer> t :call dirvish#open('tabedit', 0)<CR>

      " Map `gr` to reload.
      autocmd FileType dirvish nnoremap <silent><buffer>
        \ gr :<C-U>Dirvish<CR>

      " Map `gh` to hide dot-prefixed files.  Press `R` to "toggle" (reload).
      autocmd FileType dirvish nnoremap <silent><buffer>
        \ gh :silent keeppatterns g@\v/\.[^\/]+/?$@d _<cr>:setl cole=3<cr>
    augroup END
<

==============================================================================
FAQ                                                              *dirvish-faq*

How do I control where Dirvish opens split windows? ~
Set the Vim options 'splitbelow' and 'splitright'.

How do I group (sort) directories/folders? ~
Sort folders at the top: >
    :sort ,^.*[\/],
Sort folders at the bottom: >
    :sort ,^.*[^\/],
To make this automatic, set |g:dirvish_mode|: >
    let g:dirvish_mode = ':sort ,^.*[\/],'
If you use |g:dirvish_relative_paths|, try this: >
    let g:dirvish_mode = ':sort ,^\v(.*[\/])|\ze,'

How do I filter? ~
Use |:global| to delete lines matching any filter: >
    :g/foo/d
To make this automatic, set |g:dirvish_mode|: >
    let g:dirvish_mode = ':silent keeppatterns g/foo/d _'

How do I hide "hidden" (dot-prefixed) files? ~
Use |:global| to delete the paths with dot-prefixed files: >
    :g@\v/\.[^\/]+/?$@d
To "toggle", just reload.
To make this automatic, set |g:dirvish_mode|: >
    let g:dirvish_mode = ':silent keeppatterns g@\v/\.[^\/]+/?$@d _'
You could also use a FileType autocmd: >
    autocmd FileType dirvish silent keeppatterns g@\v/\.[^\/]+/?$@d _
To un-hide, just undo. To hide again, reload.

How do I disable a Dirvish mapping? ~
As noted in |dirvish-options|, the way to customize Dirvish is to handle its
FileType event. For example if you have a global <C-p> mapping and you don't
want Dirvish to "shadow" it, :unmap the Dirvish buffer-local mapping: >

    augroup dirvish_config
      autocmd!
      autocmd FileType dirvish silent! unmap <buffer> <C-p>
    augroup END

You could use ":mapclear <buffer>" to delete ALL of the mappings.

Why does the "swap file" dialog appear if another Vim is viewing the same ~
directory? ~
To avoid this, |:noswapfile| is required (Vim 7.4.213).
https://github.com/vim/vim/tree/v7.4.213

How can I delete files, rename files, or perform other commands?~
Since ":'<,'>call delete(getline('.'))" is a bit much to type, Dirvish
provides the ":Shdo" command. |dirvish-:Shdo|

Just for fun, here's the old-school way: >
    qqq
    :g/^/let @Q='echo '.shellescape(getline('.')).' '.shellescape(getline('.'))."\n"
    :exe 'e' tempname().'.sh'
    :put q|w|!%
<
Why does Dirvish report "invalid directory" for a path that contains unusual ~
characters (e.g. brackets "[]")? ~
Check your 'isfname' setting. On Windows (where filepaths may contain
backslashes "\") |fnamemodify()| may produce nonsense if 'isfname' does not
contain the aforementioned unusual characters.

How to override the netrw :Explore, :Sexplore, :Vexplore commands? ~
Put this in your vimrc: >

    let g:loaded_netrwPlugin = 1
    command! -nargs=? -complete=dir Explore Dirvish <args>
    command! -nargs=? -complete=dir Sexplore belowright split | silent Dirvish <args>
    command! -nargs=? -complete=dir Vexplore leftabove vsplit | silent Dirvish <args>

How to expand a directory inline (like a tree-style view)? ~
There is a hacky solution. Put this in your vimrc and hit "t" on a directory: >

    augroup dirvish_config
      autocmd!
      autocmd FileType dirvish
                  \ nnoremap <buffer> t o<Esc>:r !find '<C-R>=substitute(getline(line(".")-1),"\\n","","g")<CR>' -maxdepth 1 -print0 \| xargs -0 ls -Fd<CR>:silent! keeppatterns %s/\/\//\//g<CR>:silent! keeppatterns %s/[^a-zA-Z0-9\/]$//g<CR>:silent! keeppatterns g/^$/d _<CR>"_dd
    augroup END

Note:
- Assumes unix-style "/" path separators.

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