*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 mappings to work with those paths. By
working with built-in Vim mechanisms instead of inventing peripheral
imitations, users (and other plugins) can compose and build upon known Vim
concepts.

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. All of 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. Just press `R` to reload the default listing.

Re-use and composition of concepts multiplies the utility of those concepts;
if a plugin does _not_ reuse a concept, both that concept _and_ the new,
redundant mechanism are made mutually _less valuable_—the sum is less than the
parts—because the user now must learn or choose from two slightly different
things instead of one augmented system. @tpope's plugins demonstrate this
theme; more plugins should too.

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

Global ~
    <Plug>(dirvish_up)
    -               Opens the current file directory or the [count]th parent.

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; returns to the original file.
    <Plug>(dirvish_up)
    -               Opens the [count]th parent directory.
    <Plug>(dirvish_split_up)
                    Opens the [count]th parent in a split.
    <Plug>(dirvish_vsplit_up)
                    Opens the [count]th parent in a vertical split.
    <2-LeftMouse>
    i
    <CR>            Opens file at cursor.
    {Visual}I
    {Visual}<CR>    Opens selected files.
    o               Opens in horizontal split.
    {Visual}O       Opens selected files in horizontal splits.
    a               Opens in vertical split.
    {Visual}A       Opens selected files in vertical splits.
    p               Opens file in previous window.
    .               Adds file to the local |arglist|.
    {Visual}.       Adds selected files to the local |arglist|.
    da.             Starts a new empty local |arglist|.
    x               Inserts "|:Shdo|  {}" into the command-line.

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

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

:Dirvish                                                    *dirvish-:Dirvish*
    Opens the |current-directory|.

:Dirvish {path}
    Opens the directory at {path} (or its parent if {path} is a file).
    To open the directory of the current file: >
        :Dirvish %
<
:[range]Shdo[!] {cmd} {}                                       *dirvish-:Shdo*
    Generates a shell script with {cmd} applied to [range] and the respective
    filepath inserted where {} appears in the :Shdo command. 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*

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

==============================================================================
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()|.
    ":{excmd}":  Ex command |:execute|d after listing files.

    Mnemonic: higher number => more files.

g:dirvish_relative_paths = 0                        *g:dirvish_relative_paths*
    0: Files in the Dirvish buffer are full (absolute) paths.
    1: Paths are relative to the |current-directory|.
       Note: Recommended on 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, so all mappings, options, and
content can be overridden by handling that event. Example: >

    augroup my_dirvish_events
      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>

      " Enable :Gstatus and friends.
      autocmd FileType dirvish call fugitive#detect(@%)

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

      " Map `gh` to hide dot-prefixed files.
      " To "toggle" this, just press `R` to reload.
      autocmd FileType dirvish nnoremap <silent><buffer>
        \ gh :silent keeppatterns g@\v/\.[^\/]+/?$@d<cr>
    augroup END
<

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

How do I control where Dirvish opens splits? ~
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 ,^.*[\/],'

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.

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/commit/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.

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