*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 mapping and their default mapping. If a mapping to the version already exists, then the default mapping is not made. Global ~ (dirbuf_up) - Opens the current file's directory or the [count]th parent directory. Buffer-local (filetype=dirbuf) ~ (dirbuf_up) - Opens the current file's directory or the [count]th parent directory. (dirbuf_enter) Opens file or directory at cursor. (dirbuf_toggle_hide) gh Toggles whether hidden files (i.e. dot files) are displayed. (dirbuf_history_forward) Moves forward [count] times in the directory buffer history. (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: