198 lines
9.0 KiB
Plaintext
Executable File
198 lines
9.0 KiB
Plaintext
Executable File
*dirbuf.txt* directory buffer
|
|
|
|
==============================================================================
|
|
OVERVIEW *dirbuf*
|
|
|
|
Dirbuf provides Neovim with an editable directory buffer. This buffer is a
|
|
regular text buffer with some metadata behind the scenes allowing you to
|
|
leverage all of Neovim's built-in text editing capabilities to efficiently
|
|
manipulate and edit file directories.
|
|
|
|
To create a new file, add a new line containing the name of the file. To
|
|
create an empty directory, add a "/" at the end.
|
|
|
|
To delete a file or directory, delete its line.
|
|
|
|
To copy a file or directory, copy its line and give it a new name.
|
|
|
|
To rename a file or directory, change its name in the directory buffer.
|
|
|
|
When you save the buffer, Dirbuf applies the necessary filesystem operations
|
|
to get the directory into the desired state. It does this by comparing the
|
|
snapshot it took of the directory when the buffer was created to the state of
|
|
the buffer upon saving. Using the hashes at the end of every line, Dirbuf can
|
|
tell what objects are new (i.e. they do not have a hash) and what objects have
|
|
changed (i.e. their hash does not match their name).
|
|
|
|
Because each Dirbuf buffer name is the literal directory path, you can run any
|
|
|:!| commands you want and prefix the filenames with |%|. For example, >
|
|
:!sed 's/hi/ahoy/g' %/pirate_script.txt -i
|
|
|
|
Dirbuf is designed to work with built-in Vim concepts as much as 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 *dirbuf-mappings*
|
|
|
|
All mappings are listed with their <Plug> mapping and their default mapping.
|
|
If a mapping to the <Plug> version already exists, then the default mapping is
|
|
not made.
|
|
|
|
Global ~
|
|
<Plug>(dirbuf_up)
|
|
- Opens the current file's directory or the [count]th parent
|
|
directory.
|
|
|
|
Buffer-local (filetype=dirbuf) ~
|
|
<Plug>(dirbuf_up)
|
|
- Opens the current file's directory or the [count]th parent
|
|
directory.
|
|
<Plug>(dirbuf_enter)
|
|
<CR> Opens file or directory at cursor.
|
|
<Plug>(dirbuf_toggle_hide)
|
|
gh Toggles whether hidden files (i.e. dot files) are
|
|
displayed.
|
|
<Plug>(dirbuf_history_forward)
|
|
Moves forward [count] times in the directory buffer
|
|
history.
|
|
<Plug>(dirbuf_history_backward)
|
|
Moves backward [count] times in the directory buffer
|
|
history.
|
|
|
|
==============================================================================
|
|
COMMANDS *dirbuf-commands*
|
|
|
|
:Dirbuf [path] *dirbuf-:Dirbuf*
|
|
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.
|
|
|
|
:DirbufQuit *dirbuf-:DirbufQuit*
|
|
Quits and returns to the original file.
|
|
|
|
:DirbufSync [{flag}] *dirbuf-:DirbufSync*
|
|
Saves and refreshes the current directory buffer, syncing its state with
|
|
the file system by creating, moving, copying, or deleting entries as
|
|
necessary.
|
|
|
|
Flags: ~
|
|
-confirm Before changing the filesystem, print out a list of all
|
|
the actions `:DirbufSync` would perform, like `-dry-run`.
|
|
Then ask the user to confirm the changes before making
|
|
them.
|
|
-dry-run Rather than changing the filesystem, print out a list of
|
|
all the actions `:DirbufSync` would perform. These are
|
|
formatted as Unix-like commands (e.g. `mv 'foo' 'bar'`),
|
|
no matter what platform you are on.
|
|
|
|
==============================================================================
|
|
FUNCTIONS *dirbuf-functions*
|
|
|
|
dirbuf.setup({opts}) *dirbuf.setup()*
|
|
Overwrites the default options with the options in the {opts} table.
|
|
|
|
Example with all the default options: >
|
|
require("dirbuf").setup {
|
|
hash_padding = 2,
|
|
show_hidden = true,
|
|
sort_order = "default",
|
|
write_cmd = "DirbufSync",
|
|
}
|
|
|
|
|
|
dirbuf.enter({cmd}) *dirbuf.enter()*
|
|
Performs {cmd} ("edit", "vsplit", "split", "tabedit") on the path
|
|
currently under the cursor.
|
|
|
|
dirbuf.get_cursor_path() *dirbuf.get_cursor_path()*
|
|
Returns the absolute path of the filesystem entry under the cursor in the
|
|
current directory buffer. If there are any errors parsing the current
|
|
line, then this `error()`s with a descriptive error message.
|
|
|
|
==============================================================================
|
|
OPTIONS *dirbuf-options*
|
|
|
|
|hash_padding| (default: `2`)
|
|
Number of characters of padding between the file hashes and the longest
|
|
filename. This must be an integer larger than 1.
|
|
|
|
|show_hidden| (default: `true`)
|
|
Whether Dirbuf should display hidden files (i.e. "dot files") by default
|
|
when opening new directory buffers. This can be changed locally per-buffer
|
|
with the `gh` mapping.
|
|
|
|
|sort_order| (default: `"default"`)
|
|
What order Dirbuf should sort the directory buffer in when it is created
|
|
and refreshed.
|
|
|
|
This must be given as either a `string` or a `function`.
|
|
|
|
If a `string` is given, then it must have one of the following values.
|
|
Values: ~
|
|
"default" sort case-insensitively by {fname}
|
|
"directories_first" groups files of like {ftype} and then sort within
|
|
groups case-insensitively by {fname}
|
|
|
|
If a `function` is given, it must be a comparison function which takes two
|
|
tables {left} and {right}, each describing a filesystem entry, which
|
|
returns `true` when {left} should appear before (i.e. above) {right} in
|
|
the directory buffer.
|
|
|
|
Both of the tables {left} and {right} have the following fields.
|
|
Fields: ~
|
|
{fname} `string` containing the literal, unescaped name of the
|
|
filesystem entry without any suffixes (e.g. a directory
|
|
example/ would have an fname of "example")
|
|
{ftype} `string` describing the type of the filesystem entry, which
|
|
must be one of "file", "directory", "link", "fifo", "socket",
|
|
"char", or "block"
|
|
{path} `string` containing the full path of the filesystem entry
|
|
using platform-specific directory separators (i.e. "\" on
|
|
Windows and "/" on Linux and MacOS) without a suffix
|
|
|
|
|write_cmd| (default: `"DirbufSync"`)
|
|
What command Dirbuf should execute when the user issues a `:write`.
|
|
|
|
Examples: ~
|
|
"DirbufSync -confirm"
|
|
Requests confirmation from the user before syncing the changes
|
|
made to the directory buffer.
|
|
|
|
"" or "echoerr ':write disabled'"
|
|
Disables `:write` in directory buffers, forcing users to
|
|
explicitly invoke `:DirbufSync`.
|
|
|
|
==============================================================================
|
|
FAQ *dirbuf-faq*
|
|
|
|
Can I conceal hashes in directory buffers? ~
|
|
Dirbuf does not natively support `conceal` on hashes because the author
|
|
believes seeing the hashes is important to making Dirbuf's actions
|
|
predictable and wants to dissuade new users from hiding the hashes.
|
|
|
|
However, if you really want to conceal the hashes, you can create a
|
|
`after/syntax/dirbuf.vim` file with the following code which modifies the
|
|
normal DirbufHash definition to support `conceal`. >
|
|
syntax clear DirbufHash
|
|
syntax match DirbufHash /^#\x\{8}\t/ms=s-1 conceal cchar=#
|
|
setlocal conceallevel=2
|
|
setlocal concealcursor=n
|
|
|
|
If you feel strongly that Dirbuf should natively support `conceal` on hashes,
|
|
+1 this issue and I will consider it: >
|
|
https://github.com/elihunter173/dirbuf.nvim/issues/23
|
|
|
|
==============================================================================
|
|
CREDITS *dirbuf-credits*
|
|
|
|
Dirbuf was initially conceived of as a Lua rewrite of the file manager plugin
|
|
Dirvish and eventually grew in scope to become an editable directory buffer
|
|
similiar to vidir. However, it still owes many of its ideas to Dirvish as well
|
|
as much of its literal Vimscript and help documentation.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=4:et:ft=help:norl:
|