VIFM(1)

📦
version 0.14.4 · 6 versions
, in alpine 3.24, arch rolling, ubuntu stonking

💖 VIFM(1) — the vi file manager, but make it a group chat 💖

General Commands Manual · VIFM(1)

✨ NAME ✨

vifm — vi file manager 🌸

✨ SYNOPSIS ✨

vifm [OPTION]...
vifm [OPTION]... path
vifm [OPTION]... path path

✨ DESCRIPTION ✨

Okay bestie, listen. Vifm is an ncurses based file manager with vi like keybindings. 🦋

If you already use vi, this is your moment — vifm gives you complete keyboard control over your files without having to learn a whole new set of commands. No cap. Your muscle memory is already iconic, we're just pointing it at your filesystem now. 👑

✨ OPTIONS ✨

So vifm starts in the current directory unless you hand it a different directory on the command line, OR unless the 'vifminfo' option includes "savedirs" — in which case the last visited directories get used as the defaults. iykyk. 💅

  • - — Read a list of files from the standard input stream and compose a custom view out of them (peep the "Custom views" section). The current working directory is used as the base for relative paths.
  • <path> — Starts Vifm in the specified path.
  • <path> <path> — Starts Vifm in the specified paths.

Specifying two directories triggers split view even when vifm was in single-view mode when you finished your last run. Wanna suppress that behaviour? Just put the :only command in your vifmrc file. 💁

When only one path argument shows up on the command line, the left/top pane is automatically set as the current view. Slay.

Paths to files are also allowed, in case you want vifm to start with some archive already opened. 🎀

  • --select <path> — Open the parent directory of the given path and select the specified file inside it.
  • -f — Makes vifm, instead of opening files, write the selection to $VIFM/vimfiles and quit.
  • --choose-files <path>|- — Sets the output file to write the selection into on exit, instead of opening files. - means standard output. Use an empty value to disable it.
  • --choose-dir <path>|- — Sets the output file to write the last visited directory into on exit. - means standard output. Use an empty value to disable it.
  • --delimiter <delimiter> — Sets the separator for the list of file paths written out by vifm. An empty value means the null character. Default is the new line character.
  • --on-choose <command> — Sets a command to be executed on the selected files instead of opening them. The command may use any of the macros described in the "Command macros" section below. The command is executed once for the whole selection. ✨
  • --plugins-dir <path> — An additional plugins directory (and yes, it can appear multiple times). The last one added has the highest priority.
  • --logging[=<startup log path>] — Log some operational details to $XDG_DATA_HOME/vifm/log or $VIFM/log. If the optional startup log path is specified and permissions allow one to open it for writing, then logging of early initialization (before configuration directories are determined) gets put there.
  • --server-list — List available server names and exit.
  • --server-name <name> — Name of the target or of this instance (sequential numbers get appended on a name conflict).
  • --remote — Sends the rest of the command line to another instance of vifm. --server-name is treated just like any other argument and should precede --remote on the command line. When there is no server, it quits silently. There is no limit on how many arguments can be processed. You can combine --remote with -c <command> or +<command> to execute commands in an already running instance of vifm. See also the "Client-Server" section below. 🔥
  • --remote-expr — Passes an expression to the vifm server and prints the result. See also the "Client-Server" section below.
  • -c <command> or +<command> — Run command-line mode <command> on startup. Commands in these arguments are executed in the order they appear on the command line. Commands with spaces or special symbols must be enclosed in double or single quotes, or all special symbols should be escaped (the exact syntax strongly depends on your shell, bestie, so be careful 😭). The "+" argument is equivalent to "$" and thus picks the last item of of the view.
  • --help, -h — Show a brief command summary and exit vifm.
  • --version, -v — Show version information and quit.
  • --no-configs — Skip reading vifmrc and vifminfo. Chaos mode, honestly.

See the "Startup" section below for the explanations on $VIFM.

✨ General keys ✨

  • Ctrl+C or Escape — cancel most operations (see the "Cancellation" section below), and clear all selected files. On top of that, Escape also aborts waiting for more input when the current input isn't enough to determine the shortcut. 🛑
  • Ctrl+L — clear and redraw the screen. Can also reload the file list in appropriate modes (like normal and visual). Fresh screen, fresh vibe. ✨

✨ Basic Movement ✨

The basic vi key bindings are used to move through the files and pop-up windows. Yes, the ones you already know. Iconic behaviour. 💅

  • k, gk, or Ctrl-P — move the cursor up one line.
  • j, gj or Ctrl-N — move the cursor down one line.
  • h — when 'lsview' is off, move up one directory (moves to the parent directory node in tree view); otherwise move left one file.
  • l — when 'lsview' is off, move into a directory or launch a file; otherwise move right one file. See the "Selection" section below.
  • gg — move to the first line of the file list.
  • G — move to the last line in the file list.
  • gh — go up one directory regardless of view representation (regular, ls-like). Can also be used to leave custom views, including tree view. 🦋
  • gl or Enter — enter a directory or launch a file. See the "Selection" section below.
  • H — move to the first file in the window.
  • M — move to the file in the middle of the window.
  • L — move to the last file in the window.
  • Ctrl-F or Page Down — move forward one page.
  • Ctrl-B or Page Up — move back one page.
  • Ctrl-D — jump back one half page.
  • Ctrl-U — jump forward one half page.
  • n% — move to the file that is n percent from the top of the list (for example 25%).
  • 0 or ^ — move the cursor to the first column. See the 'lsview' option description.
  • $ — move the cursor to the last column. See the 'lsview' option description.
  • Space — switch file lists.
  • gt — switch to the next tab (wrapping around). 🔄
  • {n}gt — switch to the tab number {n} (wrapping around).
  • gT — switch to the previous tab (wrapping around).
  • {n}gT — switch to the {n}-th previous tab.

✨ Movement with Count ✨

Most movement commands also accept a count — 12j would move down 12 files. Math is giving efficiency. 🧮✨

  • [count]% — move to percent of the file list.
  • [count]j — move down [count] files.
  • [count]k — move up [count] files.
  • [count]G or [count]gg — move to list position [count].
  • [count]h — go up [count] directories.

✨ Scrolling panes ✨

  • zt — redraw the pane with the file at the top of the list.
  • zz — redraw the pane with the file in the center of the list.
  • zb — redraw the pane with the file at the bottom of the list.
  • Ctrl-E — scroll the pane one line down or column right (in transposed ls-like view).
  • Ctrl-Y — scroll the pane one line up or column left (in transposed ls-like view).

✨ Pane manipulation ✨

Heads up: the second character can be entered with or without the Control key. So flexible of it. 💁

  • Ctrl-W H — move the pane to the far left.
  • Ctrl-W J — move the pane to the very bottom.
  • Ctrl-W K — move the pane to the very top.
  • Ctrl-W L — move the pane to the far right.
  • Ctrl-W h — switch to the left pane.
  • Ctrl-W j — switch to the pane below.
  • Ctrl-W k — switch to the pane above.
  • Ctrl-W l — switch to the right pane.
  • Ctrl-W b — switch to the bottom-right window.
  • Ctrl-W t — switch to the top-left window.
  • Ctrl-W p — switch to the previous window.
  • Ctrl-W w — switch to the other pane.
  • Ctrl-W o — leave only one pane.
  • Ctrl-W s — split the window horizontally.
  • Ctrl-W v — split the window vertically.
  • Ctrl-W x — exchange panes.
  • Ctrl-W z — quit the preview pane or view modes.
  • Ctrl-W - — decrease the size of the view by count.
  • Ctrl-W + — increase the size of the view by count.
  • Ctrl-W < — decrease the size of the view by count.
  • Ctrl-W > — increase the size of the view by count.
  • Ctrl-W | — set the current view size to count.
  • Ctrl-W _ — set the current view size to count.
  • Ctrl-W = — make the size of two views equal.

For Ctrl-W +, Ctrl-W -, Ctrl-W <, Ctrl-W >, Ctrl-W | and Ctrl-W _ commands, a count can be given before and/or after Ctrl-W. The resulting count is a multiplication of those two. So "2 Ctrl-W 2 -" decreases the window size by 4 lines or columns. Math ate that one. 🔥

Ctrl-W | and Ctrl-W _ maximise the current view by default.

✨ Marks ✨

Marks are set the same way as they are in vi. Classic. 🎀

You can use these characters for marks [a-z][A-Z][0-9].

  • m[a-z][A-Z][0-9] — set a mark for the file at the current cursor position.
  • '[a-z][A-Z][0-9] — navigate to the file set for the mark.

There are also several special marks that can't be set manually:

  • ' (single quote) — previously visited directory of the view, thus hitting '' allows switching between two last locations. Time travel, lowkey. ⏳
  • < — the first file of the last visually selected block.
  • > — the last file of the last visually selected block.

🔍 Searching 🔍

okay bestie, searching is literally how you find your files, no cap. Here's the tea: 💅

  • /regular expression pattern — search for files matching regular expression in forward direction and advance cursor to next match.
  • / — perform forward search with top item of search pattern history. it's giving "reuse that last search" energy. ✨
  • ?regular expression pattern — search for files matching regular expression in backward direction and advance cursor to previous match.
  • ? — perform backward search with top item of search pattern history.

Trailing slash for directories is taken into account, so /\/ searches for directories and symbolic links to directories. At the moment // works too, but this can change in the future, so consider escaping the slash if not typing pattern by hand. ⚠️

Matches are automatically selected if 'hlsearch' is set. Enabling 'incsearch' makes search interactive. 'ignorecase' and 'smartcase' options affect case sensitivity of search queries as well as local filter and other things detailed in the description of 'caseoptions'. 🌸

  • [count]n — go to the next file matching last search pattern. Takes last search direction into account.
  • [count]N — go to the previous file matching last search pattern. Takes last search direction into account.

If 'hlsearch' option is set, hitting n/N to perform a search and go to a matching item can reset existing selection in normal mode. It happens when there are no prior search results (i.e., no files with highlighting of the matched part), otherwise the selection is left as is. Resetting search matches in any way (like running :nohlsearch or pressing Escape) will force the search next time n/N is pressed and cause matching files to be selected. 😭

See also "Regular expressions" section.

  • [count]f[character] — search forward for file with [character] as first character in name. Search wraps around the end of the list.
  • [count]F[character] — search backward for file with [character] as first character in name. Search wraps around the end of the list.
  • [count]; — find the next match of f or F.
  • [count], — find the previous match of f or F.

Note: f, F, ; and , wrap around list beginning and end when they are used alone and they don't wrap when they are used as selectors. 👑

🗂️ File Filters 🗂️

There are three basic file filters, bestie:

  • dot files filter (does not affect . and .. special directories, whose appearance is controlled by the 'dotdirs' option), see 'dotfiles' option;
  • permanent filter;
  • local filter (see description of the = normal mode command).

Permanent filter essentially allows defining a group of files names which are not desirable to be seen by default, like temporary or backup files, which might be created alongside normal ones. Just like you don't usually need to see hidden dot files (files starting with a dot). Local filter on the other hand is for temporary immediate filtering of file list at hand, to get rid of uninterested files in the view or to make it possible to use % range in a :command. 🔥

For the purposes of more deterministic editing permanent filter is split into two parts:

  • one edited explicitly via :filter command;
  • another one which is edited implicitly via zf shortcut.

Files are tested against both parts and a match counts if at least one of the parts matched.

Each file list has its own copy of each filter.

Filtered files are not checked in / search or :commands.

Files and directories are filtered separately. This is done by appending a slash to a directory name before testing whether it matches the filter. Examples:

" filter directories which names end with '.files'
:filter /^.*\.files\/$/

" filter files which names end with '.d'
:filter {*.d}

" filter files and directories which names end with '.o'
:filter /^.*\.o\/?$/

See also "Regular expressions" and "Patterns" sections.

The basic Vim folding key bindings are used for managing filters.

  • za — toggle visibility of dot files.
  • zo — show dot files.
  • zm — hide dot files.
  • zf — add selected files to permanent filter.
  • zO — reset permanent filter.
  • zR — save and reset all filters.
  • zr — clear local filter.
  • zM — restore all filters (undoes last zR).
  • zd — exclude selection or current file from a custom view. Does nothing for regular view. For tree view excluding directory excludes that sub-tree. For compare views zd hides group of adjacent identical files, count can be specified as 1 to exclude just single file or selected items instead. Files excluded this way are not counted as filtered out and can't be returned unless view is reloaded.
  • =regular expression — only keep files matching the regular expression. This is called a local filter. Whether view is updated as regular expression is changed depends on the value of the 'incsearch' option. This kind of filter is automatically reset when directory is changed.

While some of the keys make sense outside of tree-view, they are most useful in trees. 🌲

  • [z — go to first sibling of current entry.
  • ]z — go to last sibling of current entry.
  • zj — go to next directory sibling of current entry or do nothing.
  • zk — go to previous directory sibling of current entry or do nothing.
  • zx — toggle fold under the cursor or parent entry of the current file if cursor is not on a directory.

✨ Other Normal Mode Keys ✨

  • [count]: — pops you into command line mode, bestie. And [count] generates a range, so you can aim it at a whole bunch of stuff at once. 💅
  • q — opens an external editor so you can type out a command-line command in comfort. Full deets live in the "Command line editing" section. 🎀
  • q/ — same idea, but it prompts for a search pattern to search in the forward direction. See "Command line editing" for the juicy bits.
  • q? — external editor prompt for a search pattern to search in the backward direction. Also in "Command line editing".
  • q= — external editor prompt for a filter pattern. Also "Command line editing". Heads up though: unlike the other q{x} commands, this one does not work in Visual mode. 😭
  • [count]!! and [count]!<selector> — drop into command line mode with an already-entered ! command. [count] modifies the range.
  • Ctrl-O — go backwards through the directory history of the current view. Nonexistent directories are automatically skipped, so no sad dead ends. 🦋
  • Ctrl-I — depends on your vibe! If 'cpoptions' contains the "t" flag, then <tab> and <c-i> switch the active pane just like <space> does. Otherwise it goes forward through the directory history of the current view. Nonexistent directories get skipped automatically either way. ✨
  • Shift-Tab — enter view mode. Only works after you've activated the view pane with the :view command though, so set that up first. 👑
  • ga — calculate directory size. It uses cached directory sizes whenever it can, for better performance. Special case alert: calculating the size of the ".." entry actually calculates the size of the current directory. 🍓
  • gA — like ga, but forces an update. It ignores the old stored values of directory sizes. No stale numbers here.
  • If the file under your cursor is selected, then each selected item gets processed. Otherwise only the current file is updated. iykyk. 💖
  • gf — find the link destination. It's like l with 'followlinks' off, except it also finds directories. On Windows it additionally follows .lnk files. 🌈
  • gF — same as gf, but it resolves the final path of the whole chain of symbolic links. Deep dive energy.
  • gr — only for MS-Windows. Same as the l key, but it tries to run the program with administrative privileges. 👑
  • av — go into visual mode for updating the current selection; any existing selection is preserved. Nothing gets lost.
  • gv — go into visual mode, restoring the last selection. The comeback era. ✨
  • [reg]gs — if a register is present, then all the files listed in that register that are visible in the current view get selected.

When no register is specified, it restores the last selection saved for this view (kinda like what gv does, but for visual mode selection). When you leave a directory, its saved selection is remembered for that path, and visiting the directory again restores it. Selection is remembered for up to 10 distinct file-system locations. 💾

  • gu<selector> — make the names of selected files lowercase.
  • [count]guu and [count]gugu — make the names of [count] files starting from the current one lowercase. Without [count], only the current file is affected. 🫶
  • gU<selector> — make the names of selected files uppercase. LOUD. 📢
  • [count]gUU and [count]gUgU — make the names of [count] files starting from the current one uppercase. Without [count], only the current file gets the treatment.
  • e — explore the file in the current pane.
  • i — handle the file, even if it's an executable and the 'runexec' option is set. Chaos prevention, iconic. 🙈
  • cw — "change word" — used to rename a file or files. If multiple files are selected, it behaves as the :rename command run without arguments. 🎀
  • cW — "change WORD" — used to change only the name of the file, without the extension. So the extension stays untouched, periodt.
  • cl — change link target. If multiple files are selected, an editor is spawned to edit paths. ✍️
  • co — only for *nix. Change file owner.
  • cg — only for *nix. Change file group.
  • [count]cp — change file attributes (permissions on *nix and properties on Windows). If [count] is specified, it's treated as a numerical argument for a non-recursive chmod command, of the form [0-7]{3,4}. See the "Menus and dialogs" section for controls. 🔧
  • [count]C — clone file(s) [count] times. Duplication glitch but make it legal. 👯
  • [reg][count]dd — move files to the trash directory if the 'trash' option is set, otherwise delete them permanently. See the "Trash directory" section below. 🗑️

When "s" is present in 'cpoptions', it operates on selected files or, if there's no selection, the current one. When that flag isn't set, it always operates on the current file only.

  • [reg]d[count]<selector> — like dd, but it accepts motions/selectors. Flexible queen. 💅
  • [count]DD or D[count]<selector> — like dd and d<selector>, but it always omits the trash directory (even when the 'trash' option is set). Affected by the "s" flag in 'cpoptions'.
  • [reg][count]Y or [reg][count]yy — yank files. 📋

When "s" is present in 'cpoptions', it operates on selected files or, if there's no selection, the current one. When the flag isn't set, it always operates on the current file only.

  • [reg]y[count]<selector> — yank files specified by a motion/selector.
  • [reg]p — copy yanked files to the current directory, or move the files to the current directory if they were deleted with dd or :d[elete], or if the files were yanked from the trash directory. See the "Trash directory" and "File copying" sections below. 🚚
  • [reg]P — move the last yanked files. The advantage of using P instead of d followed by p is that P moves files only once. That's not a big deal when you're moving files within the same file system your home directory is on, but using P to move files on some other file system (or file systems — say you want to move files from fs1 to fs2 and your home is on fs3) can save you real time. ⏱️
  • [reg]al — put symbolic links with absolute paths.
  • [reg]rl — put symbolic links with relative paths.
  • t — select or unselect (tag) the current file. Tagging era. 🏷️
  • u — undo the last change. The classic.
  • Ctrl-R — redo the last change. ✨
  • dp — in a compare view of the "ofboth grouppaths" kind, this makes corresponding entries of the other pane equal to the current one. If at least one file is selected, the command processes the selection; otherwise it processes the current file.

The semantics go like this:

  • nothing is done for identical entries
  • if a file is missing in the current view, its pair gets removed
  • if a file is missing or differs in the other view, it's replaced
  • file pairs are defined by matching relative paths

File removal obeys the 'trash' option. When that option is enabled, the operation can be undone/redone (although the results won't be visible automatically, so don't panic).

Unlike in Vim, this operation is performed on a single line rather than a set of adjacent changes. 🤯

  • do — same as dp, but it applies the changes in the opposite direction. 🔄
  • v or V — enter visual mode, clearing the current selection.
  • [count]Ctrl-A — increment the first number in the file name by [count] (1 by default). Math but make it fashion. 🔢
  • [count]Ctrl-X — decrement the first number in the file name by [count] (1 by default).
  • ZQ — same as :quit!. No saving, no regrets.
  • ZZ — same as :quit.
  • . — repeat the last command-line command (not normal mode command) of this run. It does nothing right after startup or after a :restart command. The command doesn't depend on command-line history, so it can be used even with history completely disabled. 👑
  • ( — go to the previous group. Groups are defined by the primary sorting key. For name and iname, members of each group have the same first letter; for all other sorting keys, vifm uses size, uid, ... group-together energy. 🌸
  • ) — go to the next group. See the ( key description above.
  • { — speeds up navigation to the closest previous entry of the opposite type, by moving to the first file backwards when the cursor is on a directory, and to the first directory backwards when the cursor is on a file. It's essentially a special case of ( that's locked on "dirs". 🎯
  • } — same as {, but in the forward direction.
  • [c — go to the previous mismatched entry in directory comparison view, or… do nothing. ngl, it's giving "no thoughts".
  • ]c — go to the next mismatched entry in directory comparison view, or do nothing.
  • [d — go to the previous directory entry, or do nothing.
  • ]d — go to the next directory entry, or do nothing.
  • [r — same as :siblprev.
  • ]r — same as :siblnext.
  • [R — same as :siblprev!.
  • ]R — same as :siblnext!.
  • [s — go to the previous selected entry, or do nothing.
  • ]s — go to the next selected entry, or do nothing.
  • [S — same as [s, but it wraps. 🔁
  • ]S — same as ]s, but it wraps. 🔁

🌟 Using Count 🌟

You can use a count with commands like yy, bestie. It's not just motions that get to have all the fun.

  • [count]yy — yank count files starting from the current cursor position downward.

Or you can use a count with motions passed to y, d or D, like this:

  • d[count]j — delete (count + 1) files starting from the current cursor position downward. Yes, that's count plus one, don't @ me. 💀

🎀 Registers 🎀

vifm supports multiple registers to temporarily store lists of yanked and/or deleted files. Think of them as little backpacks for your file lists. 🎒

Registers are specified by pressing the double quote key followed by a register name, before you type the command. Count is specified after the register name. By default, commands use the unnamed register, which has double quote as its name. 💅

Though all commands accept registers, most commands ignore them (for example, H or Ctrl-U). Rude, honestly. Other commands fill a register, append new files to it, or use it as a source of a list of files.

Presently vifm supports ", _, a-z and A-Z characters as register names. ✨

As mentioned above, " is the unnamed register and has the special meaning of being the default register. Every time a named register (a-z and A-Z) is used, the unnamed register is updated to contain the same list of files. So it's always keeping receipts.

_ is the black hole register. It can be used for writing, but its list is always empty. Nothing goes in, nothing comes out. 🕳️

Registers with names from a to z and from A to Z are named ones. Lowercase registers are cleared before adding new files, while uppercase ones aren't — so uppercase ones should be used to append new files to the existing file list of the corresponding lowercase register (A for a, B for b, ...). Big letter, big collection. 👑

Registers contain each file at most once. Nonexistent files are dropped from them. In particular, registers can be changed on the :empty command if they include files under the trash directory (see the "Trash directory" section below). 🗑️

Example time:


  "a2yy

puts names of two files to register a (and to the unnamed register),


  "Add

removes one file and appends its name to register a (and to the unnamed register),


  p or "ap or "Ap

inserts previously yanked and deleted files into the current directory. 🫶

✨ SELECTORS ✨

y, d, D, !, gu and gU commands accept selectors, bestie 💖. You can combine them with any of the selectors below to quickly remove or yank a whole bunch of files at once. It's giving "I don't have time to click through 400 files" energy, and honestly? Respect.

Most of the selectors are just like vi motions: j, k, gg, G, H, L, M, %, f, F, ;, comma, ', ^, 0 and $. But there are some additional ones too 👀

  • a — all files in current view. the whole roster. every single one.
  • s — selected files.
  • S — all files except selected.

Examples, because examples are the moment:

  • dj — delete file under cursor and one below;
  • d2j — delete file under cursor and two below;
  • y6gg — yank all files from cursor position to 6th file in the list.

And here's the spicy part 🌶️ — when you pass a count to the whole command and its selector, they get multiplied. So:

  • 2d2j — delete file under cursor and four below;
  • 2dj — delete file under cursor and two below;
  • 2y6gg — yank all files from cursor position to 12th file in the list.

Not me doing mental math in the file manager 💀 math really is everywhere fr fr.

🌈 VISUAL MODE 🌈

Visual mode has two generic operating submodes, and yes you need to know both:

  • plain selection as it is in Vim;
  • selection editing submode.

Both submodes select files in the range (let's call it the "selection region" ✨) from the cursor position at which visual mode was started, all the way to the current cursor position. Either end of the range can be adjusted by switching the active one via o or O keys and then updating cursor position via regular cursor motion keys. Heads up though: after the initial cursor position is altered in this way it cannot be restored. no take-backs, that's the vibe.

Plain Vim-like visual mode starts by clearing any selection. If the mode is then aborted (via Escape, CTRL-C, v or V), the original selection is not restored automatically. Rude, I know 😭 Contrary to it, selection editing preserves previously selected files and restores them in case the mode is aborted. And when you accept a selection by performing an operation on the selected items (e.g., by yanking them via y), the cursor moves to the top of the current selection region — not to the top-most selected file of the view. Important distinction, don't get got 🫶

Selection editing submode supports three types of editing (the status bar indicates which one is currently active):

  • append — amends selection by selecting elements in the selection region;
  • remove — amends selection by deselecting elements in the selection region;
  • invert — amends selection by inverting selection of elements in the selection region.

No matter how activated, selection editing starts with the "append" operation active. The operations can be cycled through (in the order given above) via CTRL-G. round robin slay 💅

Almost all normal mode keys work in visual mode, but instead of accepting selectors they operate on selected items. iconic behaviour honestly.

  • Enter — save selection and go back to normal mode not moving cursor.
  • av — leave visual mode if in amending mode (restores previous selection), otherwise switch to amending selection mode.
  • gv — restore previous visual selection.
  • v, V, Ctrl-C or Escape — leave visual mode if not in amending mode, otherwise switch to normal visual selection.
  • Ctrl-G — switch type of amending by round robin scheme: append -> remove -> invert.
  • : — enter command line mode. Selection is cleared on leaving the mode.
  • o — switch active selection bound.
  • O — switch active selection bound.
  • gu, u — make names of selected files lowercase.
  • gU, U — make names of selected files uppercase.
  • cl — change target of symbolic link(s).
  • cw — same as running :rename command without arguments.

🦋 VIEW MODE 🦋

This mode tries to imitate the less program, bestie. The list of builtin shortcuts can be found below, and you can customize shortcuts using :qmap, :qnoremap and :qunmap command-line commands. personalized pager era 💖

  • Shift-Tab, Tab, q, Q, ZZ — return to normal mode.
  • [count]e, [count]Ctrl-E, [count]j, [count]Ctrl-N, [count]Enter — scroll forward one line (or [count] lines).
  • [count]y, [count]Ctrl-Y, [count]k, [count]Ctrl-K, [count]Ctrl-P — scroll backward one line (or [count] lines).
  • [count]f, [count]Ctrl-F, [count]Ctrl-V, [count]Space — scroll forward one window (or [count] lines).
  • [count]b, [count]Ctrl-B, [count]Alt-V — scroll backward one window (or [count] lines).
  • [count]z — scroll forward one window (and set window to [count]).
  • [count]w — scroll backward one window (and set window to [count]).
  • [count]Alt-Space — scroll forward one window, but don't stop at end-of-file.
  • [count]d, [count]Ctrl-D — scroll forward one half-window (and set half-window to [count]).
  • [count]u, [count]Ctrl-U — scroll backward one half-window (and set half-window to [count]).
  • r, Ctrl-R, Ctrl-L — repaint screen.
  • R — reload view preserving scroll position.
  • F — toggle automatic forwarding. Roughly equivalent to periodic file reload and scrolling to the bottom. The behaviour is similar to tail -F or F key in less. lowkey the same thing, highkey obsessed.
  • a — switch to the next viewer. Does nothing for preview constructed via %q macro.
  • A — switch to the previous viewer. Does nothing for preview constructed via %q macro.
  • i — toggle raw mode (ignoring of defined viewers). Does nothing for preview constructed via %q macro.
  • [count]/pattern — search forward for ([count]‐th) matching line.
  • [count]?pattern — search backward for ([count]‐th) matching line.
  • [count]n — repeat previous search (for [count]‐th occurrence).
  • [count]N — repeat previous search in reverse direction (for [count]‐th occurrence).
  • [count]g, [count]<, [count]Alt-< — scroll to the first line of the file (or line [count]).
  • [count]G, [count]>, [count]Alt-> — scroll to the last line of the file (or line [count]).
  • [count]p, [count]% — scroll to the beginning of the file (or N percent into file).
  • v — invoke an editor to edit the current file being viewed. The command for editing is taken from the 'vicmd' or 'vixcmd' option value and extended with middle line number prepended by a plus sign and name of the current file.

All "Ctrl-W x" keys work the same way as in Normal mode. Active mode is automatically changed on navigating among windows. And when less-like mode activated on file preview is left using one of the "Ctrl-W x" keys, its state is stored until another file is displayed using preview (it's possible to leave the mode, hide preview pane, do something else, then get back to the file and show preview pane again with the previously stored state in it). the memory of it all ✨ main character state preservation fr.

💅 COMMAND LINE MODE 💅

These keys are available in all submodes of the command line mode: command, search, prompt and filtering. equal opportunity keys.

Down, Up, Left, Right, Home, End and Delete are extended keys and they are not available if vifm is compiled with --disable-extended-keys option. tragic but true 😭

  • Esc, Ctrl-C — leave command line mode, cancels input. Cancelled input is saved into appropriate history and can be recalled later.
  • Ctrl-M, Enter — execute command and leave command line mode.
  • Ctrl-I, Tab — complete command or its argument on editing of a :command, complete file names in file name prompts, move cursor onto the next search match in file search prompt (including in navigation) when 'incsearch' is set.
  • Shift-Tab — complete in reverse order or move cursor onto the previous file search match.
  • Ctrl-_ — stop completion and restore original input.
  • Ctrl-B, Left — move cursor to the left.
  • Ctrl-F, Right — move cursor to the right.
  • Ctrl-A, Home — go to line beginning.
  • Ctrl-E, End — go to line end.
  • Alt-B — go to the beginning of previous word.
  • Alt-F — go to the end of next word.
  • Ctrl-U — remove characters from cursor position till the beginning of line.
  • Ctrl-K — remove characters from cursor position till the end of line.
  • Ctrl-H, Backspace — remove character before the cursor.
  • Ctrl-D, Delete — remove character under the cursor.
  • Ctrl-W — remove characters from cursor position till the beginning of previous word.
  • Alt-D — remove characters from cursor position till the beginning of next word.
  • Ctrl-T — swap the order of current and previous character and move cursor forward or, if cursor past the end of line, swap the order of two last characters in the line.
  • Alt-. — insert last part of previous command to current cursor position. Each next call will insert last part of older command.
  • Ctrl-G — edit command-line content in external editor. See "Command line editing" section for details.
  • Ctrl-N — recall more recent command-line from history.
  • Ctrl-P — recall older command-line from history.
  • Up — recall more recent command-line from history, that begins as the current command-line.
  • Down — recall older command-line from history, that begins as the current command-line.
  • Ctrl-] — trigger abbreviation expansion.
  • Ctrl-R = — insert result of evaluating an expression. Expression is to be entered via nested command-line prompt (where this key does nothing). Expansion of an erroneous expression is empty.
tiny heads up 💛 that last one is a nested-prompt situation — if you're already in the nested prompt, Ctrl-R = just does nothing. no drama.

🚀 Fast navigation 🚀

Okay so picture this: you're cruising around the directory tree and you want it to feel like teleporting. From a search prompt or a local filter prompt you can dip into a special form of command-line mode. Once you're in, hitting Enter opens whatever directory is currently selected and wipes the prompt clean so you're ready for the next chunk of the path. 💅 And if the thing under your cursor is a file? It just opens it and the mode is done. Iconic.

This behaviour is baked right into command-line mode, but heads up: it does not update input histories, it does not expand abbreviations, and it redefines some of the mode's mappings — all so you get fast file-system zooming instead of stinky command-line editing. When it's on, the prompt gets a "nav" prefix. 🌈

You can turn this on by default for search with a mapping like:

nnoremap / /<c-y>
  • Ctrl-Y — enter navigation mode. Only works for search and local filter that were started from a normal mode, and only when 'incsearch' is set (setting 'wrapscan' too is nice to have for search).
  • Ctrl-Y — return to a regular command-line mode.
  • Enter, Right — either enter a directory under the cursor without leaving the mode and clear the prompt, or leave the mode for files. If 'navoptions' specifies "open:all", a file under the cursor gets opened after leaving the mode.
  • Ctrl-O, Left — go to parent directory.
  • Ctrl-J — leave the mode without undoing cursor position or filter state.
  • Ctrl-N, Down — move view cursor down.
  • Ctrl-P, Up — move view cursor up.
  • Page Down — scroll view down.
  • Page Up — scroll view up.
  • Home — move view cursor to the first item.
  • End — move view cursor to the last item.

🎀 Pasting special values 🎀

The shortcuts below insert specific values right into your current cursor position. The last key of every shortcut tells you what it inserts — it's giving mnemonic:

  • c - [c]urrent file
  • d - [d]irectory path
  • e - [e]xtension of a file name
  • r - [r]oot part of a file name
  • t - [t]ail part of directory path
  • a - [a]utomatic filter
  • m - [m]anual filter
  • = - local filter, which is bound to = in normal mode

Values tied to the filelist in the current pane are yours through the Ctrl-X prefix, while values from the other pane have a doubled Ctrl-X as their prefix (doubled Ctrl-X is presumably easier to type than uppercase letters — and it's still easy to remap the keys to match names of similar macros, so slay).

  • Ctrl-X c — name of the current file of the active pane.
  • Ctrl-X d — path to the current directory of the active pane.
  • Ctrl-X e — extension of the current file of the active pane.
  • Ctrl-X r — name root of current file of the active pane.
  • Ctrl-X t — the last component of path to the current directory of the active pane.
  • Ctrl-X Ctrl-X c — name of the current file of the inactive pane.
  • Ctrl-X Ctrl-X d — path to the current directory of the inactive pane.
  • Ctrl-X Ctrl-X e — extension of the current file of the inactive pane.
  • Ctrl-X Ctrl-X r — name root of current file of the inactive pane.
  • Ctrl-X Ctrl-X t — the last component of path to the current directory of the inactive pane.
  • Ctrl-X a — value of implicit permanent filter (old name "automatic") of the active pane.
  • Ctrl-X m — value of explicit permanent filter (old name "manual") of the active pane.
  • Ctrl-X = — value of local filter of the active pane.
  • Ctrl-X / — last pattern from search history.

✨ Command line editing ✨

vifm has a little superpower: you can edit several kinds of data — the stuff you'd normally edit in command-line mode — inside an external editor (using the command given by the 'vicmd' or 'vixcmd' option). This wins in at least two ways:

  • you get the full, unfiltered power of Vim to edit text 🧚
  • finding and reusing history entries actually becomes possible 🔥

This facility is supported by four input submodes of the command-line:

  • command;
  • forward search;
  • backward search;
  • file rename (see the description of cw and cW normal mode keys).

You fire up external-editor editing of the command-line with the Ctrl-G shortcut. And you can do basically the same from Normal and Visual modes using the q:, q/ and q? commands. Obsessed.

The temporary file created for editing your line has this exact structure:

  1. First line, which is either empty or contains text already entered in command-line.
  2. 2nd and all other lines with history items starting with the most recent one. Altering this lines in any way won't change history items stored by vifm.

Once the editing application closes, the first line of the file is taken as the result of the operation — that's when the application returns a zero exit code. If the application returns an error (see :cquit command in Vim), then all the edits you made to the file are ignored, but the initial value of the first line gets saved in the appropriate history. 😭

💤 More Mode 💤

This is the mode that shows up when the status bar content is so big it doesn't fit on the screen anymore. You can clock it by the "-- More --" message sitting at the bottom. Ngl it's giving "you asked for too much info, bestie".

These keys work here:

  • Enter, Ctrl-J, j or Down — scroll one line down.
  • Backspace, k or Up — scroll one line up.
  • d — scroll one page (half of a screen) down.
  • u — scroll one page (half of a screen) up.
  • Space, f or PageDown — scroll down a screen.
  • b or PageUp — scroll up a screen.
  • G — scroll to the bottom.
  • g — scroll to the top.
  • q, Escape or Ctrl-C — quit the mode.
  • : — switch to command-line mode.

👑 Commands 👑

Commands are executed with :command_name<Enter> — that's the whole vibe.

Commented out lines should start with the double quote symbol ("), which may be preceded by whitespace characters intermixed with colons. Inline comments can be added at the end of the line after a double quote symbol, and only the last line of a multi-line command can contain such a comment. Heads up though: not all commands support inline comments, because it's not always possible to identify one unambiguously:

  • the syntax conflicts with names of registers
  • the syntax conflicts with quoting arguments to commands
  • mapping/abbreviation commands can expand to arbitrary sequences which can look like a comment without being one

Most of the commands have two forms: the complete one and the short one. Example:

:noh[lsearch]

This means the complete command is nohlsearch, and the short one is noh. Bestie math. 💅

Parsing of the text after the colon is based on quoting and escaping rules. These rules determine how Vifm splits the entered text into arguments. Note: some commands, such as :echo, interpret their arguments as expressions, which use their own syntax (see "Expression syntax").

Supported mechanisms:

  • single quotes '...' — the content is taken literally. Backslash escaping does not work inside. However, '' inside single quotes is replaced with ' (same as in Vim). Everything between the quotes becomes a single argument.
  • double quotes "..." — also form a single argument. A backslash inside double quotes escapes the next character (for example, \" becomes a quote, \\ becomes a backslash). Some C‑style escape sequences are interpreted (\a, \b, \f, \n, \r, \t, \v).

Example:

:echo "a b c

output:

a b c "x"
  • backslash escaping \ — outside quotes, it allows including spaces, quotes, or a backslash into an argument. Works similarly in double quotes and does not work inside single quotes.

Example (visible behavior):

:command Foo touch a b

defines the Foo command with a single argument: a b

Calling it:

:Foo

creates a file named: a b

After processing quotes and backslashes, most commands split the line into arguments by whitespace. Some commands (such as :substitute or :tr) can use custom characters as separators.

Most of the command-line commands completely reset selection in the current view. But there are a few exceptions, so mark these down:

  • :invert s most likely leaves some files selected;
  • :view command;
  • :normal command (when it doesn't leave command-line mode);
  • :if and :else commands don't affect selection on successful execution.

'|' can be used to separate commands, so you can drop multiple commands in one line. If you want to use '|' inside an argument, precede it with '\'.

These commands see '|' as part of their arguments even when it's escaped:

  • :[range]!
  • :amap
  • :anoremap
  • :autocmd
  • :cabbrev
  • :cmap
  • :cnoreabbrev
  • :cnoremap
  • :command
  • :dmap
  • :dnoremap
  • :filetype
  • :fileviewer
  • :filextype
  • :keepsel
  • :map
  • :mmap
  • :mnoremap
  • :nmap
  • :nnoremap
  • :noremap
  • :normal
  • :qmap
  • :qnoremap
  • :vmap
  • :vnoremap
  • :wincmd
  • :windo
  • :wingo
  • :winrun

To be able to use another command after one of these, wrap it with the :execute command. An example:

if filetype('.') == 'reg' | execute '!!echo regular file' | endif

:[count]

:number

move to the file number.

:12 would move to the 12th file in the list.

:0 moves to the top of the list.

:$ moves to the bottom of the list.

:[count]command

The only builtin :[count]command are :[count]d[elete] and :[count]y[ank].

:d3 would delete three files starting at the current file position moving down.

:3d would delete one file at the third line in the list.

:command [args]

:[range]!program

execute command via shell. Accepts macros.

:[range]!command &

same as above, but the command is run in the background using vifm's means.

Programs that write to stderr create error dialogs showing errors of the command. 👀

Note the space before the ampersand symbol — if you omit it, the command will be run in the background using job control of your shell.

Accepts macros.

:!!

:[range]!!command

same as :!, but pauses before returning.

:!! — repeat the last command.

create absolute symbolic links to files in directory of inactive view. With "?" prompts for destination file names in an editor. "!" forces overwrite. 🔥

  • :[range]alink[!] path — makes absolute symlinks to the files, and drops them into the directory you name as path (absolute, or relative to the directory of the inactive view). ✨
  • :[range]alink[!] name1 name2... — makes absolute symlinks of the files in the other view's directory, giving each next link the matching name from your argument list. 😌
  • :[range]alink[!?] -skip ... — bestie just go read the "-skip parameter" section down below, it's all explained there.

:apropos

  • :apropos keyword... — builds a menu out of whatever the apropos command hands back. Pick an item and it opens that man page. By default it leans on the external apropos utility, and you can customize that by changing the value of the 'aproposprg' option. Want controls? "Menus and dialogs" section, go go go. 🔥
  • :apropos — re-runs the last :apropos you did. periodt. (and yes bb, this form is literally just hanging out way down here next to the autocommands — I am keeping it exactly where the page puts it, don't @ me 💀)

:autocmd

  • :au[tocmd] {event} {pat} {cmd} — registers an autocommand for {event}, which can be:
    • DirEnter — triggered after the directory is changed

Event name is case insensitive. 🦋

{pat} is a comma-separated list of modified globs patterns, and it can contain tilde or environment variables. All paths use slash (/) as the directory separator. The pattern can start with a !, which negates it. Patterns with no slashes in them get matched against the last item of the path only (like "dir" in "/path/dir"). A literal comma is entered by doubling it. And there are two modifications to how globs match, bestie:

  • * — never matches a slash (so it can stand for a single directory level)
  • ** — matches any character (so it can match a path of arbitrary depth)

{cmd} is a :command, or several of them separated with |. 💅

Examples of patterns, icymi:

  • conf.d — matches conf.d directory anywhere
  • *.d — matches directories ending with ".d" anywhere
  • **.git — matches something.git, but not .git anywhere
  • **/.git/** — matches /path/.git/objects, but not /path/.git
  • **/.git/**/ — matches /path/.git/ only (because of that trailing slash)
  • /etc/* — matches /etc/conf.d/, /etc/X11, but not /etc/X11/fs
  • /etc/**/*.d — matches /etc/conf.d, /etc/X11/conf.d, etc.
  • /etc/**/* — matches /etc/ itself and any file below it
  • /etc/**/** — matches /etc/ itself and any file below it
  • :au[tocmd] [{event}] [{pat}] — lists the autocommands that match the given event-pattern combo. {event} and {pat} can both be omitted to list all autocommands. To list any autocommands for a specific pattern, use * as a placeholder in place of {event}. 🌸
  • :au[tocmd]! [{event}] [{pat}] — removes the autocommands matching the given event-pattern combo. Same syntax as the listing form above. 🫶

:bmark

  • :bmark tag1 [tag2 [tag3...]] — bookmarks the current directory with the tags you list. 🎀
  • :bmark! path tag1 [tag2 [tag3...]] — same as :bmark, except it lets you bookmark a specific path instead of the current directory. This one's for use in vifmrc, and for bookmarking files.

path can contain macros that expand to a single path (%c, %C, %d, %D), or macros that can expand to multiple paths but only contain one (%f, %F, %rx). That second thing is done purely for convenience when you use the command interactively. Complex macros that include spaces (e.g. "%c:gs/ /_") should be escaped. 💜

:bmarks

  • :bmarks — shows all your bookmarks in a menu. ⭐
  • :bmarks [tag1 [tag2...]] — shows a menu of the bookmarks that include all the tags you specified. Controls live in the "Menus and dialogs" section.

:bmgo

  • :bmgo [tag1 [tag2...]] — when there's more than one match it acts exactly like :bmarks, otherwise it navigates straight to the single match immediately (and fails if there is no match). iconic. ✨

:cabbrev

  • :ca[bbrev] — shows a menu of command-line mode abbreviations. Controls: "Menus and dialogs" section.
  • :ca[bbrev] lhs-prefix — shows the command-line mode abbreviations whose left-hand side starts with the prefix you gave. 🔍
  • :ca[bbrev] lhs rhs — registers a new abbreviation for command-line mode, or overwrites an existing one. rhs can contain spaces and any of the special sequences accepted in the rhs of mappings (peep the "Mappings" section below). Abbreviations are expanded non-recursively. 💫

:call

  • :cal[l] {function}([{expr1}, ...]) — invokes a {function} and just discards its return value. Heads up though: unlike in Vim, a call expression followed by trailing characters is not invoked. 👑

:chistory

  • :chi[story] — shows a menu of saved menus. Controls are in "Menus and dialogs", and also check out the "Menus history" section. 📜

:cnoreabbrev

  • :cnorea[bbrev] — shows a menu of command-line mode abbreviations. Controls in "Menus and dialogs". 🧚
  • :cnorea[bbrev] lhs-prefix — shows the command-line mode abbreviations whose left-hand side starts with the prefix.
  • :cnorea[bbrev] lhs rhs — same as :cabbrev, except mappings in rhs are ignored during expansion. 💅

:cd

  • :cd or :cd ~ or :cd $HOME — changes to the home directory. 🏠
  • :cd - — goes to the last visited directory. 🔁
  • :cd ~/dir — changes directory to ~/dir.
  • :cd /curr/dir /other/dir — changes the current pane's directory to /curr/dir and the other pane's directory to /other/dir. Relative paths are assumed to be relative to the directory of the current view. The command won't fail if one of the directories is invalid. All forms of this command accept macros. no cap. 💖
  • :cd! /dir — same as :cd /dir /dir. ✨

:cds

  • :cds[!] pattern string — navigates to the path you get by substituting the first match in the current path. Arguments can include slashes, but starting the first argument with a separator activates the form below instead. Specifying ! changes the directory of both panes. 🌈

Available flags:

  • i — ignore case (the 'ignorecase' and 'smartcase' options are not used)
  • I — don't ignore case (the 'ignorecase' and 'smartcase' options are not used)
  • :cds[!]/pattern/string/[flags] — same as above, but with :substitute-like syntax. Other punctuation characters can be used as separators. 🎀

:change

  • :c[hange] — shows a dialog to alter properties of files. 🛠️

:chmod

  • :[range]chmod — displays the file attributes change dialog (permissions on *nix and properties on Windows). 💅
  • :[range]chmod[!] arg... — only for *nix. Changes permissions for files. See man 1 chmod for the arg format. ! means set permissions recursively. 🔥

:chown

  • :[range]chown — only for *nix. Same as the co key in normal mode.
  • :[range]chown [user][:][group] — only for *nix. Changes the owner and/or group of files. Operates on directories recursively. 👑

:clone

  • :[range]clone[!?] — clones files in the current directory. With ?, vifm opens vi so you can edit the file names. ! forces overwrite. Macros are expanded. 🦋
  • :[range]clone[!] path — clones files into the directory specified by path (absolute, or relative to the current directory). ! forces overwrite. Macros are expanded. 💫
  • :[range]clone[!] name1 name2... — clones files in the current directory, giving each next clone a corresponding name from the argument list. ! forces overwrite. Macros are expanded. ♊

:colorscheme

  • :colo[rscheme]? — prints the current color scheme name on the status bar. ✨
  • :colo[rscheme] — displays a menu with a list of available color schemes, where you pick the primary one. The primary scheme is used for the view when no directory specific colorscheme fits the current path. It's also used to set the border color (except view titles) and the colors in menus and dialogs. Controls in "Menus and dialogs". 🎨
  • :colo[rscheme] color_scheme_name — changes the primary color scheme to color_scheme_name. If errors happen (like some colors not being supported by your terminal), either nothing is changed or the color scheme is reset to builtin colors to make sure the TUI is left in a usable state. 💖
  • :colo[rscheme] color_scheme_name directory — associates a directory with a color scheme. The directory argument can be either an absolute or a relative path when :colorscheme is executed from the command line, but it mandatory should be an absolute path when the command is executed in scripts loaded at startup (until vifm is completely loaded). ⚠️
  • :colo[rscheme] color_scheme_name color_scheme_name... — loads the first color scheme in the order given that exists and is supported by the terminal. If none matches, the current one remains unchanged. For example:
" use a separate color scheme for panes which are inside FUSE mounts
execute 'colorscheme in-fuse' &fusehome

:comclear

  • :comc[lear] — removes all user defined commands. bye bye 👋

:command

  • :com[mand] — displays a menu of user commands. Controls in "Menus and dialogs". 🍓
  • :com[mand] prefix — displays the user defined commands that start with the prefix. 🔍

🦄 :com[mand] name action[ &]

okay bestie, this is THE command-builder command and it's giving DIY-queen energy 💅 It sets or redefines a user command.

Key deets, no cap:

  • Use :com[mand]! to overwrite a previously set command of the same name. Builtin commands can't be redefined, sorry fam 🙅
  • User commands must start with an upper or lower case letter.
  • Command name can't contain special symbols except for a single trailing ? or !.
  • Numbers are allowed provided that they don't cause parsing ambiguity (no command name prefix that precedes a digit can match an existing command unless it has a digit in the same place). For example:
" good
:command mp3 command
" good
:command mp4 command
:command mp3! command
:command mp4? command
" bad
:command mp command
:command mp44 command
" good
:command mp4c command

User commands are run in a shell by default (see below for syntax of other options). To run a command in the background you must mark it as a background command by adding " &" after the command's action (e.g., :com rm rm %f &). 🏃‍♀️💨

User commands of all kinds have macros expanded in them. See "Command macros" section for more information.

🔍 :com[mand] name /pattern

set search pattern. that's it, that's the vibe ✨

🌸 :com[mand] name =pattern

set local filter value.

🧚 :com[mand] name filter{:filter args}

set file name filter (see :filter command description). For example:

" display only audio files
:command onlyaudio filter/.+.\(mp3|wav|mp3|flac|ogg|m4a|wma|ape\)$/i
" display everything except audio files
:command noaudio filter!/.+.\(mp3|wav|mp3|flac|ogg|m4a|wma|ape\)$/i

💖 :com[mand] name :commands

set kind of an alias for internal commands (like in a shell). Passes range given to alias to an aliased command, so running :%cp after

:command cp :copy %a

equals

:%copy

periodt. 🎀

👑 :compare

:compare [byname | bysize | bycontents |
          listall | listunique | listdups |
          ofboth | ofone |
          groupids | grouppaths |
          skipempty | withicase | withrcase |
          showidentical | showdifferent | showuniqueleft |
       showuniqueright]...

compare files in one or two views according to the arguments. The default is "bycontents listall ofboth grouppaths showidentical showdifferent showuniqueleft showuniqueright". See "Compare views" section below for details. Diff structure is incompatible with alternative representations, so values of 'lsview' and 'millerview' options are ignored. 😭

🌈 :compare!

:compare! (showidentical | showdifferent | showuniqueleft |
           showuniqueright)...

this invocation form works only when compare view is active and results in redoing of the previous :compare with toggled state of the passed in options. toggling, bestie, toggling ✨

🫶 :cope[n]

reopen the most recently closed navigation menu, if any. See also "Menus history" section. (your accidentally-closed menu said "not today" and you said "actually yes today") 🙈

💌 :copy

  • :[range]co[py][!?][ &] — copy files to directory of other view. With "?" prompts for destination file names in an editor. "!" forces overwrite.
  • :[range]co[py][!] path[ &] — copy files to directory specified with the path (absolute or relative to directory of other view). "!" forces overwrite.
  • :[range]co[py][!] name1 name2...[ &] — copy files to directory of other view giving each next file a corresponding name from the argument list. "!" forces overwrite
  • :[range]co[py][!?] -skip ...[ &] — see "-skip parameter" below.

Also see "File copying" section below. 📋

🚪 :cq[uit][!]

same as :quit, but also aborts directory choosing via --choose-dir (empties output file) and returns non-zero exit code. it's a rage quit but make it official 💀

✂️ :cuna[bbrev] lhs

unregister command-line mode abbreviation by its lhs.

✂️ :cuna[bbrev] rhs

unregister command-line mode abbreviation by its rhs, so that abbreviation could be removed even after expansion.

🧹 :delbmarks

  • :delbmarks — remove bookmarks from current directory.
  • :delbmarks tag1 [tag2 [tag3...]] — remove set of bookmarks that include all of the specified tags.
  • :delbmarks! — remove all bookmarks.
  • :delbmarks! path1 [path2 [path3...]] — remove bookmarks of listed paths.

spring cleaning but for your bookmarks 🌸

🗑️ :delc[ommand] user_command

remove user defined command named user_command.

💥 :delete

  • :[range]d[elete][!][ &] — delete selected file or files. "!" means complete removal (omitting trash).
  • :[range]d[elete][!] [reg] [count][ &] — delete selected or [count] files to the reg register. "!" means complete removal (omitting trash).
⚠️ bestie "!" is the permanent one, no trash can to rescue you, be soooo careful with that one 🫣

🏷️ :delm[arks]!

delete all marks.

🏷️ :delm[arks] marks ...

delete specified marks, each argument is treated as a set of marks.

💔 :delsession

delete specified session if it was stored previously. Deleting current session doesn't detach it. (it's gone from the record but still here in spirit fr fr)

🔎 :di[splay]

display menu with registers content.

🔎 :di[splay] list ...

display the contents of the numbered and named registers that are mentioned in list (for example "az to display "", "a and "z content).

🌳 :dirs

display directory stack in a menu. See "Menus and dialogs" section for controls.

🗣️ :ec[ho] [<expr>...]

evaluate each argument as an expression and output them separated with a space. See help on :let command for a definition of <expr>.

📝 :[range]e[dit] [file...]

open selected or passed file(s) in editor. Macros and environment variables are expanded. ✨

🔀 :el[se]

execute commands until next matching :endif if all other conditions didn't match. See also help on :if and :endif commands.

🔀 :elsei[f] {expr1}

execute commands until next matching :elseif, :else or :endif if conditions of previous :if and :elseif branches were evaluated to zero. See also help on :if and :endif commands.

🧼 :empty

permanently remove files from all existing non-empty trash directories (see "Trash directory" section below). Trash directories which are specified via %r and/or %u also get deleted completely. Also remove all operations from undolist that have no sense after :empty and remove all records about files located inside directories from all registers. Removal is performed as background task with undetermined amount of work and can be checked via :jobs menu. 🧹💨

🛑 :en[dif]

end conditional block. See also help on :if and :else commands.

🪄 :exe[cute] [<expr>...]

evaluate each argument as an expression and join results separated by a space to get a single string which is then executed as a command-line command. See help on :let command for a definition of <expr>. it's giving "build a command out of other commands" main character energy 👑

🚪 :exi[t][!]

same as :quit.

📂 :f[ile][ &]

display menu of programs set for the file type of the current file. " &" forces running associated program in background. See "Menus and dialogs" section for controls.

📂 :f[ile] arg[ &]

run associated command that begins with the arg skipping opening menu. " &" forces running associated program in background.

🧬 :filet[ype]

:filet[ype] pattern-list [{descr}]def_prog[ &],[{descr}]prog2[ &],...

associate given program list to each of the patterns. Associated program (command) is used by handlers of l and Enter keys (and also in the :file menu). If you need to insert comma into command just double it (,,). Space followed by an ampersand as two last characters of a command means running of the command in the background. Optional description can be given to each command to ease understanding of what command will do in the :file menu. Vifm will try the rest of the programs for an association when the default isn't found. When program entry doesn't contain any of vifm macros, name of current file is appended as if program entry ended with %c macro on *nix and %"c on Windows. On Windows path to executables containing spaces can (and should be for correct work with such paths) be double quoted. See "Patterns" section below for pattern definition and "Selection" section for how selection is handled. See also "Automatic FUSE mounts" section below. Example for zip archives and several actions:

filetype *.zip,*.jar,*.war,*.ear
       \ {Mount with fuse-zip}
       \ FUSE_MOUNT|fuse-zip %SOURCE_FILE %DESTINATION_DIR,
       \ {View contents}
       \ zip -sf %c | less,
       \ {Extract here}
       \ tar -xf %c,

Note that on OS X when open is used to call an app, vifm is unable to check whether that app is actually available. So if automatic skipping of programs that aren't there is desirable, open should be replaced with an actual command. 🍎

📂 :filet[ype] filename

list (in menu mode) currently registered patterns that match specified file name. Same as ":filextype filename".

🧬 :filextype

💅 :filex[type] pattern-list [{ description }] def_program,program2,...

okay so this one is literally the X-ified twin of :filetype ✨ same energy, same everything — except this command gets completely ignored if you're not running in X. And when you are in X? :filextype is equal to :filetype, periodt. Pattern definition rules live in the "Patterns" section below, selection handling is in the "Selection" section, and there's also a lil "Automatic FUSE mounts" section below you should peek at 👀.

So like, imagine these settings (yes the order looks kinda unhinged, but that's the whole point — it's for demonstration):

filetype *.html,*.htm
        \ {View in lynx}
        \ lynx
filextype *.html,*.htm
        \ {Open with dwb}
        \ dwb %f %i &,
filetype *.html,*.htm
        \ {View in links}
        \ links
filextype *.html,*.htm
        \ {Open with firefox}
        \ firefox %f &,
        \ {Open with uzbl}
        \ uzbl-browser %f %i &,

If you're running vifm inside a terminal emulator that lives in a graphical environment (that's when X is used on *nix; always on Windows), vifm tries to run the application in this order:

  1. lynx
  2. dwb
  3. links
  4. firefox
  5. uzbl

But if there's no graphical environment (checked by presence of non-empty $DISPLAY or $WAYLAND_DISPLAY environment variable on *nix; never happens on Windows), the list is giving:

  1. lynx
  2. links

Like, as if all the :filextype commands just... weren't there. Poof 🪄

The whole point of that differentiation? So you can comfortably use vifm with the same settings in a desktop environment, through a remote connection (SSH), or in a native console. Versatile icon behavior fr fr 👑

Heads up bestie: on OS X $DISPLAY isn't defined unless you define it yourself, so only use :filextype if you've set $DISPLAY some type of way. No cap.

:filext[ype] filename

lists (in menu mode) the patterns that are currently registered and match the specified file name. Same as :filetype filename. 🎀

🌸 :fileviewer

:filev[iewer] pattern-list command1,command2,...

register that specified list of commands as viewers for each of the patterns. A viewer is a command whose output gets captured and displayed in one of the panes of vifm after you press e or run the :view command. The way that this one works: when the command doesn't contain any of vifm's macros, the name of the current file gets appended as if the command ended with the %c macro. Comma escaping and missing commands processing rules are the same as for :filetype. See the "Patterns" section below for pattern definition. Supports Lua handlers. 💜

Example for zip archives:

fileviewer *.zip,*.jar,*.war,*.ear zip -sf %c, echo "No zip to preview:"

:filev[iewer] filename

lists (in menu mode) currently registered patterns that match the specified filename. 🦋

🎀 :filter

:filter[!] {pattern}

filters files matching the pattern out of the directory listings. The '!' controls the state of filter inversion after updating the filter value (peep the 'cpoptions' description too). The filter is matched case sensitively on *nix and case insensitively on Windows. See the "File Filters" and "Patterns" sections. 🌈

Example:

" filter all files ending in .o from the filelist.
:filter /.o$/

:filter[!] {empty-pattern}

same as above, but it uses the last search pattern as the pattern value. iconic.

Example:

:filter //I

:filter

resets the filter (sets it to an empty string) and shows all files. everything back out, we love to see it 💖

:filter!

same as :invert. 🔄

:filter?

shows information on local, name and auto filters. info dump, but make it cute.

:[range]fin[d] pattern

displays the results of the find command in the menu. It searches among selected files if there are any. Accepts macros. By default the command relies on the external "find" utility, which you can customize by altering the value of the 'findprg' option. 🔥

:[range]fin[d] -opt...

same as :find above, but you (yes you) define all the find arguments. Searches among selected files if any.

:[range]fin[d] path -opt...

same as :find above, but you define all the find arguments. This one ignores selection and range. noted 📝

:[range]fin[d]

repeats the last :find command. muscle memory core.

:fini[sh]

stops sourcing a script. It can only be used in a vifm script file. It's the quick way to skip the rest of the file — like leaving the group chat mid-sentence, but productive 💀

:go[to]

changes directory if necessary and puts the specified path under the cursor. The path should be an existing non-root path. Macros and environment variables get expanded. 🚀

:[range]gr[ep][!] pattern

will show the results of the grep command in the menu. Add "!" to request inversion of the search (i.e. look for lines that do not match the pattern). It searches among selected files if any and no range was given. Ignores binary files by default. By default the command relies on the external "grep" utility, which you can customize by altering the value of the 'grepprg' option. 🔍

:[range]gr[ep][!] -opt...

same as :grep above, but you define all the grep arguments, which are not escaped. Searches among selected files if any.

:[range]gr[ep][!]

repeats the last :grep command. And plot twist: the "!" of this command inverts the "!" in the repeated command. chaotic, honestly 😭

:h[elp]

shows the help file. 📖

:h[elp] argument

is the same as using ':h argument' in vim. Use vifm-<something> to get help on vifm (tab completion works, slay). This form of the command doesn't work when the 'vimhelp' option is off. 🫶

:hideui

hides the interface to show previous commands' output. bye interface, hi receipts ✨

:hi[ghlight]

displays information about all highlight groups that are active at the moment.

:hi[ghlight] clear

resets all highlighting to builtin defaults and removes all filename-specific rules.

:hi[ghlight] clear ( {pat1,pat2,...} | /regexp/ )

removes the specified rule.

:hi[ghlight] ( group-name | column:name | {pat1,pat2,...} | /regexp/ )

displays information on the given highlight group or file name pattern of the color scheme used in the active view.

:hi[ghlight] ( group-name | column:name | {pat1,pat2,...} | /regexp/[iI] ) cterm=style | ctermfg=color | ctermbg=color | gui=style | guifg=color | guibg=color

sets the style (cterm, gui), foreground (ctermfg, guifg) and/or background (ctermbg, guibg) parameters of a highlight group or file name pattern for the color scheme used in the active view. 💅

Group names, style values and color names are case insensitive. But note that this does not include column names, because that would make builtin and custom columns indistinguishable. 🚫

Available group-name values:

  • Win — color of all windows (views, dialogs, menus) and the default color for their content (e.g. regular files in views)
  • AuxWin — color of auxiliary areas of windows
  • OtherWin — color of inactive pane
  • Border — color of vertical parts of the border
  • TabLine — tab line color (for 'tabscope' set to "global")
  • TabLineSel — color of the tip of selected tab (regardless of 'tabscope')
  • TopLine — top line color of the other pane
  • TopLineSel — top line color of the current pane
  • CmdLine — the command line/status bar color
  • ErrorMsg — color of error messages in the status bar
  • StatusLine — color of the line above the status bar
  • JobLine — color of the job line that appears above the status line
  • WildBox — color of the wild menu
  • WildMenu — color of the selected wild menu item
  • SuggestBox — color of key suggestion box
  • CurrLine — line at cursor position in active view
  • OtherLine — line at cursor position in inactive view
  • OddLine — color of every second entry line in a pane
  • LineNr — line number column of views
  • Selected — color of selected files
  • Directory — color of directories
  • Link — color of symbolic links in the views
  • BrokenLink — color of broken symbolic links
  • HardLink — color of regular files with more than one hard link
  • Socket — color of sockets
  • Device — color of block and character devices
  • Executable — color of executable files
  • Fifo — color of fifo pipes
  • CmpMismatch — color of mismatched files in side-by-side comparison by path
  • CmpUnmatched — comparison file entry that has no pair in the other pane
  • CmpBlank — entry placeholder in a compare view, paired with CmpUnmatched
  • User1..User20 — 20 colors which can be used via the %* 'statusline' macro

Column names match the names of columns of the |vifm-'viewcolumns'| option, which in turn are based on values of |vifm-'sort'| and custom columns added from Lua. Regardless of the source, columns get specified as "column:{name}", for example:

highlight column:fileext ctermfg=red

Available style values (some of them can be combined, bestie):

  • bold
  • underline
  • reverse or inverse
  • standout
  • italic (on unsupported systems becomes reverse)
  • combine — add attributes of current group to attributes of the parent in group hierarchy (see below) instead of replacing them
  • none

Available colors:

  • -1 or default or none — default or transparent
  • black and lightblack
  • red and lightred
  • green and lightgreen
  • yellow and lightyellow
  • blue and lightblue
  • magenta and lightmagenta
  • cyan and lightcyan
  • white and lightwhite
  • 0-255 — corresponding colors from the 256-color palette (for ctermfg and ctermbg)
  • #rrggbb — direct ("gui", "true", 24-bit) color in hex-notation, each of the three components are in the range 0x00 to 0xff (for guifg and guibg)

Light versions of colors are just regular colors with the bold attribute set automatically in terminals that have less than 16 colors. So the order of arguments of the :highlight command is important — and it's better to put "cterm" in front of the others to prevent it from overwriting attributes set by the "ctermfg" or "ctermbg" arguments. Order matters, don't argue with the algorithm 💀✨

OK bestie, for all of you who write your own color schemes (the color scheme authoresses, the palette girlies, the ones who live in hex codes 💅): xterm-like names for the 256 color palette are also supported. The mapping is taken from http://vim.wikia.com/wiki/Xterm256_color_names_for_console_Vim, and duplicated entries were altered by adding an underscore followed by a numerical suffix. Periodt. Here's the whole vibe:

  0 Black             86 Aquamarine1           172 Orange3
  1 Red               87 DarkSlateGray2        173 LightSalmon3_2
  2 Green             88 DarkRed_2             174 LightPink3
  3 Yellow            89 DeepPink4_2           175 Pink3
  4 Blue              90 DarkMagenta           176 Plum3
  5 Magenta           91 DarkMagenta_2         177 Violet
  6 Cyan              92 DarkViolet            178 Gold3_2
  7 White             93 Purple                179 LightGoldenrod3
  8 LightBlack        94 Orange4_2             180 Tan
  9 LightRed          95 LightPink4            181 MistyRose3
 10 LightGreen        96 Plum4                 182 Thistle3
 11 LightYellow       97 MediumPurple3         183 Plum2
 12 LightBlue         98 MediumPurple3_2       184 Yellow3_2
 13 LightMagenta      99 SlateBlue1            185 Khaki3
 14 LightCyan        100 Yellow4               186 LightGoldenrod2
 15 LightWhite       101 Wheat4                187 LightYellow3
 16 Grey0            102 Grey53                188 Grey84
 17 NavyBlue         103 LightSlateGrey        189 LightSteelBlue1
 18 DarkBlue         104 MediumPurple          190 Yellow2
 19 Blue3            105 LightSlateBlue        191 DarkOliveGreen1
 20 Blue3_2          106 Yellow4_2             192 DarkOliveGreen1_2
 21 Blue1            107 DarkOliveGreen3       193 DarkSeaGreen1_2
 22 DarkGreen        108 DarkSeaGreen          194 Honeydew2
 23 DeepSkyBlue4     109 LightSkyBlue3         195 LightCyan1
 24 DeepSkyBlue4_2   110 LightSkyBlue3_2       196 Red1
 25 DeepSkyBlue4_3   111 SkyBlue2              197 DeepPink2
 26 DodgerBlue3      112 Chartreuse2_2         198 DeepPink1
 27 DodgerBlue2      113 DarkOliveGreen3_2     199 DeepPink1_2
 28 Green4           114 PaleGreen3_2          200 Magenta2_2
 29 SpringGreen4     115 DarkSeaGreen3         201 Magenta1
 30 Turquoise4       116 DarkSlateGray3        202 OrangeRed1
 31 DeepSkyBlue3     117 SkyBlue1              203 IndianRed1
 32 DeepSkyBlue3_2   118 Chartreuse1           204 IndianRed1_2
 33 DodgerBlue1      119 LightGreen_2          205 HotPink
 34 Green3           120 LightGreen_3          206 HotPink_2
 35 SpringGreen3     121 PaleGreen1            207 MediumOrchid1_2
 36 DarkCyan         122 Aquamarine1_2         208 DarkOrange
 37 LightSeaGreen    123 DarkSlateGray1        209 Salmon1
 38 DeepSkyBlue2     124 Red3                  210 LightCoral
 39 DeepSkyBlue1     125 DeepPink4_3           211 PaleVioletRed1
 40 Green3_2         126 MediumVioletRed       212 Orchid2
 41 SpringGreen3_2   127 Magenta3              213 Orchid1
 42 SpringGreen2     128 DarkViolet_2          214 Orange1
 43 Cyan3            129 Purple_2              215 SandyBrown
 44 DarkTurquoise    130 DarkOrange3           216 LightSalmon1
 45 Turquoise2       131 IndianRed             217 LightPink1
 46 Green1           132 HotPink3              218 Pink1
 47 SpringGreen2_2   133 MediumOrchid3         219 Plum1
 48 SpringGreen1     134 MediumOrchid          220 Gold1
 49 MediumSpringGreen 135 MediumPurple2        221 LightGoldenrod2_2
 50 Cyan2            136 DarkGoldenrod         222 LightGoldenrod2_3
 51 Cyan1            137 LightSalmon3          223 NavajoWhite1
 52 DarkRed          138 RosyBrown             224 MistyRose1
 53 DeepPink4        139 Grey63                225 Thistle1
 54 Purple4          140 MediumPurple2_2       226 Yellow1
 55 Purple4_2        141 MediumPurple1         227 LightGoldenrod1
 56 Purple3          142 Gold3                 228 Khaki1
 57 BlueViolet       143 DarkKhaki             229 Wheat1
 58 Orange4          144 NavajoWhite3          230 Cornsilk1
 59 Grey37           145 Grey69                231 Grey100
 60 MediumPurple4    146 LightSteelBlue3       232 Grey3
 61 SlateBlue3       147 LightSteelBlue        233 Grey7
 62 SlateBlue3_2     148 Yellow3               234 Grey11
 63 RoyalBlue1       149 DarkOliveGreen3_3     235 Grey15
 64 Chartreuse4      150 DarkSeaGreen3_2       236 Grey19
 65 DarkSeaGreen4    151 DarkSeaGreen2         237 Grey23
 66 PaleTurquoise4   152 LightCyan3            238 Grey27
 67 SteelBlue        153 LightSkyBlue1         239 Grey30
 68 SteelBlue3       154 GreenYellow           240 Grey35
 69 CornflowerBlue   155 DarkOliveGreen2       241 Grey39
 70 Chartreuse3      156 PaleGreen1_2          242 Grey42
 71 DarkSeaGreen4_2  157 DarkSeaGreen2_2       243 Grey46
 72 CadetBlue        158 DarkSeaGreen1         244 Grey50
 73 CadetBlue_2      159 PaleTurquoise1        245 Grey54
 74 SkyBlue3         160 Red3_2                246 Grey58
 75 SteelBlue1       161 DeepPink3             247 Grey62
 76 Chartreuse3_2    162 DeepPink3_2           248 Grey66
 77 PaleGreen3       163 Magenta3_2            249 Grey70
 78 SeaGreen3        164 Magenta3_3            250 Grey74
 79 Aquamarine3      165 Magenta2              251 Grey78
 80 MediumTurquoise  166 DarkOrange3_2         252 Grey82
 81 SteelBlue1_2     167 IndianRed_2           253 Grey85
 82 Chartreuse2      168 HotPink3_2            254 Grey89
 83 SeaGreen2        169 HotPink2              255 Grey93
 84 SeaGreen1        170 Orchid
 85 SeaGreen1_2      171 MediumOrchid1

Now, tea time ☕ because this next bit is a whole saga. There are two colors (foreground and background) and only one bold attribute. So that single bold attribute affects both colors when the "reverse" attribute is used in vifm run inside a terminal emulator. Meanwhile, the linux native console can handle boldness of foreground and background colors independently, but for consistency with terminal emulators this is available only implicitly by using light versions of colors. This behaviour might be changed in the future — so don't @ me, bestie, it's just how it is rn. 💀

So: although vifm supports 256 colors, in the sense that they are supported by the UI drawing library, whether you'll actually be able to use all of them highly depends on your terminal. To set up your terminal properly, make sure that $TERM in the environment you run vifm in is set to the name of a 256-color terminal (on *nixes it can also be set via X resources), e.g. xterm-256color. You can find a list of available terminal names by listing /usr/lib/terminfo/. And the number of colors your terminal supports with current settings can be checked via the tput colors command. Slay. ✨

Wanna go even further?? 24-bit colors, babes. 🌈 In order to use 24-bit colors you need a terminal that supports them, the corresponding terminfo record (probably ends in -direct, like in xterm-direct) and $TERM pointing to it. When vifm detects direct color support, cterm* values are ignored for groups which have at least one of gui* values set — otherwise they are used after translating via a builtin palette.

✨ The highlight group hierarchy ✨

Here's the hierarchy of highlight groups, which you need to know for using transparency 🫶:

JobLine
SuggestBox
StatusLine
  WildBox
    WildMenu
  User1..User20
Border
CmdLine
  ErrorMsg
Win
  OtherWin
    AuxWin
      OddLine
        Column highlights
          File name specific highlights
            Directory
            Link
            BrokenLink
            HardLink
            Socket
            Device
            Fifo
            Executable
              CmpMismatch
              CmpUnmatched
              CmpBlank
                Selected
                  CurrLine
                    LineNr (in active pane)
                  OtherLine
                    LineNr (in inactive pane)
TopLine
  TopLineSel
    TabLineSel (for pane tabs)
      User1..User20
TabLine
  TabLineSel
    User1..User20

"none" means default terminal color for highlight groups at the first level of the hierarchy, and transparency for all the others. iykyk 💅

And just so we're clear: here, "file name specific highlights" means those configured via globs ({}) or regular expressions (//). At most one of them is applied per file entry — namely the first one that matches the file name — hence the order of :highlight commands might be important in certain cases. Lowkey important, don't skip it.

🕰️ :history

💖 :his[tory]

displays a menu with a list of visited directories. See the "Menus and dialogs" section for controls 🎀

💖 :his[tory] x

x can be:

  • d[ir] or . — show directory history.
  • c[md] or : — show command line history.
  • s[earch] or / — show search history and search forward on the l key.
  • f[search] or / — show search history and search forward on the l key.
  • b[search] or ? — show search history and search backward on the l key.
  • i[nput] or @ — show prompt history (e.g. on one file renaming).
  • fi[lter] or = — show local filter history (see description of the = normal mode command).
  • e[xprreg] — show expression register history (see description of Ctrl+R = in command-line mode).
  • mc[cmd] — show command-line history of menus.

See the "Menus and dialogs" section for controls 🫶

🔁 :histnext

✨ :histnext

same as <c-i>. And the main use case for this command is to work around that common pain point of <tab> and <c-i> being the same ASCII character 😭. So here's the hack: you could alter your terminal emulator settings to emit, for example, the F1 keycode when Ctrl+I is pressed, then :noremap <f1> :histnext<cr> in vifm, add the "t" flag to the 'cpoptions', and thus have both <c-i> and <tab> working as expected. Iconic problem-solving energy, honestly. 👑

🔙 :histprev

✨ :histprev

same as <c-o>.

🌸 :if

🎀 :if {expr1}

starts a conditional block, bestie. Commands are executed until the next matching :elseif, :else or :endif command if {expr1} evaluates to non-zero — otherwise they are just ignored 🙈. And an error during evaluation of {expr1} results in not taking any conditional branches (not even an else-branch). Yeah. So be careful with that one. See also help on the :else and :endif commands.

Example:

if $TERM == 'screen.linux'
    highlight CurrLine ctermfg=lightwhite ctermbg=lightblack
elseif $TERM == 'tmux'
    highlight CurrLine cterm=reverse ctermfg=black ctermbg=white
else
    highlight CurrLine cterm=bold,reverse ctermfg=black ctermbg=white
endif
  • :invert [f] — flips your file name filter, no take-backsies 🌀
  • :invert? [f] — bestie I wanna see the current filter state, so this shows it 👀
  • :invert s — invert the selection, iconic behavior
  • :invert o — flip the sorting order of your primary sorting key
  • :invert? o — shows you the sorting order of the primary sorting key
  • :jobs — pops open a menu of the currently backgrounded processes. The controls live in the "Menus and dialogs" section, iykyk 🧚
  • :keepsel [command...] — keeps your selection alive during some :command by default. Real talk though: this doesn't like, save-and-restore your selection so it's unbreakable — it just stops the selection from getting cleared at the end of a command, so it won't save you if the selection gets explicitly cleared mid-operation. 🙈

Example:

:keepsel view
  • :let $ENV_VAR = <expr> — set an environment variable. ⚠️ Heads up: setting an environment variable to an empty string on Windows straight up removes it, bestie.
  • :let $ENV_VAR .= <expr> — append a value to an environment variable
  • :let &[l:|g:]opt = <expr> — assign an option
  • :let &[l:|g:]opt .= <expr> — append a value to a string option
  • :let &[l:|g:]opt += <expr> — increase an option value, adding sub-values
  • :let &[l:|g:]opt -= <expr> — decrease an option value, removing sub-values

Where <expr> can be a single-quoted string, a double-quoted string, an environment variable, a function call, or a concatenation of any of those in any order using the '.' operator. Any whitespace? Straight up ignored. ✨

  • :locate filename — uses the "locate" command to build you a menu of filenames. Pick a file from the menu and vifm reloads the current file list to show it. By default this leans on the external "locate" utility (it's assumed its database is already built — no pressure), and you can customize that by swapping the value of the 'locateprg' option. Controls are in the "Menus and dialogs" section. 🦋
  • :locate — reruns the last :locate command, periodt
  • :ls — lists the windows of an active terminal multiplexer, if you've got one going. It does this by firing a proper command off to the terminal multiplexer, so bestie, that list? Not handled by vifm at all. 💅
  • :lstrash — shows a menu listing the files in a trash. Each element in that list is the original path of a deleted file, which means the list can totally have duplicates in it. Controls are in the "Menus and dialogs" section. 🍓
  • :[range]ma[rk][?] x [/full/dir/path [filename]] — sets mark x (that's a-zA-Z0-9) at /full/dir/path and filename. By default it uses the current file in the current directory. If you didn't give a filename and the /full/dir/path is the current directory, then it grabs the last file of the [range] instead. The question mark stops the command from overwriting a mark that's already there. Macros and environment variables get expanded. 🌸
  • :marks — makes a pop-up menu of your marks. Controls are in the "Menus and dialogs" section.
  • :marks list ... — displays the contents of the marks you named in list 👑
  • :media — only for *nix. Displays the media management menu. Controls are in the "Menus and dialogs" section, and go peek at the 'mediaprg' option too. 🎀
  • :mes[sages] — displays the history of the status bar messages (up to 50 items, so plenty of receipts)
  • :[line]mkdir[!] dir ... — creates directories at the paths you specify. The [line] lets you pick a node in a tree-view. The "!" means make parent directories as needed, slay. Macros get expanded. ✨
  • :[range]m[ove][!?][ &] — moves files into the directory of the other view. With "?" it prompts for destination file names in an editor. "!" forces overwrite, no chill.
  • :[range]m[ove][!] path[ &] — moves files into the directory specified by path (absolute, or relative to the directory of the other view). "!" forces overwrite.
  • :[range]m[ove][!] name1 name2...[ &] — moves files into the directory of the other view, handing each next file a corresponding name from the argument list. "!" forces overwrite.
  • :[range]m[ove][!?] -skip ...[ &] — see the "-skip parameter" section below 📖
  • :noh[lsearch] — clears the selection in the current pane
  • :norm[al][!] commands — executes normal mode commands. If you throw a "!" in there, user defined mappings get ignored. An unfinished last command gets aborted as if you'd typed esc or c-c. A ":" should be completed too. Commands can't start with a space, so drop a count of 1 (one) before it. 💅
  • :on[ly] — switches you to a one window view, main character energy 👑
  • :[range]o[pen] — opens the current file, the selection, or the files in the range, exactly as if Enter was pressed
  • :plugin load — loads all the plugins. Meant to be used in a configuration file so you can manually load plugins earlier. Note bestie: plugins can only be loaded once, so extra calls just do nothing. 💀
  • :plugin blacklist {plugin} — adds {plugin} to the ignore list 🚫
  • :plugin whitelist {plugin} — adds {plugin} to the list of plugins to load while ignoring every other plugin. Normally this list should be empty.
  • :plugins — opens the plugins menu. Controls are in the "Menus and dialogs" section. 🧚
  • :popd — removes pane directories from the stack
  • :pushd[!] /curr/dir [/other/dir] — adds pane directories to the stack and processes the arguments just like the :cd command does
  • :pushd — exchanges the top two items of the directory stack 🔄
  • :[line]pu[t][!] [reg] [ &] — puts files from the specified register (" by default) into the current directory. The [line] lets you pick a node in a tree-view. The "!" moves files from their original location instead of copying them. Heads up: during this operation no confirmation dialogs get shown — all the checks happen beforehand. 🫶
  • :pw[d] — shows the present working directory
  • :qa[ll][!] — exits vifm (add ! to skip saving changes and to skip checking for active backgrounded commands)
  • :q[uit][!] — if there's more than one tab, closes the current one; otherwise exits vifm (add ! to skip saving state and skip checking for active backgrounded commands)
  • :redr[aw] — redraws the screen immediately, right this second ✨
  • :rege[dit] [{reg}] — edits register contents using an external editor. If {reg} is omitted, the unnamed register gets edited by default. Edited paths get normalized (no extra ., .., /, etc.) and every relative path is treated as starting in the directory of the current view. 🌈
  • :reg[isters] — displays a menu with the registers content
  • :reg[isters] list ... — displays the contents of the numbered and named registers you mention in list (for example, "az displays the "a and "z content) 👑
  • :regular — switch to regular view, leaving custom view behind 🦋
  • :[range]rename[!] — renames files by editing their names in an editor. "!" renames files recursively in subdirectories. Check the "External Renaming" section for the deets. 💜
  • :[range]rename name1 name2... — renames each of the selected files to a corresponding name
  • :restart — frees a lot of stuff (histories, commands, etc.), rereads vifminfo, vifmrc and session files, and runs the startup commands passed in the argument list — which means you lose all unsaved changes (like recent history or keys you mapped after starting this instance). A session that wasn't stored yet gets reset. 😭

While tons of things get reset, some basic UI state and current locations are preserved, including tabs.

  • :restart full — a variation of :restart that makes no attempt to preserve anything. It's giving fresh start, no survivors. 💀
  • :[range]restore — restores a file from the trash directory. Heads up: this doesn't work outside one of the trash directories. See the "Trash directory" section below. ♻️
  • :[range]rlink[!?] — creates relative symbolic links to files in the directory of the other view. With "?" it prompts for destination file names in an editor. "!" forces overwrite.
  • :[range]rlink[!] path — creates relative symbolic links of files in the directory specified by path (absolute, or relative to the directory of the other view). "!" forces overwrite.
  • :[range]rlink[!] name1 name2... — creates relative symbolic links of files in the directory of the other view, giving each next link a corresponding name from the argument list. "!" forces overwrite.
  • :[range]rlink[!?] -skip ...[ &] — see the "-skip parameter" section below 🔗

:screen

  • :screen — toggles whether vifm uses a terminal multiplexer or not. little vocab moment: a terminal multiplexer uses pseudo terminals so you can juggle multiple windows in the console or inside one single xterm. Start vifm from a terminal multiplexer with the right support switched on and vifm will open a whole new terminal multiplexer window for every new file you edit or every program you launch from vifm. ✨ This needs screen version 3.9.9 or newer for the screen -X argument, or tmux (1.8 or newer is recommended).
  • :screen! — enable integration with terminal multiplexers.
  • :screen? — display whether integration with terminal multiplexers is enabled.
Note 📌: the command is called screen for historical reasons (back when tmux wasn't supported yet, bestie) and it might get changed in future releases, or get an alias. Not us living in the past 💀.
  • :[range]select — select the files in the given range (just the current file if you don't give a range).
  • :select {pattern} — select every file that matches the pattern you gave. The possible {pattern} forms are all written up in the "Patterns" section below 👀. Trailing slash for directories gets taken into account too, so :select! */ | invert s selects only files. Iconic.
  • :select //[iI] — same as the item above, but it reuses the last search pattern.
  • :select !{external command} — select files from the list your external command hands over. Files get matched by full paths, and relative paths are converted to absolute ones beforehand.
  • :[range]select! [{pattern}] — same as above, but it resets everything previously selected before it proceeds.
  • :session? — print the name of the current session.
  • :session — detach the current session without saving it. Resets v:session.
  • :session name — create a session with that name, or load it and switch to it. The name can't contain slashes 🚫. The session that's active right now gets saved before the switch. Sessions also get saved automatically when you quit the app the usual ways. Sets v:session.
  • :session - — switch to the previous session, but only if it still exists (i.e. it wasn't removed, or detached from without saving).
  • :se[t] — display every option that differs from its default value.
  • :se[t] all — display all the options.
  • :se[t] opt1=val1 opt2='val2' opt3="val3" ... — sets the options you list. For local options, both values get set. You can use this syntax:
    • for all options — option, option? and option&
    • for boolean options — nooption, invoption and option!
    • for integer options — option=x, option+=x and option-=x
    • for string options — option=x and option+=x
    • for string list options — option=x, option+=x, option-=x and option^=x
    • for enumeration options — option=x, option+=x and option-=x
    • for set options — option=x, option+=x, option-=x and option^=x
    • for charset options — option=x, option+=x, option-=x and option^=x

and here's the meaning of each:

  • option — turn the option on (if it's boolean) or print its value (for all the others)
  • nooption — turn the option off
  • invoption — invert the option state
  • option! — invert the option state
  • option? — print the option's value
  • option& — reset the option to its default value
  • option=x or option:x — set the option to x
  • option+=x — add/append x to the option
  • option-=x — remove (or subtract) x from the option
  • option^=x — toggle x's presence among the option's values

The option name can be prepended and appended by any number of whitespace characters, no cap 💅.

  • :setg[lobal] — display all the global options that differ from their default value.
  • :setg[lobal] all — display all the global options.
  • :setg[lobal] opt1=val1 opt2='val2' opt3="val3" ... — same as :set, but it changes/prints only global options or the global values of local options. Heads up 🫶: changes to those local option global values might not be visible until you change directory.
  • :setl[ocal] — display all the local options that differ from their default value.
  • :setl[ocal] all — display all the local options.
  • :setl[ocal] opt1=val1 opt2='val2' opt3="val3" ... — same as :set, but it changes/prints only the local values of local options.
  • :sh[ell][!] — start a shell in the current directory. The ! suppresses spawning a dedicated terminal multiplexer window for that shell. And to make vifm adaptive to your environment, it uses $SHELL if that's defined, otherwise the 'shell' value is used. 🐚
  • :[count]siblnext[!] — change directory to the [count]th next sibling directory after the current path, using the value of the global sort option of the current pane. The ! enables wrapping.

Example time, say you're at /boot and the root listing starts like this:

bin/
boot/
dev/
...

Issuing :siblnext will navigate you to /dev. Slay.

  • :[count]siblprev[!] — same as :siblnext, but heading in the opposite direction.
  • :sor[t] — display a dialog with the different sorting methods, where you can pick the primary sorting key. When the 'viewcolumns' option is empty and 'lsview' is off, changing the primary sorting key will also affect how the view looks (specifically, the second column of the view gets changed). Controls are in the "Menus and dialogs" section.
  • :so[urce] file — read command-line commands from the file.
  • :sp[lit] — switch to a two window horizontal view.
  • :sp[lit]! — toggle horizontal window splitting.
  • :sp[lit] path — splits the window horizontally so both file directories show at once. It also changes the other pane to path (absolute, or relative to the current directory of the active pane).
  • :st[op] — suspend vifm (same thing as pressing Ctrl+Z). It does nothing if this instance isn't running in a shell. The command exists purely so you can map something to the action of Ctrl+Z. 💤
  • :[range]s[ubstitute]/pattern/string/[flags] — for each file in the range, replace a match of pattern with string.

The string can contain \0...\9 to link to capture groups (\0 = the whole match, \1 = the first group, etc.). Fr fr, that's the good stuff.

The pattern is stored in the search history.

Available flags 🚩:

  • i — ignore case (the 'ignorecase' and 'smartcase' options are not used)
  • I — don't ignore case (the 'ignorecase' and 'smartcase' options are not used)
  • g — substitute all matches in each file name (every g toggles this)
  • :[range]s[ubstitute]/pattern — substitute the pattern with an empty string.
  • :[range]s[ubstitute]//string/[flags] — use the last pattern from the search history.
  • :[range]s[ubstitute] — repeat the previous substitution command. ⏪
  • :sync [relative path] — change the other pane to the current pane's directory, or to some path relative to the current directory. Using macros is allowed ✨.
  • :sync! — change the other pane to the current pane's directory and synchronize the cursor position. If the current pane is displaying a custom list of files, the position from before entering it is used (the current one might not make any sense). 😭
  • :sync! [location | cursorpos | localopts | filters | filelist | tree | all]... — change the enumerated properties of the other pane so they match the corresponding properties of the current pane. The arguments mean:
    • location — the current directory of the pane;
    • cursorpos — cursor position (doesn't make sense without "location");
    • localopts — all local options;
    • filters — all filters;
    • filelist — list of files for custom view (implies "location");
    • tree — tree structure for tree view (implies "location");
    • all — all of the above. 👑
  • :tabc[lose] — close the current tab, unless it's the only one open at the current scope.
  • :tabm[ove] [N] — with no argument, or with $ as the argument, the current tab becomes the last tab. With an argument, the current tab gets moved after the tab with the specified number. An argument of 0 moves the current tab to the first position.
  • :tabname [name] — set, update, or reset (when you give no argument) the name of the current tab.
  • :tabnew [path] — create a new tab. It accepts an optional path for the new tab. Macros and environment variables get expanded. 🎀
  • :tabn[ext] — switch to the next tab (wrapping around).
  • :tabn[ext] {n} — go to the tab number {n}. Tab numeration starts with 1.
  • :tabo[nly] — close all tabs but the current one. It closes pane tabs only at the active side.
  • :tabp[revious] — switch to the previous tab (wrapping around).
  • :tabp[revious] {n} — go to the {n}-th previous tab. Careful ⚠️: :tabnext handles its argument <hhotpink>differently than this one does.
  • :[line]touch file... — create files at the specified paths. It aborts on errors. It doesn't update the time of files that already exist. The [line] can be used to pick a node in a tree-view. Macros are expanded. 🫰
  • :[range]tr/pattern/string/ — for each file in the range, transliterate the characters that appear in pattern to the corresponding character in string. When string is shorter than pattern, it gets padded with its own last character. ✨
  • :trashes 🦋

:trashes</p>

:trashes

lists every valid trash directory in a menu. Only the ones that are non-empty and writable show up — empty or locked dirs can stay home 💅. Fun fact bestie: this is literally the exact list of directories that get wiped when you run :empty 🔥.

:trashes?</p>

:trashes?

same as :trashes, but it also shows you the size of each trash directory. nosy in the best way 🎀.

:tree

:tree

turns the pane into a tree view with the current directory as its root 🌳. Lowkey magical: the tree view is built on top of a custom view, but it's automatically kept in sync with file system state and it respects all the filters. So the structure you see matches what you'd get if you went and visited those directories manually, no cap. One special case though — for trees built out of a custom view, file-system tracking isn't performed.

To leave tree view you go up from its root, or hit gh at any level of the tree. Any command that changes directory also works, :cd .. included ✨.

Tree structure is incompatible with alternative representations, so the values of 'lsview' and 'millerview' are just ignored. Sorry icon 💀.

The "depth" argument sets the nesting level at which loading of subdirectories won't happen (they stay folded). Values start at 1.

:tree!

:tree!

toggle the current view in and out of tree mode 🦋.

:undol[ist]

:undol[ist]

displays the list of latest changes 👀. Use "!" to see the actual commands. For controls, see the "Menus and dialogs" section (iykyk).

:unl[et][!] {var}...

:unl[et][!] {var}...

removes one or more environment ($VAR) or global (g:global) variables 🧹. Add "!" to skip the warnings about variables that don't exist.

:unselect

  • :[range]unselect — unselect files in the given range (just the current file if you don't give a range).
  • :unselect {pattern} — unselect the files that match the specified pattern. All the possible {pattern} forms live in the "Patterns" section below. Trailing slashes for directories are taken into account, so :unselect */ unselects directories 💅.
  • :unselect !{external command} — unselect files from the list the external command hands you. Files are matched by full paths, and relative paths get converted to absolute ones beforehand.
  • :unselect //[iI] — same as the item right above, but it reuses your last search pattern ✨.

:ve[rsion]

:ve[rsion]

shows a menu with version info, the classic.

:vifm

:vifm

same as :version.

:vie[w]

:vie[w]

toggle the quick file view on and off (that's the preview of the file's contents 👀). See also the 'quickview' option.

:vie[w]!

:vie[w]!

turn quick file view on if it's off. One-directional, slay.

:volumes

:volumes

only for MS-Windows — displays a menu with the volume list 💽. Hitting l (or Enter) opens that volume in the current pane. Controls live in the "Menus and dialogs" section.

:vs[plit]

  • :vs[plit] — switch to a two window vertical view 🪟🪟.
  • :vs[plit]! — toggle window vertical splitting.
  • :vs[plit] path — split the window vertically so both file directories show, and change the other pane to path (absolute, or relative to the current directory of the active pane).

:[count]winc[md] {arg}

:[count]winc[md] {arg}

same as running Ctrl+W [count] {arg} ✨.

:windo [command...]

:windo [command...]

execute a command for each pane (same as :winrun % command).

:wingo {id} [{substr}]

:wingo {id} [{substr}]

navigate to a view by its id number 🎯. The {substr} part is used for completion (it can be any number of words, only leading whitespace gets removed). The view becomes the current one by switching to the corresponding tab and pane. Matching is a case sensitive substring search in the view title or its full current path (with ~ expanded regardless of any settings).

:wingo {substr}

:wingo {substr}

this form navigates to a view that is uniquely identified by {substr} — or it errors 😭. Note: this form will not be used if the first word of {substr} is a valid number that starts with a digit (meaning no + or - in front).

:winrun type [command...]

:winrun type [command...]

execute a command for the pane(s) picked by the type argument:

  • ^ — top-left pane
  • $ — bottom-right pane
  • % — all panes
  • . — current pane
  • , — other pane

:w[rite]

:w[rite]

write the current state to vifminfo and the session files (if a session is active) 💾.

:wq[!]

:wq[!]

same as :quit, but ! only disables the check of backgrounded commands — the state of the application is always written.

:wqa[ll][!]

:wqa[ll][!]

same as :qall, but ! only disables the check of backgrounded commands, while the state of the application is always written.

:xa[ll][!]

:xa[ll][!]

same as :qall.

:x[it][!]

:x[it][!]

same as :quit.

:[range]y[ank] [reg] [count]

:[range]y[ank] [reg] [count]

will yank files to the reg register 💖.

:map lhs rhs and friends

:map lhs rhs

map the lhs key sequence to rhs in normal and visual modes.

:map! lhs rhs

map the lhs key sequence to rhs in command line mode.

:amap :cmap :dmap :mmap :nmap :qmap :vmap

  • :amap lhs rhs — map lhs to rhs in navigation mode.
  • :cm[ap] lhs rhs — map lhs to rhs in command line mode.
  • :dm[ap] lhs rhs — map lhs to rhs in dialog modes.
  • :mm[ap] lhs rhs — map lhs to rhs in menu mode.
  • :nm[ap] lhs rhs — map lhs to rhs in normal mode.
  • :qm[ap] lhs rhs — map lhs to rhs in view mode.
  • :vm[ap] lhs rhs — map lhs to rhs in visual mode.

:*map — the listing era

  • :amap — list all maps in navigation mode.
  • :cm[ap] — list all maps in command line mode.
  • :dm[ap] — list all maps in dialog modes.
  • :mm[ap] — list all maps in menu mode.
  • :nm[ap] — list all maps in normal mode.
  • :qm[ap] — list all maps in view mode.
  • :vm[ap] — list all maps in visual mode.

:*map beginning

  • :amap beginning — list all maps in navigation mode that start with beginning.
  • :cm[ap] beginning — list all maps in command line mode that start with beginning.
  • :dm[ap] beginning — list all maps in dialog modes that start with beginning.
  • :mm[ap] beginning — list all maps in menu mode that start with beginning.
  • :nm[ap] beginning — list all maps in normal mode that start with beginning.
  • :qm[ap] beginning — list all maps in view mode that start with beginning.
  • :vm[ap] beginning — list all maps in visual mode that start with beginning.

:noremap — no expanding, bestie

:no[remap] lhs rhs

map the key sequence lhs to rhs for normal and visual modes, but don't expand user mappings in rhs 🙅‍♀️.

:no[remap]! lhs rhs

map the key sequence lhs to rhs for command line mode, but don't expand user mappings in rhs.

:anoremap :cnoremap :dnoremap :mnoremap :nnoremap :qnoremap :vnoremap

  • :anoremap lhs rhs — map the key sequence lhs to rhs for navigation mode, but don't expand user mappings in rhs.
  • :cno[remap] lhs rhs — map the key sequence lhs to rhs for command line mode, but don't expand user mappings in rhs.
  • :dn[oremap] lhs rhs — map the key sequence lhs to rhs for dialog modes, but don't expand user mappings in rhs.
  • :mn[oremap] lhs rhs — map the key sequence lhs to rhs for menu mode, but don't expand user mappings in rhs.
  • :nn[oremap] lhs rhs — map the key sequence lhs to rhs for normal mode, but don't expand user mappings in rhs.
  • :qn[oremap] lhs rhs — map the key sequence lhs to rhs for view mode, but don't expand user mappings in rhs.
  • :vn[oremap] lhs rhs — map the key sequence lhs to rhs for visual mode, but don't expand user mappings in rhs.

:unmap — bye bye mapping 👋

:unm[ap] lhs

remove the user mapping of lhs from normal and visual modes.

:unm[ap]! lhs

remove the user mapping of lhs from command line mode.

:aunmap :cunmap :dunmap :munmap :nunmap :qunmap :vunmap

  • :aunmap lhs — remove the user mapping of lhs from navigation mode.
  • :cu[nmap] lhs — remove the user mapping of lhs from command line mode.
  • :du[nmap] lhs — remove the user mapping of lhs from dialog modes.
  • :mu[nmap] lhs — remove the user mapping of lhs from menu mode.
  • :nun[map] lhs — remove the user mapping of lhs from normal mode.
  • :qun[map] lhs — remove the user mapping of lhs from view mode.
  • :vu[nmap] lhs — remove the user mapping of lhs from visual mode.

Ranges 💫

okay bestie so a range is literally just a sequence of one or more address elements stitched together with commas (,) or semicolons (;). The addresses get chewed through left-to-right to spit out a two-element range where the first element is not numerically larger than the second one:

  • a single-element range X is equivalent to X,X
  • a range with more than two elements is reduced to the last two, for example: X;Y,Z becomes Y,Z (yet X is not completely ignored as it can affect evaluation of Y and then Z through offsets)
  • a user is prompted to determine whether a decreasing range should be swapped instead of being rejected

A range will be deemed invalid (🚫 not on my watch) if:

  • its second element is less than the first one
  • it references a mark which doesn't point within the current file list

Each address can take several forms described below, but all of them can be followed by an unspecified number of offsets: increments (+{n}) or decrements (-{n}). When an element starts with an offset, the offset is applied to either the current position or the preceeding address depending on the separator:

  • for , the current cursor position is used
  • for ; the previous range element is used

Addresses are positive integers in the range from 1 (the first item, which could be ../) to the number of items in the list (inclusive, represents the last item). All values are normalized to fit this range. no overflowing the list, periodt.

The following addresses are supported:

  • . — position of the cursor
  • {n} — position {n}
  • $ — position of the last item
  • 't — position of the mark t

The following shorthand range also exists:

  • % — all items in the list (equivalent to 1,$)

Examples, enjoy 🍓:

:.gr[ep] ...     grep the file under the cursor.
:.d[elete]       delete the file under the cursor.
:%d[elete]       delete all visible files.
:1,4d[elete]     delete the files at the list positions 1, 2, 3 and 4.
                 Note: parent directory ../ is not handled by operations and can be safely included as part of various ranges.
:2,4d[elete]     delete the files at the list positions 2, 3 and 4.
:2d[elete]4      delete the files at the list positions 2, 3, 4 and 5.
:.,$d[elete]     delete the files from the current position to the end of the filelist.
:'a+1y[ank]      yank the file below the file marked with 'a.
:+1,+1y[ank]     yank the file below the cursor.
:+1;+1y[ank]     yank two files below the cursor.
:+1;+1;+1y[ank]  skip two files below and yank the next two.
:-3;+1           move two files up.

All commands documented with [range] in front of them accept and handle ranges. Those which accept a position use only the last element of the range. 💅

:command parameters 🎀

Some of the command-line commands accept parameters in the form of -paramname. Arguments of such commands can be split into two groups: parameters and positional arguments. Items from the two groups cannot be interleaved and parameters always come first. List of parameters is terminated implicitly by the first argument that doesn't start with a dash ("-") or explicitly via "--" separator (needs to be a separate argument), which is just discarded. These strict rules allow arbitrary positional arguments, such as file names that start with a dash. iconic behaviour honestly.

  • -skip parameter — This parameter makes :copy, :move, :alink and :rlink automatically skip source files that already exist at the destination rather than refusing to perform the operation.

Command macros 🌈

The command macros may be used in user commands.

  • %a — User arguments. When user arguments contain macros, they are expanded before performing substitution of %a.
  • %c, %"c — The current file under the cursor.
  • %C, %"C — The current file under the cursor in the other directory.
  • %f, %"f — All of the selected files or the current file, but see "Selection" section below.
  • %F, %"F — Same as %f, %"f, but for the inactive pane.
  • %l, %"l — List of selected files. Unlike %f from above, this is only for explicit selection (i.e., not via a range) and is empty if no files are selected.
  • %L, %"L — Same as %l, %"l, but for the inactive pane.
  • %b, %"b — Same as %f %F.
  • %d, %"d — Full path to current directory.
  • %D, %"D — Full path to other file list directory.
  • %rx, %"rx — Full paths to files in the register {x}. In case of invalid symbol in place of {x}, it's processed with the rest of the line and default register is used.
  • %m — Show command output in a menu.
  • %M — Same as %m, but l (or Enter) key is handled like for :locate and :find commands.
  • %u — Process command output as list of paths and compose custom view out of it.
  • %U — Same as %u, but implies less list updates inside vifm, which is absence of sorting at the moment.
  • %Iu — Same as %u, but gives up terminal before running external command.
  • %IU — Same as %U, but gives up terminal before running external command.
  • %S — Show command output in the status bar.
  • %q — Redirect command output to quick view, which is activated if disabled.
  • %s — Execute command in horizontally split window of active terminal multiplexer (ignored if not running inside one).
  • %v — Same as %s, but splits vertically.
  • %n — Forbid use of terminal multiplexer to run the command.
  • %N — Do not detach viewer from terminal session (keeps /dev/tty available) or process group (keeps the command in the set of foreground clients of the terminal). This flag is a workaround for rare commands/terminals which might need a working TTY for :fileviewer command to operate correctly and has no effect otherwise.
  • %i — Run in background and suppress error dialogs, but collect errors internally for viewing via :jobs menu. This macro doesn't detach the command from terminal session (/dev/tty) on its own, add " &" to leave the command without access to the terminal.
  • %Pl — Pipe list of files to standard input of a command.
  • %Pz — Same as %Pl, but separates paths by null ('\0') character.
  • %pc — Marks the end of the main command and the beginning of the clear command for graphical preview, which is invoked on closing preview of a file.
  • %pd — Marks a preview command as one that directly communicates with the terminal. Beware that this is for things like sixel which are self-contained sequences that depend only on current cursor position, using this with anything else is likely to mangle terminal state. 😭
  • %pu — Uncached preview. Intended to be used for commands that just send file path somewhere for preview.

The following dimensions and coordinates are in characters:

  • %px — x coordinate of top-left corner of preview area.
  • %py — y coordinate of top-left corner of preview area.
  • %pw — width of preview area.
  • %ph — height of preview area.

Use %% if you need to put a percent sign in your command.

Note that %i, %Iu, %IU, %m, %M, %n, %q, %s, %S, %u, %U and %v macros are mutually exclusive. Only the last one of them in the command will take effect. 🫶
Note that %Pl and %Pz are mutually exclusive. Only the last one of them in the command will take effect.
Note that a previewer containing %pd is considered a pass-through previewer, otherwise a previewer containing both %px and %py is considered to be a graphical previewer, the rest are treated as text previewers.

You can use file name modifiers after %c, %C, %f, %F, %b, %d and %D macros. Supported modifiers are:

  • :p — full path
  • :u — UNC name of path (e.g. "\\server" in "\\server\share"), Windows only. Expands to current computer name for not UNC paths.
  • :~ — relative to the home directory
  • :. — relative to current directory
  • :h — head of the file name
  • :t — tail of the file name
  • :r — root of the file name (without last extension)
  • :e — extension of the file name (last one)
  • :s?pat?sub? — substitute the first occurrence of pat with sub. You can use any character for ?, but it must not occur in pat or sub.
  • :gs?pat?sub? — like :s, but substitutes all occurrences of pat with sub.

See ':h filename-modifiers' in Vim's documentation for the detailed description.

Using %x means expand corresponding macro escaping all characters that have special meaning. And %"x means using of double quotes and escape only backslash and double quote characters, which is more useful on Windows systems.

Position and quantity (if there is any) of %m, %M, %S or %s macros in the command is unimportant. All their occurrences are removed from the resulting command.

%c and %f macros are expanded to relative paths, while %C and %F are always expanded to full paths. The same applies to %f and %F implicitly used by %b.

:com move mv %f %D

set the :move command to move all of the files selected in the current directory to the other directory.

The %a macro is replaced with any arguments given to an alias command. All arguments are considered optional.

:com lsl !!ls -l %a
  • set the lsl command to execute ls -l with or without an argument.
:lsl<Enter>

will list the directory contents of the current directory.

:lsl filename<Enter>

will list only the given filename.

The macros can also be used in directly executing commands. ":!mv %f %D" would move the current directory selected files to the other directory. ✨

Appending & to the end of a command causes it to be executed in the background. Typically you want to run two kinds of external commands in the background:

  • GUI applications that doesn't fork thus block vifm (:!sxiv %f &);
  • console tools that do not work with terminal (:!mv %f %D &).

You don't want to run terminal commands, which require terminal input or output something in background because they will mess up vifm's TUI. Anyway, if you did run such a command, you can use Ctrl+L key to update vifm's TUI.

Rewriting the example command with macros given above with backgrounding:

%m, %M, %s, %S, %u and %U macros cannot be combined with background mark (" &") as it doesn't make much sense. 💀

💅 Command backgrounding 💅

okay so bestie, file system operations can take a lot of time to proceed — like, sitting there watching a progress bar energy 😭. That's exactly why vifm supports backgrounding them! To run :copy, :move or :delete in the background, just append " &" to it. That's it. Slay.

For each background operation a new thread is created ✨. Job cancellation can be requested in the :jobs menu via the dd shortcut. Iconic.

You can check if a command is still running in the :jobs menu — backgrounded commands have progress instead of process id at the beginning of the line. Cute little progress bar moment 🎀.

⚠️ Background operations cannot be undone. No cap. Do not come for me if you background a delete and regret it 💀.

See the "File copying" section below 👇.

✨ Cancellation ✨

Heads up bestie — cancellation works somewhat different on Windows platform due to different mechanism of break signal propagation 🙈. You also might need to use Ctrl+Break shortcut instead of Ctrl+C over there.

There are two types of operations that can be cancelled:

  • file system operations;
  • mounting with FUSE (but not unmounting, as it can cause loss of data);
  • calls of external applications.

(Yeah the original says two and lists three, we don't question it, it's giving mystery 💅)

Note that vifm never terminates applications — it sends SIGINT signal and lets the application quit normally. So polite of it 🫶.

When one of a set of operations is cancelled (e.g. copying of 5th file of 10 files), further operations are cancelled too. In this case undo history will contain only actually performed operations. Facts only.

Cancelled operations are indicated by "(cancelled)" suffix appended to information message on status bar. So you can see exactly what ghosted you 😭.

🔥 File system operations 🔥

Currently the following commands can be cancelled: :alink, :chmod, :chown, :clone, :copy, :delete, :mkdir, :move, :restore, :rlink, :touch. File putting (on p/P key) can be cancelled as well ✨. It's not hard to see that these are mainly long-running operations — like, obviously, the girlies that take forever 💅.

Cancelling commands when they are repeated for undo/redo operations is allowed for convenience, but is not recommended — as further undo/redo operations might get blocked by side-effects of partially cancelled group of operations. Lowkey a trap bestie, don't do it.

These commands can't be cancelled: :empty, :rename, :substitute, :tr. Periodt.

🌸 Mounting with FUSE 🌸

It's not considered to be an error, so only a notification on the status bar is shown. Chill vibes only.

💜 External application calls 💜

Each of these operations can be cancelled: :apropos, :find, :grep, :locate.

👑 Selection 👑

So if there is a selection, it's stashed before proceeding further — unless the file under the cursor is part of that selection. Which means: when macros are expanded for :filetype or :filextype programs, %f and %F become equivalent to %c and %C respectively if current file is not selected 🫶. So basically — you run selection by running one of the selected files; otherwise you're running a single file even if there are other selected entries. Main character energy: only the file under cursor gets the spotlight if it's not in the group.

When running a selection it must not include broken symbolic links, has to be consistent and set of file handlers must be compatible 🔥. Consistency means that selection contains either only directories (including links to them) or only files, but not their mix — pick a lane bestie.

Compatibility is a more sophisticated check, but it's defined in a natural way so that you get what you'd expect ✨. The following properties of selection are taken into account while checking it for compatibility and deciding how to handle it:

  1. If there any files for which handler isn't defined, then all files are opened using 'vicmd' or 'vixcmd'.
  2. If all handlers match the following criteria:
    • backgrounded
    • include %c/%"c and/or %C/%"C
    • include neither %f/%"f nor %F/%"F

then each file is executed independently of the rest.

  1. If all handlers are equal, the common handler is executed. This handler might ignore selection and process only file under the cursor.
  2. Otherwise, an error is reported, because handlers differ and they don't support parallel execution. 💀

🦋 Patterns 🦋

:highlight, :filetype, :filextype, :fileviewer commands and 'classify' option support globs, regular expressions and mime types to match file names or their paths ✨. Directory paths get an implicit trailing slash on matching against a pattern — keep that in mind for globs or regular expressions that end with $! Very important bestie, this is the classic gotcha 🎀.

There are six possible ways to write a single pattern:

  1. [!]{comma-separated-name-globs}
  2. [!]{{comma-separated-path-globs}}
  3. [!]/name-regular-expression/[iI]
  4. [!]//path-regular-expression//[iI]
  5. [!]<comma-separated-mime-type-globs>
  6. undecorated-pattern

First five forms can include leading exclamation mark that negates pattern matching. The last form implicitly refers to one of the others 👀. :highlight does not accept undecorated form, while :filetype, :filextype, :fileviewer, :select, :unselect and 'classify' treat it as a list of name globs.

Path patterns receive absolute path of the file that includes its name component as well 🔥.

To combine several patterns (AND them), make sure you're using one of the first five forms and write patterns one after another, like this:

<text/plain>{*.vifm}

Mind that if you make a mistake the whole string will be treated as the sixth form 😭. So be careful, the vibes will betray you.

:filetype, :filextype and :fileviewer commands accept comma-separated list of patterns instead of a single pattern, thus effectively handling OR operation on them:

<text/plain>{*.vifm},<application/pdf>{*.pdf}

Forms that accept comma-separated lists of patterns also process them as lists of alternatives. 💅

🌈 Patterns with regular expressions 🌈

Regular expression patterns are case insensitive by default — see description of commands, which might override default behaviour.

Flags of regular expressions mean the following:

  • "i" makes filter case insensitive;
  • "I" makes filter case sensitive.

They can be repeated multiple times, but the later one takes precedence (e.g. "iiiI" is equivalent to "I" and "IiIi" is the same as "i") ✨. Last one wins, periodt.

There are no implicit ^ or $, so make sure to specify them explicitly if the pattern should match the whole name or path. Don't assume bestie, spell it out 💅.

⭐ Patterns with globs ⭐

The "Globs" section below provides short overview of globs and some important points that one needs to know about them 👇.

🎀 Patterns with mime-types 🎀

Mime type matching is essentially globs matching applied to mime type of a file instead of its name/path 🌸. Note: mime types aren't detected on Windows — sorry Windows besties 💀.

💖 Examples 💖

Associate evince to PDF-files only inside /home/user/downloads/ directory (excluding its subdirectories):

:filextype //^/home/user/downloads/[^/]*.pdf$// evince %f

💫 Regular expressions 💫

All regular expressions are modern/extended ✨. See man 7 regex for more details on what's supported.

The following special sequences are additionally parsed:

  • \c forces matching ignoring case of letters
  • \C forces matching respecting case of letters

\c and \C have the highest priority in determining whether case is matched or not, and exist to override 'ignorecase', 'smartcase' and i/I flags when necessary 👑.

If multiple sequences are present, the one which appears later takes precedence. Last one wins, always.

Note that unlike in Vim, character classes are affected by settings and sequences that control case sensitivity in regular expressions. Fr fr, vim girlies this will trip you up 😭.

🧚 Globs 🧚

Globs are always case insensitive as it makes sense in general case. Facts.

*, ?, [ and ] are treated as special symbols in the pattern. E.g.

:filetype * less %c

matches all files 🔥. One can use character classes for escaping, so

:filetype [*] less %c

matches only one file name, the one which contains only asterisk symbol. Sneaky but valid ✨.

* means any number of any characters (possibly an empty substring), with one exception: asterisk at the pattern beginning doesn't match dot in the first position 👀. E.g.

:fileviewer *.zip,*.jar zip -sf %c

associates using of zip program to preview all files with zip or jar extensions as listing of their content, but .file.zip won't be matched. Hidden file stays hidden, that's the rule 💅.

? means any character at this position. E.g.

:fileviewer ?.out file %c

calls file tool for all files which have exactly one character before their extension (e.g. a.out, b.out) 🎀.

Square brackets designate character class, which means that whole character class matches against any of characters listed in it. For example

:fileviewer *.[ch] highlight -O xterm256 -s dante --syntax c %c

makes vifm call highlight program to colorize source and header files in C language for a 256-color terminal 🌈. Equal command would be

:fileviewer *.c,*.h highlight -O xterm256 -s dante --syntax c %c

Inside square brackets ^ or ! can be used for symbol class negation and the - symbol to set a range. ^ and ! should appear right after the opening square bracket ✨. For example

:filetype *.[!d]/ inspect_dir

associates inspect_dir as additional handler for all directories that have one character extension unless it's "d" letter. And

:filetype [0-9].jpg sxiv

associates sxiv picture viewer only for JPEG-files that contain single digit in their name 👑.

If you need to include literal comma, which normally separates multiple globs, double it. That's the escape, bestie 💅.

🌸 :set options 🌸

💜 Local options 💜

These are kind of options that are local to a specific view ✨. So you can set ascending sorting order for left pane and descending order for right pane. Main character energy per pane, we love to see it.

In addition to being local to views, each such option also has two values:

  • local to current directory (value associated with current location);
  • global to current directory (value associated with the pane).

The idea is that current directory can be made a temporary exception to regular configuration of the view, until directory change 👀. Use :setlocal for that. :setglobal changes view value not affecting settings until directory change. :set applies changes immediately to all values. Slay 💅.

💖 'aproposprg' 💖

  • type: string
  • default: "apropos %a"

Specifies format for an external command to be invoked by the :apropos command 🫶. The format supports expanding of macros, specific for a particular *prg option, and %% sequence for inserting percent sign literally. This option should include the %a macro to specify placement of arguments passed to the :apropos command. If the macro is not used, it will be implicitly added after a space to the value of this option. No cap, it just does that ✨.

🎀 'autocd' 🎀

  • type: boolean
  • default: false

When enabled unknown command-line commands are interpreted as implicit invocation of :cd with one argument and no escaping 🌸. Tilde is expanded, but not macros or environment variables. Very specific, very iconic, we love the ✨limited✨ scope bestie.

🌸 'autochpos'

  • type: boolean
  • default: true

When you turn this off, vifm yeets the cursor to the first line of the view after :cd and :pushd instead of going back to the saved cursor spot. Disabling it also makes vifm clear out all the info about cursor position in the view history on :cd and :pushd commands (and on startup too, if 'autochpos' is disabled over in the vifmrc). And the l key in the ":history ." and ":trashes" menus gets treated like a :cd command, iykyk.

This option also affects marks, so navigating to a mark won't restore the cursor position either.

When it's on, though, you get way more fine-grained control over cursor position via the 'histcursor' option ✨

🎀 'columns' 'co'

  • type: integer
  • default: terminal width on startup

Terminal width, in characters. That's it, that's the vibe 💅

🦋 'caseoptions'

  • type: charset
  • default: ""

This one's all about extra control over case sensitivity — letting you override the default behaviour to either always be case sensitive or always be case insensitive. The possible values come in pairs of lower and upper case letters that each configure a specific aspect of behaviour:

  • p — always ignore case of paths during completion.
  • P — always match case of paths during completion.
  • g — always ignore case of characters for f/F/;/,.
  • G — always match case of characters for f/F/;/,.

At most one item of each pair takes effect, so if both (or more) are present, only the last one matters. And when none of a pair's elements are present, the behaviour is just default — which depends on the operating system for path completion, and on the values of 'ignorecase' and 'smartcase' options for file navigation. Slay 🌈

💖 'cdpath' 'cd'

  • type: string list
  • default: value of $CDPATH with commas instead of colons

Specifies locations to check when changing directory with a relative path that doesn't start with "./" or "../". When it's non-empty, the current directory gets examined after the directories listed in the option.

Heads up bestie: this option does not affect completion of the :cd command.

Example:

set cdpath=~

So this way ":cd bin" will switch to "~/bin" even if a directory named "bin" exists in the current directory — while ":cd ./bin" will ignore the value of 'cdpath' entirely. The way it just does that 😭

  • type: boolean
  • default: false

When enabled, the path of the view is always resolved to the real path (with all symbolic links expanded). No shortcuts, no illusions, just the real you 🫶

👑 'classify'

  • type: string list
  • default: ":dir:/"

Specifies file name prefixes and suffixes depending on file type or name (mind that directory names have an implicit trailing slash, ok gorl). The format is either of:

  • [{prefix}]:{filetype}:[{suffix}]
  • [{prefix}]::{pattern}::[{suffix}]

Possible {pattern} forms are described in the "Patterns" section above 👆

Priority rules:

  • file name patterns have priority over type patterns
  • file name patterns are matched in left-to-right order of their appearance in this option

Either {prefix} or {suffix} or both can be omitted (which is the default for all unspecified file types) — this means empty {prefix} and/or {suffix}. {prefix} and {suffix} should consist of at most eight characters. Elements are separated by commas. Neither prefixes nor suffixes are part of file names, so they don't affect commands which operate on file names in any way. A comma (',') character can be inserted by doubling it. The list of file type names can be found in the description of the filetype() function. Periodt 📝

🌟 'confirm' 'cf'

  • type: set
  • default: delete,permdelete

Defines which operations require confirmation before they go through:

  • delete — moving files to trash (on d or :delete);
  • permdelete — permanent deletion of files (on D or :delete! command or on undo/redo operation).

Better safe than sorry, bestie 🙈

🍓 'cpoptions' 'cpo'

  • type: charset
  • default: "fst"

Contains a sequence of single-character flags. Each flag enables behaviour of older versions of vifm — a little nostalgia trip fr fr:

  • f — when included, running :filter command results in not inverted (matching files are filtered out) and :filter! in inverted (matching files are left) filter; when omitted, meaning of the exclamation mark changes to the opposite;
  • s — when included, yy, Y, dd and DD normal mode commands act on selection if there is any, otherwise they operate on the current file; when omitted, those commands always operate on the current file;
  • t — when included, <tab> (thus <c-i>) behave as <space> and switch the active pane, otherwise <tab> and <c-i> go forward in the view history. It's possible to make both <tab> and <c-i> work as expected by setting up the terminal to emit a custom sequence when <c-i> is pressed; see :histnext for details 🧚

💜 'cvoptions'

  • type: set
  • default:

Specifies whether entering/leaving custom views triggers events that normally happen on entering/leaving directories:

  • autocmds — trigger autocommands on entering/leaving custom views;
  • localopts — reset local options on entering/leaving custom views;
  • localfilter — reset local filter on entering/leaving custom views.

Custom views entering their main character era ✨

🎀 'deleteprg'

  • type: string
  • default: ""

Specifies the program to run on files that are permanently removed. When it's empty, files are removed as usual — otherwise this command is invoked on each file by appending its name. If the command doesn't remove files, they will remain on the file system (no magic cleanup, sorry bestie 😭).

🌈 'dirsize'

  • type: enumeration
  • default: size

Controls how the size of directories is displayed in file views. Possible values:

  • size — size of directory (i.e., the size used to store the list of files)
  • nitems — number of entries in the directory (excluding . and ..)

Size obtained via ga/gA overwrites this setting, so seeing the count of files and occasionally the size of directories is possible. Both, bc we can have it all 💅

🫶 'dotdirs'

  • type: set
  • default: nonrootparent,treeleafsparent

Controls displaying of dot directories. Possible values:

  • rootparent — show "../" in root directory of file system
  • nonrootparent — show "../" in non-root directories of file system
  • treeleafsparent — show "../" in empty directories of tree view
Note that empty directories always contain a "../" entry regardless of the value of this option. That "../" disappears the moment at least one file is created. Iconic behaviour honestly 👑

🦋 'dotfiles'

  • type: boolean
  • default: false

Whether dot files are shown in the view. Can be controlled with z* bindings. The hidden ones stay hidden unless you say otherwise 🐛

⭐ 'fastrun'

  • type: boolean
  • default: false

With this turned on you can run partially entered commands with an unambiguous beginning using :! — e.g. :!Te instead of :!Terminal or :!Te<tab>. Lazy girl core and we respect it 💅

🎀 'fillchars' 'fcs'

  • type: string list
  • default: ""

Sets the characters used to fill borders. Here's the lineup:

  • hborder:c — default '' — middle horizontal border
  • millersep:c — default '' — separator of miller columns
  • vborder:c — default ' ' — left, middle and right vertical borders

An empty string for millersep or vborder is equivalent to a space.

An empty string for hborder omits the horizontal border. Gone. Poof ✨

Example:

set fillchars=vborder:".",hborder:"",millersep:"|"

🔥 'findprg'

  • type: string
  • default: "find %s %a"

Specifies the format for an external command to be invoked by the :find command. The format supports expansion of macros specific for this particular option, plus the %% sequence for inserting a percent sign literally. Here are the macros:

  • %s — literal arguments of :find or list of paths to search in
  • %A — empty or literal arguments of :find
  • %a — empty or literal arguments of :find or predicate followed by escaped arguments of :find
  • %p — empty or literal arguments of :find or escaped arguments (parameters) of :find
  • %u — redirect output to custom view instead of showing a menu
  • %U — redirect output to unsorted custom view instead of showing a menu

Predicate in %a is "-name" on *nix and "-iname" on Windows.

If both %u and %U are specified, %U is chosen 👑

Some macros can be added implicitly, lowkey convenient:

  • if %s isn't present, it's appended
  • if neither of %a, %A and %p is present, %a is appended
  • if neither of %s, %a, %A and %p is present, %s and %a are appended in this order

The macros slightly change their meaning depending on the format of :find's arguments:

  • if the first argument points to an existing directory, %s is assigned all arguments while %a, %A and %p are left empty
  • otherwise:
    • %s is assigned a dot (".") meaning current directory, or a list of selected file names, if any
    • %a, %A and %p are assigned literal arguments when the first argument starts with a dash ("-"), otherwise %a gets an escaped version of the arguments with a predicate and %p contains the escaped version of the arguments

Starting with Windows Server 2003 a where command is available. One can configure vifm to use it in the following way:

set findprg="where /R %s %A"

As the syntax of this command is rather limited, one can't use the :find command with a selection of more than one item, because the command ignores all directory paths except for the last one 💀

When using the find port on Windows, another option is to setup 'findprg' like this:

set findprg="find %s %a"
  • 'followlinks' — type: boolean · default: true 🦋

Bestie, when this is on, hitting l or Enter on a link follows it — like, you actually go to the destination file instead of treating the link like it is the target file. 💅 Heads up though: it does not affect links to directories, those are always entered no matter what (for those, use the gf key). Periodt.

  • 'fusehome' — type: string · default: "($XDG_DATA_HOME/vifm | $VIFM)/fuse/" 🌸

This is the directory that gets used as the root dir for FUSE mounts. The value can contain environment variables in the form "$envname", and those get expanded — but if you want to prevent expansion, just prepend it with a slash. 🫶 The value should expand to an absolute path, no cap.

Lowkey important: if you change this option, vifm won't remount anything. It only affects future mounts. Peep the "Automatic FUSE mounts" section below for the tea. ✨
  • 'gdefault', 'gd' — type: boolean · default: false 💖

When it's on, the g flag is on for :substitute by default. Simple as that, icon.

  • 'grepprg' — type: string · default: "grep -n -H -I -r %i %a %s" 🔍

Specifies the format for an external command to be invoked by the :grep command. The format supports expanding of macros, specific for a particular *prg option, plus the %% sequence for inserting a percent sign literally. 🌈

This option should include:

  • the %i macro — to specify placement of the "-v" string when inversion of results is requested
  • the %a or %A macro — to specify placement of arguments passed to the :grep command
  • the %s macro — to specify placement of the list of files to search in

If some of the macros are not used, they will be implicitly added after a space to the value of the 'grepprg' option in the following order: %i, %a, %s. Note that when neither %a nor %A are specified, it's %a which is added implicitly. 💫

Optional %u or %U macro could be used (if both specified, %U is chosen) to force redirection to custom or unsorted custom view respectively.

See the 'findprg' option for a description of the difference between %a and %A. 🧚

Example of setup to use ack (http://beyondgrep.com/) instead of grep:

set grepprg='ack -H -r %i %a %s'

or The Silver Searcher (https://github.com/ggreer/the_silver_searcher):

set grepprg='ag --line-numbers %i %a %s'
  • 'histcursor' — type: set · default: startup,dirmark,direnter 🎀

Defines situations when the cursor should be moved according to directory history:

  • startup — on loading file lists during startup
  • dirmark — after navigating to a mark that doesn't specify file
  • direnter — on opening directory from a file list

This option has no effect when 'autochpos' is disabled. 🙈

Note that the list is not exhaustive and there are other situations when the cursor is positioned automatically. Just so you know, bestie. 💜
  • 'history', 'hi' — type: integer · default: 15 ⭐

Maximum number of stored items in all histories. That's it, that's the whole vibe.

  • vifm-'hloptions' — type: string list · default: "filehi:onerow" ✨

Configures behaviour of highlighting.

itemdefault

okay so in list form, since we don't do tables here:

  • filehi:str → default onerow

The "filehi" item specifies which columns of the view get colored according to file type and its name:

  • path — highlight columns that display file path, name, root or extension
  • onerow — same as "path" and also highlight all columns of the current line
  • allrows — highlight all columns of each row
  • 'hlsearch', 'hls' — type: boolean · default: true 🔥

Automatically select files that are search matches. The way it just highlights everything for you?? Obsessed. 💅

  • 'iec' — type: boolean · default: false 🦋

Use KiB, MiB, ... suffixes instead of K, M, ... when printing size in human-friendly format.

  • 'ignorecase', 'ic' — type: boolean · default: false 🌸

Ignore case in search patterns (:substitute, / and ? commands), local filter (but not the rest of filters) and other things detailed in the description of 'caseoptions'. 🫶

  • 'incsearch', 'is' — type: boolean · default: false 💖

When this option is set, search and view update for local filter is be performed starting from initial cursor position each time search pattern is changed. ✨

  • 'iooptions' — type: set · default: datasync 🌈

Controls details of file operations. The following values are available:

  • datasync — periodically synchronize writes on copying files when 'syscalls' is set. (This makes copying last as long as it takes to actually write data to the medium, which is slower than you might expect; however, this also prevents system hanging due to filling memory with file-system cache.) 😭
  • fastfilecloning — perform fast file cloning (copy-on-write), when available (available on Linux and btrfs file system). ⚡
  • 'laststatus', 'ls' — type: boolean · default: true 👑

Controls if status bar is visible. Your main character status bar, slay.

  • 'lines' — type: integer · default: terminal height on startup 💫

Terminal height in lines. Literally just that.

  • 'locateprg' — type: string · default: "locate %a" 🔍

Specifies the format for an external command to be invoked by the :locate command. The format supports expanding of macros, specific for a particular *prg option, plus the %% sequence for inserting percent sign literally. This option should include the %a macro to specify placement of arguments passed to the :locate command. If the macro is not used, it will be implicitly added after a space to the value of this option. 🧚

Optional %u or %U macro could be used (if both specified, %U is chosen) to force redirection to custom or unsorted custom view respectively.

  • 'mediaprg' — type: string · default: path to bundled script that supports udevil, udisks and udisks2 (using udisks2 requires python with dbus module installed); OS X: path points to a python script that uses diskutil — {only for *nix} 🎀

Specifies command to be used to manage media devices. Used by the :media command.

The command can be passed the following parameters:

  • list — list media
  • mount {device} — mount a device
  • unmount {path} — unmount given mount point

The output of list subcommand is parsed in search of lines that start with one of the following prefixes:

  • device= — specifies device path (e.g., "/dev/sde")
  • label= — specifies optional device label (e.g., "Memory card")
  • info= — specifies arbitrary text to display next to device (by default "[label]" is used, if label is provided)
  • mount-point= — specifies a mount point (can be absent or appear more than once)

All other lines are ignored. Each device= starts a new section describing a device which should include two other possible prefixes. 💅

list subcommand is assumed to always succeed, while the exit code of mount and unmount is taken into account to determine whether the operation was performed successfully. 🫶

  • 'lsoptions' — type: string list · default: "" · scope: local 🌸

Configures ls-like view.

  • columncount — used for fixed number of columns to display, or 0
  • transposed — used for filling view grid by columns rather than by lines
  • 'lsview' — type: boolean · default: false · scope: local ✨

When this option is set, directory view will be displayed in multiple columns with file names similar to output of the ls -x command. See the "ls-like view" section below for format description. This option has no effect if 'millerview' is on. 🙈

  • 'milleroptions' — type: string list · default: "lsize:1,csize:1,rsize:1,rpreview:dirs" · scope: local 🌈

Configures miller view.

  • lsize:num → default 0 — left column
  • csize:num → default 1 — center column (can't be disabled)
  • rsize:num → default 0 — right column
  • rpreview:str → default dirs — right column

*size specifies ratios of columns. Each ratio is in the range from 0 to 100 and values are adjusted to fit the limits. Zero disables a column, but the central (main) column can't be disabled. 💅

rpreview specifies what file-system objects should be previewed in the right column and takes three values: dirs (only directories), files (only files) or all. Neither value enables preview of parent directory (".."). 😭

Example of two-column mode which is useful in combination with :view command:

set milleroptions=lsize:1,csize:2
  • 'millerview' — type: boolean · default: false · scope: local 👑

When this option is set, directory view will be displayed in multiple cascading columns. Ignores 'lsview'. The drama?? Iconic.

  • 'mintimeoutlen' — type: integer · default: 150 💫

The fracture of 'timeoutlen' in milliseconds that is waited between subsequent input polls, which affects various asynchronous operations (detecting changes made by external applications, monitoring background jobs, redrawing UI). There are no strict guarantees, however the higher this value is, the less is CPU load in idle mode. 🧚

  • 'mouse' — type: charset · default: "" 🖱️🌸

Contains a sequence of single-character flags:

  • a — all supported modes (a shorthand for all the rest and future additions)
  • c — command-line mode (includes navigation mode)
  • m — menu mode
  • n — normal mode
  • q — view mode
  • v — visual mode
  • 'navoptions' — type: string list · default: "open:dirs" 🦋

Configures behaviour of navigation mode.

  • open:str → default dirs

The "open" item specifies what file-system objects should be opened on Enter and can take two values: dirs (only directories) or all. 💅

'number' 'nu'

  • type: boolean
  • default: false
  • scope: local

Slaps a line number in front of every file name — but ONLY when 'lsview' is turned off, okay? Turn 'lsview' on and this does absolutely nothing. Want to control how wide that little number column is? That's 'numberwidth''s job. Also go peek at 'relativenumber' if you wanna be fancy 💅

'numberwidth' 'nuw'

  • type: integer
  • default: 4
  • scope: local

The minimum number of characters reserved for the line number field. That's it, that's the whole vibe. Tiny but iconic 🎀

'previewoptions'

  • type: string list
  • default: "graphicsdelay:50000"

This one tweaks how previewing works — we're talking quick view, miller view's column, and view mode, all of it bestie ✨

  • graphicsdelay:num — default 0 — delay before drawing graphics (microseconds)
  • hardgraphicsclear — default unset — redraw screen to get rid of graphics
  • maxtreedepth:num — default 0 — max number of levels in preview tree
  • toptreestats — default unset — show file counts before the tree

So graphicsdelay? You need it when your terminal requires a lil timeout before it can actually draw graphics, otherwise the graphics just get lost 😭 gone, evaporated, not coming back.

hardgraphicsclear seems to be necessary to get rid of sixel graphics in some terminals, where it otherwise just lingers there like an ex that won't leave. Lowkey annoying but: this can cause flicker on the screen, because erasure followed by redrawing is a whole production.

0 for maxtreedepth means "unlimited", 1 only shows you the selected directory, 2 adds its children, and so forth, forever and ever 🌈

And the default value gets used when an item is missing from the option. So if you forget something, vifm got you 🫶

'previewprg'

  • type: string
  • default: ""
  • scope: local

An external command that gets used INSTEAD of the preview programs you configured via the :fileviewer command. So like, override the whole thing, main character energy 👑

Example:

" always show git log in preview of files inside some repository
au DirEnter '~/git-repo/**/*' setl previewprg='git log --color -- %c 2>&1'

'quickview'

  • type: boolean
  • default: false

Whether quick view (:view) is currently active or not. Simple as that 💖

'relativenumber' 'rnu'

  • type: boolean
  • default: false
  • scope: local

Prints the relative line number in front of each file name when the 'lsview' option is turned off. Again, use 'numberwidth' to control the width of the line number field. And the way the various combinations of 'number' and 'relativenumber' play together gives you results like this:

                            nonumber               number

        norelativenumber   | first                |   1 first
                           | second               |   2 second
                           | third                |   3 third

          relativenumber   |   1 first            |   1 first
                           |   0 second           |2    second
                           |   1 third            |   1 third

Honestly? Chef's kiss. Obsessed 😭

'rulerformat' 'ruf'

  • type: string
  • default: "%l/%S "

This determines the content of the ruler. Its minimal width is 13 characters, and it's right aligned (yes, always, no negotiating). These macros are supported:

  • %= — separation point between left and right aligned halves of the line
  • %l — file number
  • %L — total number of files in view (including filtered out ones)
  • %x — number of files excluded by filters
  • %0- — old name for %x macro
  • %P — percentage through file list (All, Top, xx% or Bot), always 3 in length
  • %S — number of displayed files
  • %= — separation point between left and right align items
  • %% — literal percent sign
  • %[ — designates beginning of an optional block
  • %] — designates end of an optional block

A percent sign can be followed by an optional minimum field width. And add a - before that minimum field width if you want the field to be right aligned, bestie.

Optional blocks? They're ignored unless at least one macro inside of them expands to a non-empty value. No content, no block, periodt.

Example:

set rulerformat='%2l-%S%[ +%x%]'

'runexec'

  • type: boolean
  • default: false

Runs the executable file when you hit Enter, l or Right Arrow. The behaviour of the last two depends on the value of the 'lsview' option, so go check that one too, iykyk 🦋

'scrollbind' 'scb'

  • type: boolean
  • default: false

When this is set, vifm will try to keep the difference of scrolling positions of the two windows constant. So they scroll together like a lil duo 🫶

'scrolloff' 'so'

  • type: integer
  • default: 0

The minimal number of screen lines to keep above and below the cursor. Want the cursor line to ALWAYS be in the middle of the view (except at the beginning or end of the file list, obviously)? Set this to some large value — like 999. Go wild ✨

'sessionoptions' 'ssop'

  • type: set
  • default: tui,state,tabs,savedirs,dhistory

The equivalent of 'vifminfo' but for sessions — it uses the same values, so if you know that one you already know this one 💖

When BOTH options include the same value, data from the session file has higher priority. (And ngl, data from vifminfo isn't necessarily completely discarded — instead it's merged with the state of a session the same way state of multiple instances is merged on exit. Cute, right? 🌸)

'shell' 'sh'

  • type: string
  • default: $SHELL or "/bin/sh" or "cmd" (on MS-Windows)

Full path to the shell that gets used to run external commands. And heads up — on *nix a shell argument can be supplied too, so the shell isn't limited to just a plain path 👑

'shellcmdflag' 'shcf'

  • type: string
  • default: "-c" or "/C" (for cmd.exe on MS-Windows)

The command-line option used to pass a command to 'shell'. It's used in contexts where the command comes from you, the user.

Okay listen. Using this option to force interactive mode of the shell is most likely a BAD IDEA. In general an interactive host and an interactive child shell can't share the same terminal session. You can't even run such a shell in background. So instead: consider writing a wrapper for your shell that preloads aliases and commands without making the shell interactive and ending up using it in a way it was not meant to be used. Please bestie, I'm begging 😭

Also PSA: this option is ignored when 'shell' is set to PowerShell, because of the internal use of -encodedCommand. So don't come for me when it doesn't do anything there 💅

'shortmess' 'shm'

  • type: charset
  • default: "p"

Holds a sequence of single-character flags. Each flag enables shortening of some message that vifm displays in the TUI. The flags:

  • L — display only last directory in tab line instead of full path.
  • M — shorten titles in windows of terminal multiplexers created by vifm down to file name instead of using full path.
  • T — truncate status bar messages in the middle if they are too long to fit on the command line. "..." will appear in the middle.
  • p — use tilde shortening in view titles.

Tiny letters, big vibes 🎀

'showtabline' 'stal'

  • type: enumeration
  • default: multiple

Speficies when the tab line should be displayed. Possible values:

  • never — never display tab line
  • multiple — show tab line only when there are at least two tabs
  • always — display tab line always

Alternatively 0, 1 and 2 — the Vim-like values — are also accepted, and they correspond to "never", "multiple" and "always" respectively. So pick your fighter, you literally can't lose 🌈

'sizefmt'

  • type: string list
  • default: "units:iec"

Configures the way size is formatted in that human-friendly way we all love 💖

  • units: — value iec — Use 1024 byte units (K or KiB, etc.). See the 'iec' option.
  • units: — value si — Use 1000 byte units (KB, etc.).
  • precision: — value i > 0 — How many fraction digits to consider.
  • precision: — value {not set} — Precision of 1 for integer part < 10, 0 otherwise (provides old behaviour).
  • space — {present} — Insert space before unit symbols. This is the default.
  • nospace — {present} — Do not insert space before unit symbols.

Numbers are rounded from zero. Trailing zeros are dropped. No leftovers, no crumbs ✨

Example:

set sizefmt=units:iec,precision:2,nospace

'slowfs'

  • type: string list
  • default: ""
  • only for *nix

A list of mounter fs name beginnings (first column in /etc/mtab or /proc/mounts) or path prefixes for fs/directories that work TOO slow for you. Think of it as telling vifm "hey bestie, don't bother those ones, they're doing their best but slowly" 🐌

This option can be used to stop vifm from making some requests to particular kinds of file systems that can slow down file browsing. Currently this means: don't check if directory has changed, skip check if target of symbolic links exists, assume that link target located on slow fs to be a directory (allows entering directories and navigating to files via gf). If you set the option to "*", it means ALL the systems are considered slow (useful for cygwin, where all the checks might render vifm very slow if there are network mounts).

Example for autofs root /mnt/autofs:

set slowfs+=/mnt/autofs

'smartcase' 'scs'

  • type: boolean
  • default: false

Overrides the ignorecase option if a pattern contains at least one upper case character. Only used when the 'ignorecase' option is enabled. So type a capital letter and suddenly case matters — it's giving ✨selective✨ and honestly, relatable 🌸

✨ 'sort' ✨

type: string list default: +name on *nix and +iname on Windows scope: local

okay bestie this one sets the list of sorting keys — first item is the primary key, second is the secondary key, and so on down the line 💅 it's giving "ranked list but for file ordering". The available keys are:

  • [+-]ext — extension of files and directories
  • [+-]fileext — extension of files only
  • [+-]name — name (including extension)
  • [+-]iname — name (including extension, ignores case)
  • [+-]type — file type (dir/reg/exe/link/char/block/sock/fifo)
  • [+-]dir — directory grouping (directory < file)
  • [+-]gid — group id (*nix only)
  • [+-]gname — group name (*nix only)
  • [+-]mode — file type derived from its mode (*nix only)
  • [+-]perms — permissions string (*nix only)
  • [+-]uid — owner id (*nix only)
  • [+-]uname — owner name (*nix only)
  • [+-]nlinks — number of hard links (*nix only)
  • [+-]inode — inode number (*nix only)
  • [+-]size — size
  • [+-]nitems — number of items in a directory (zero for files)
  • [+-]groups — groups extracted via regexps from 'sortgroups'
  • [+-]target — symbolic link target (empty for other file types)
  • [+-]atime — time accessed (e.g., read, executed)
  • [+-]ctime — time changed (changes in metadata, like mode)
  • [+-]mtime — time modified (when file contents is changed)
🌸 note bestie: go look for st_atime, st_ctime and st_mtime in man 2 stat if you want the full tea on the time keys.

+ means ascending sort for that key, and - means descending sort. periodt.

The dir key is kinda similar in this regard but it's added implicitly — when dir is not specified, sorting behaves as if it was the first key in the list. that's literally why if you want your sorting algorithm to mix directories and files together, you append dir to the sorting option, like this:

set sort+=dir

or

set sort=-size,dir

The value of the option gets checked to include the dir key and the default sorting key (name on *nix, iname on Windows). Here's what happens if one of them is missing, no cap:

  • type key is added at the beginning;
  • default key is added at the end;

all other keys are left untouched (at most they are moved). 🫶

This option also changes view columns according to the primary sorting key set, unless the 'viewcolumns' option is not empty ✨

🔢 'sortnumbers' 🔢

type: boolean default: false scope: local

Natural sort of (version) numbers within text. yeah it just gets it.

🎀 'sortgroups' 🎀

type: string default: "" scope: local

Sets a comma-separated list of regular expressions for the group type of sorting. Double the comma to insert it literally 🙈

The regular expressions are used to extract substrings of file names to serve as keys for sorting. It is essentially a way to ignore uninteresting parts of file names during sorting by name — iconic behaviour honestly.

Each expression should contain at least one group or its value will be considered to be always empty. Also, only the first match of the regular expression is processed. 👑

The first group divides the list of files into sub-groups, each of which is then sorted by substrings extracted using the second regular expression and so on recursively. it's giving nesting dolls but for sorting 💅

Example:

set sortgroups=-(todo|done).*

this would group files with -done in their names and files with -todo separately. On ascending sorting, the group containing -done would appear before the other one. slay.

🔀 'sortorder' 🔀

type: enumeration default: ascending Sets sort order for primary key: ascending, descending.

📊 'statusline' 'stl' 📊

type: string default: "" Determines the content of the status line (the line right above the command-line). Empty string means use the same format like in previous versions. The following macros are supported, bestie, take notes:

  • %N — line break (increases height of the status line accordingly), ignores %[ %] blocks
  • %t — file name (considering value of the 'classify' option)
  • %T — symbolic link target (empty for other filetypes)
  • %f — file name relative to current directory (considers 'classify')
  • %A — file attributes (permissions on *nix or properties on Windows)
  • %o — file permissions in octal form on *nix (nothing on Windows)
  • %u — user name or uid (if it cannot be resolved)
  • %g — group name or gid (if it cannot be resolved)
  • %s — file size in human readable format
  • %E — size of selected files in human readable format, same as %s when no files are selected, except that it will never show size of ../ in visual mode, since it cannot be selected
  • %d — file modification date (uses 'timefmt' option)
  • %D — path of the other pane for single-pane layout
  • %a — amount of free space available on current FS
  • %c — size of current FS
  • %z — short tips/tricks/hints that chosen randomly after one minute period
  • %{<expr>} — evaluate arbitrary vifm expression <expr>, e.g. '&sort' or expand('%d'); a raw } can be inserted as \} (mind that the slash doesn't need to be doubled to be inserted literally)
  • %* — resets or applies one of User1..User20 highlight groups; reset happens when width field is 0 or not specified, one of the groups gets picked when width field is in the range from 1 to 20
  • all 'rulerformat' macros

Percent sign can be followed by optional minimum field width. Add - before minimum field width if you want the field to be right aligned 💅

On Windows, file properties include the following flags (upper case means flag is on):

 A - archive
 H - hidden
 I - content isn't indexed
 R - readonly
 S - system
 C - compressed
 D - directory
 E - encrypted
 P - reparse point (e.g. symbolic link)
 Z - sparse file

Example without colors:

set statusline="  %t%= %A %10u:%-7g %15s %20d %{&sort} "

Example with colors:

highlight User1 ctermbg=yellow
highlight User2 ctermbg=blue ctermfg=white cterm=bold
set statusline="%1* %-26t %2* %= %1* %A %2* %7u:%-7g %1* %-5s %2* %d "

💡 'suggestoptions' 💡

type: string list default: (empty)

Controls when, for what and how suggestions are displayed. The following values are available:

  • normal — in normal mode;
  • visual — in visual mode;
  • view — in view mode;
  • otherpane — use other pane to display suggestions, when available;
  • delay[:num] — display suggestions after a small delay (to do not annoy if you just want to type a fast shortcut consisting of multiple keys), num specifies the delay in ms (500 by default), 'timeoutlen' at most;
  • keys — include shortcuts (commands and selectors);
  • foldsubkeys — fold multiple keys with common prefix;
  • marks — include marks;
  • registers[:num] — include registers, at most num files (5 by default).

🔄 'syncregs' 🔄

type: string default: "" Specifies identifier of a group of instances that share registers among each other. When several instances of vifm have this option set to an identical value, they automatically synchronize contents of their registers on operations which use them. besties sharing secrets fr fr 🫶

⚙️ 'syscalls' ⚙️

type: boolean default: false When disabled, vifm will rely on external applications to perform file-system operations, otherwise system calls are used instead (much faster and supports progress tracking). The option should eventually be removed. Mostly *nix-like systems are affected. ngl the "will be removed" is giving deprecated energy, so don't get too attached 💀

🏷️ 'tablabel' 🏷️

type: string default: "" When non-empty and 'tabline' isn't set, determines the format of the main part of a single tab's label.

When empty, the tab label is set to either the tab name for named tabs or to the view title (usually current path) for unnamed tabs.

The following macros can appear in the format (see below for what a flag is):

  • %C — flag of a current tab
  • %N — number of the tab
  • %T — flag of a tree mode
  • %c — description of a custom view
  • %n — name of the tab
  • %p — path of the view (handles filename modifiers)
  • %t — title of the view (affected by 'shortmess' flags)
  • %% — literal percent sign
  • %[ — designates beginning of an optional block
  • %] — designates end of an optional block
  • %*, %0* — resets highlighting
  • %1*-%20* — applies one of User1..User20 highlight groups

In global tabs, the view in the bullets above refers to the currently active view of that tab 👑

Flag macros are a special kind of macro that always expand to an empty value and are meant to be used inside optional blocks to control their visibility ✨

Optional blocks are ignored unless at least one macro inside of them is expanded to a non-empty value or is a set flag macro.

" %[(%n)%]        -- optional name of the tab
" %[              -- optional description of the view
"   %[%T{tree}%]  -- mark of tree mode
"   %[{%c}%]      -- description of custom view
"   @             -- just an extra separator before the path
' %]
" %p:t            -- tail part of view's location
set tablabel=%[(%n)%]%[%[%T{tree}%]%[{%c}%]@%]%p:t

📑 'tabline' 'tal' 📑

type: string default: "" When non-empty, determines the format of the tab line. Note that mouse clicks won't be handled when this option is non-empty. 🫠

The following macros can appear in the format:

  • %*, %0* — resets highlighting
  • %1*-%20* — applies one of User1..User20 highlight groups

'tabprefix'

  • type: string
  • default: "[%N:"

bestie this is literally just the lil' intro bit of a tab's label 💅 it decides the prefix of a tab's label, and the formatting is done exactly the same way as for the 'tablabel' option, no cap.

'tabscope'

  • type: enumeration
  • default: global

this one picks the style of tabs, and that style is what defines what a single tab actually contains 👑

possible values, periodt:

  • global — a tab describes the complete UI of two views and how they are arranged
  • pane — a tab is located "inside" a pane and manages it and quick view

'tabstop' 'ts'

  • type: integer
  • default: value from curses library

how many spaces does a Tab in the file count for? this many, bestie 🎀

'tabsuffix'

  • type: string
  • default: "]"

the matching outro to 'tabprefix' — it determines the suffix of a tab's label, and the formatting is done as for the 'tablabel' option 🌸

'timefmt'

  • type: string
  • default: "%m/%d %H:%M"

the format of time in the file list ⏰ see man 1 date or man 3 strftime for the details, iykyk.

'timeoutlen' 'tm'

  • type: integer
  • default: 1000

the time in milliseconds that gets waited for a mapped key when the key sequence you already typed is ambiguous 😭 she's patient but not that patient.

'title'

  • type: boolean
  • default: true when title can be restored, false otherwise

when it's enabled, the title of the terminal (or the terminal multiplexer's window) gets updated according to the current location 👑

because not every terminal supports setting the title, this only works if $TERM matches one of these conditions:

  • equals "xterm" or starts with "xterm-"
  • equals "rxvt" or starts with "rxvt-"
  • equals "screen" or starts with "screen-"
  • equals "aterm"
  • equals "Eterm"

'trash'

  • type: boolean
  • default: true

use the trash directory 🗑️ see the "Trash directory" section below, bestie.

'trashdir'

  • type: string
  • default:

on *nix:

"%r/.vifm-Trash-%u,$XDG_DATA_HOME/vifm/Trash,%r/.vifm-Trash"

or

"%r/.vifm-Trash-%u,$VIFM/Trash,%r/.vifm-Trash"

on Windows:

"%r/.vifm-Trash,$XDG_DATA_HOME/vifm/Trash"

or

"%r/.vifm-Trash,$VIFM/vifm/Trash"

it's a list of trash directory path specifications, separated with commas 💖 each list item either defines an absolute path to the trash directory, or a path relative to a mount point root when the list element starts with "%r/". the value of the option can contain environment variables (of the form "$envname"), which get expanded — prepend $ with a slash to stop the expansion. environment variables are expanded when the option is set.

on *nix, if an element ends with "%u", the mark is replaced with the real user ID and permissions are set so that only that owner is able to use it 🔐

ngl, even this setup is not completely secure when combined with "%r/", and it's overall safer to keep files in the home directory — but that implies the cost of copying files between partitions 😬

when a new file gets cut (deleted), vifm traverses each element of the option in the order of their appearance and uses the first trash directory that it was able to create, or that's already writable ✨

the default value tries to use a trash directory per mount point and falls back to the common trash directory on failure.

it will attempt to create the directory if it doesn't exist 🫶 see the "Trash directory" section below.

'tuioptions' 'to'

  • type: charset
  • default: "psv"

each flag here configures some aspect of the TUI's appearance 👑

  • p — when included:
    • the file list inside a pane gets additional single character padding on left and right sides;
    • quick view and view mode get single character padding.
  • s — when included, left and right borders (side borders, hence the "s" character) are visible.
  • u — use Unicode characters in the TUI (Unicode ellipsis instead of "...").
  • v — vary the width of the vertical middle border to equalize view sizes.

each pane title contains the path of the listed directory. if it's too large, the path is truncated on the left for the active pane and on the right for the other pane 🎀 and this can be modified with:

  • l — truncation is always on the left.
  • r — truncation is always on the right.

'uioptions'

  • type: set
  • default:

tweaks UI behaviour 💅 the following values are available:

  • iodetails — show the I/O progress details dialog automatically instead of displaying progress on the statusbar until the user presses "i" to see the dialog.

'undolevels' 'ul'

  • type: integer
  • default: 100

the maximum number of changes that can be undone 😭 note that here a single file operation is used as a unit, not the operation itself — i.e. deleting 101 files will exceed the default limit. she stays bookkeeping fr fr.

'vicmd'

  • type: string
  • default: "vim"

the command used to edit files in various contexts 🖊️ an ampersand sign at the end (regardless of whether it's preceded by a space or not) means backgrounding of the command.

the background flag is ignored in certain contexts where vifm waits for the editor to finish 🙈 such contexts include any command that spawns an editor to change the list of file names or a command — with :rename being one example. -f is also appended to prevent forking in such cases, so the command needs to handle the flag.

additionally +{num} and +'call cursor()' arguments are used to position the cursor when the location is known ✨

'viewcolumns'

  • type: string
  • default: ""
  • scope: local

a format string containing the list of columns in the view 🌈 when this option is empty, the view columns to show get chosen automatically using the sorting keys (see 'sort') as a base. the value of this option is ignored if 'lsview' is set. see the "Column view" section below for the format description.

an example of setting the options for both panes (note the :windo command):

windo set viewcolumns=-{name}..,6{size},11{perms}

'vixcmd'

  • type: string
  • default: value of 'vicmd'

same as 'vicmd', but it takes precedence over it when running inside a graphical environment 👑

'vifminfo'

  • type: set
  • default: bookmarks,bmarks

controls what will be saved in the $VIFM/vifminfo file 💾

  • bmarks — named bookmarks (see :bmark command)
  • bookmarks — marks, except for special ones like '< and '>
  • cs — primary color scheme
  • dirstack — directory stack (overwrites previous stack, unless stack of current instance is empty)
  • registers — registers content
  • savedirs — last visited directory
  • state — file name and dot filters and terminal multiplexers integration state
  • tabs — global or pane tabs
  • tui — state of the user interface (sorting, number of windows, quick view state, active view)
  • chistory — command line history
  • dhistory — directory history
  • ehistory — expression register history (see description of Ctrl+R = in command-line mode)
  • fhistory — history of local filter (see description of the "=" normal mode command)
  • mchistory — command line history of menus
  • phistory — prompt history
  • shistory — search history (/ and ? commands)
  • commands — user defined commands (see :command description) (obsolete)
  • filetypes — associated programs and viewers (obsolete)
  • options — all options that can be set with the :set command (obsolete)

'vimhelp'

  • type: boolean
  • default: false

use vim help format 📖 that's it, that's the whole vibe.

'wildinc'

  • type: string
  • default: ""

a comma-separated list of globs which defines what should be completed incrementally ✨ currently, it can only be :commands, which are matched with the colon in front of their name. for such commands, completion is always active and is displayed even if there's only one completion item 👑

examples:

" for all :commands
set wildinc=:*
" only for these two
set wildinc=:wingo,:bmgo

see the "Patterns" and "Globs" sections for more info on the syntax 🫶

'wildmenu' 'wmnu'

  • type: boolean
  • default: false

controls whether possible matches of completion will be shown above the command line 🌸

'wildstyle'

  • type: enumeration
  • default: bar

picks the presentation style of the wild menu 💅 possible values:

  • bar — one-line with left-to-right cursor
  • popup — multi-line with top-to-bottom cursor

'wordchars'

  • type: string list
  • default: "1-8,14-31,33-255" (that is all non-whitespace characters)

specifies which characters in command-line mode should be considered as part of a word 🔤 the value of the option is a comma-separated list of ranges. if both endpoints of a range match, a single endpoint is enough (e.g. "a" = "a-a"). both endpoints are inclusive. there are two accepted forms: the character representing itself, or a number encoding the character according to the ASCII table 🎀 in the case of ambiguous characters (dash, comma, digit), use the numeric form. accepted characters are in the range from 0 to 255. any Unicode character with code greater than 255 is considered to be part of a word.

the option affects Alt+D, Alt+B and Alt+F, but not Ctrl+W. this is intentional, to allow two use cases:

  • moving by WORDS and deletion by words.
  • moving by words and deletion by WORDS.

to get the latter, use the following mapping:

cnoremap <c-w> <a-b><a-d>

also used for abbreviations ✨

'wrap'

  • type: boolean
  • default: true

controls whether to wrap text in quick view 🦋

'wrapscan' 'ws'

  • type: boolean
  • default: true

searches wrap around the end of the list 🔁 iconic behaviour, honestly.

✨ Mappings ✨

okay bestie, mappings are literally the group chat of keybinds 💅 A user mapping like nnoremap lhs rhs defines a substitution of the left-hand-side (LHS) with the right-hand-side (RHS) in the input stream. A regular mapping (without "nore" in :command's name) expands recognized sequences in the RHS, while a *noremap mapping always interprets RHS as if no user mappings were defined and each key has its builtin meaning. In most cases you want to use the noremap variant, and if your RHS includes LHS, only the noremap variant will work because recursion in a mapping is not allowed. no cap 🚫🔁

In order to define a mapping, determine in which mode you want to activate it and use an appropriate *noremap :command (e.g., :nnoremap for a normal mode mapping). RHS doesn't have to limit itself to the mode in which the mapping was started and can span multiple modes. it's giving main character energy across modes fr fr ✨

🎀 Map arguments 🎀

LHS of mappings can be preceded by arguments which take the form of special sequences:

  • <silent> — Postpone UI updates until RHS is completely processed. lowkey polite, honestly 🫶
  • <wait> — In case of builtin mapping causing conflict for a user-defined mapping (e.g., t builtin to a partially typed ta user-defined mapping), ignore the builtin mapping and wait for input indefinitely as opposed to default behaviour of triggering the builtin mapping after a delay defined by 'timeoutlen'. Example:
nnoremap <wait> tw :set wrap!<cr>
nnoremap <wait> tn :set number!<cr>
nnoremap <wait> tr :set relativenumber!<cr>

🌈 Special sequences 🌈

Since it's not easy to enter special characters, there are several special sequences that can be used in place of them. They are:

  • <cr> — Enter key. ⏎
  • <esc> — Escape key. 😳
  • <space> — Space key. 🫧
  • <lt> — Less-than character (<).
  • <nop> — provides a way to disable a mapping (by mapping it to <nop>). iconic 🚫
  • <bs> — Backspace key (see key conflict description below).
  • <tab> <s-tab> — Tabulation and Shift+Tabulation keys.
  • <home> <end> — Home/End.
  • <left> <right> <up> <down> — Arrow keys.
  • <pageup> <pagedown> — PageUp/PageDown.
  • <del> <delete> — Delete key. <del> and <delete> mean different codes, but <delete> is more common.
  • <insert> — Insert key.
  • <s-home> <s-end> / <s-left> <s-right> <s-up> <s-down> / <s-pageup> <s-pagedown> / <s-delete> <s-insert> — Shift + one of the keys from above, if terminal and its terminfo supports it.
  • <c-a>,<c-b>,...,<c-z>,<c-[>,<c->,<c-]>,<c-^>,<c-_> — Control + some key (see key conflict description below).
  • <c-@> {only for *nix} — Control + Space.
  • <a-a>,<a-b>,...,<a-z> / <m-a>,<m-b>,...,<m-z> / <a-0>,<a-1>,...,<a-9> {only for *nix} / <m-0>,<m-1>,...,<m-9> {only for *nix} — Alt + some key.
  • <a-s-a>,<a-s-b>,...,<a-s-z> {only for *nix} / <s-a-a>,<s-a-b>,...,<s-a-z> {only for *nix} / <m-s-a>,<m-s-b>,...,<m-s-z> {only for *nix} / <s-m-a>,<s-m-b>,...,<s-m-z> {only for *nix} — Alt + Shift + some key.
  • <a-c-a>,<a-c-b>,...,<a-c-z> {only for *nix} / <m-c-a>,<m-c-b>,...,<m-c-z> {only for *nix} — Alt + Ctrl + some key.
  • <f0> - <f63> — functional keys. These also correspond to keys like <c-f1> and can be used in their place.
  • <c-f1> - <c-f12> — functional keys with Control key pressed.
  • <a-f1> - <a-f12>, <m-f1> - <m-f12> — functional keys with Alt key pressed.
  • <s-f1> - <s-f12> — functional keys with Shift key pressed.

Note that whether and how functional keys work might depend on the terminal and corresponding terminfo record. fr fr, terminal lore is real 🧚

Note that due to the way terminals process their input, several keyboard keys might be mapped to single key code, for example:

  • <cr> and <c-m>;
  • <tab> and <c-i>;
  • <c-h> and <bs> and <del>;
  • etc.

Most of the time they are defined consistently and don't cause surprises, but <c-h> and <bs> are treated differently in different environments (although they match each other all the time), that's why they correspond to different keys in vifm. As a consequence, if you map <c-h> or <bs> be sure to repeat the mapping with the other one so that it works in all environments. Alternatively, provide your mapping in one form and add one of the following:

" if mappings with <c-h> in the LHS work
map <c-h> <bs>
" if mappings with <bs> in the LHS work
map <bs> <c-h>

Also sometimes neither of them might work and it's <del> key which corresponds to your backspace (don't mind the name). 💀

🧚 Whitespace 🧚

vifm removes whitespace characters at the beginning and end of commands. That's why you may want to use <space> at the end of rhs in mappings. For example:

cmap <f1> man<space>

will put "man " in line when you hit the <f1> key in the command line mode. periodt 🫶

✨ Expression syntax ✨

okay so bestie, vifm has its own lil expression language and here's the tea: it's a subset of what VimL gives you. Not the whole buffet, just the good parts. 🫶

Here's the entire syntax summary, ordered from least significant to most significant (so the ones at the top bind the loosest, the ones at the bottom latch on the tightest):

expr1      expr2
           expr2 || expr2 ..       logical OR

expr2      expr3
           expr3 && expr3 ..       logical AND

expr3      expr4
           expr4 == expr4          equal
           expr4 != expr4          not equal
           expr4 >  expr4          greater than
           expr4 >= expr4          greater than or equal
           expr4 <  expr4          smaller than
           expr4 <= expr4          smaller than or equal

expr4      expr5
           expr5 + expr5 ..        number addition
           expr5 - expr5 ..        number subtraction

expr5      expr6
           expr6 . expr6 ..        string concatenation

expr6      expr7
           - expr6                 unary minus
           + expr6                 unary plus
           ! expr6                 logical NOT

expr7      number                  number constant
           "string"                string constant, \ is special
           'string'                string constant, ' is doubled
           &option                 option value
           $VAR                    environment variable
           g:var                   global variable
           v:var                   builtin variable (read-only)
           function(expr1, ...)    function call
           (expr1)                 nested expression

And that ".." situation? It means the operations at that level can be concatenated, like, endlessly. Stack 'em up. 💅

expr1

expr2 || expr2 — this is the logical OR babe.

  • Both arguments get converted to numbers before anything gets evaluated.
  • The result is non-zero if at least one of the arguments is non-zero. One lil truthy guy is all it takes. ✨
  • It's right associative and it short-circuits, so sub-expressions get evaluated from left to right until the result of the whole expression is determined (i.e., until the first non-zero) or until we run out of expression.

expr2

expr3 && expr3 — logical AND, the picky one.

  • Arguments are converted to numbers before evaluation.
  • The result is non-zero only if both arguments are non-zero. Both. No exceptions. Both.
  • Also right associative, also short-circuiting, so sub-expressions are evaluated from left to right until the result of the whole expression is determined (i.e., until the first zero) or the expression ends.

expr3

expr4 {cmp} expr4 — comparison era.

You compare two expr4 expressions and you get 0 if it evaluates to false, or 1 if it evaluates to true. That's it. Binary queen. 👑

  • equal — ==
  • not equal — !=
  • greater than — >
  • greater than or equal — >=
  • smaller than — <
  • smaller than or equal — <=

Examples, because seeing it > reading it:

'a' ==  'a'         == 1
'a' >   'b'         == 1
'a' ==  'b'         == 0
'2' >   'b'         == 0
 2  >   'b'         == 1
 2  >   '1b'        == 1
 2  >   '9b'        == 0
-1  == -'1'         == 1
 0  ==  '--1'       == 1

expr4

  • expr5 + expr5 .. — number addition
  • expr5 - expr5 .. — number subtraction

Basic math, we love her. 💖

Examples:

 1 + 3 - 3          == 1
 1 + '2'            == 3

expr5

expr6 . expr6 .. — string concatenation. That's the lone dot, bestie, do not confuse her with the .. situation.

Examples:

'a' . 'b'           == 'ab'
'aaa' . '' . 'c'    == 'aaac'

expr6

The unary corner of the language. Three icons:

  • - expr6 — unary minus
  • + expr6 — unary plus
  • ! expr6 — logical NOT

The deets:

  • For - the sign of the number is changed.
  • For + the number is unchanged. (Yes it literally just vibes there.)
  • For ! non-zero becomes zero, zero becomes one.
  • A String will be converted to a Number first.

These operations can be repeated and mixed, and honestly that's where it gets fun. Examples:

 --9                == 9
---9                == -9
 -+9                == 9
 !-9                == 0
 !''                == 1
!'x'                == 0
 !!9                == 1

expr7

This is the bottom of the food chain, the most significant level — the actual values. expr7 can be any of these:

  • number — number constant
  • "string" — string constant, \ is special
  • 'string' — string constant, ' is doubled
  • &option — option value
  • $VAR — environment variable
  • g:var — global variable
  • v:var — builtin variable (read-only)
  • function(expr1, ...) — function call
  • (expr1) — nested expression

Now let's meet each one properly. 💅

number

number — a number constant. It's decimal. That's the whole vibe.

Examples:

 0                   == 0
 0000                == 0
 01                  == 1
 123                 == 123
 10000               == 10000

string

"string" — a string constant. Note that double quotes are used here, not the single ones. 🎀

A string constant accepts these special characters:

\b      backspace <bs>
\e      escape <esc>
\n      newline
\r      return <cr>
\t      tab <tab>
\\      backslash
\"      double quote

Examples:

"\"Hello,\tWorld!\""
"Hi,\nthere!"

literal-string

'string' — also a string constant, but single quotes this time.

This string is taken as it is. No backslashes are removed, none of them have a special meaning, nothing. The only exception is that two quotes stand for one quote.

Examples:

'All\slashes\are\saved.'
'This string contains doubled single quotes ''here'''

option

Reading a setting right out of the config, no cap:

  • &option — option value (local one is preferred, if it exists)
  • &g:option — global option value
  • &l:option — local option value

Examples:

echo 'Terminal size: '.&columns.'x'.&lines
if &columns > 100

Any valid option name can be used here (note that "all" in :set all is a pseudo option, she's not a real one). See the :set options section above if you need a refresher. ✨

environment variable

$VAR — environment variable.

The String value of any environment variable. And when it's not defined? The result is an empty string. No drama, just silence. 💀

Examples:

'This is my $PATH env: ' . $PATH
'vifmrc at ' . $MYVIFMRC . ' is used.'

global variable

g:var — global variable.

A typed storage of data for use in scripting. Can be created/removed dynamically (via :let and :unlet) and used in expressions. Build her up, tear her down. 🦋

builtin variable

v:var — builtin variable.

Information exposed by vifm for use in scripting. Such variables are predefined and read-only, but not necessarily constant. The full roster:

  • v:count — count passed to : command, 0 by default. Can be used in mappings to pass the count to a different command.
  • v:count1 — same as v:count, but 1 by default.
  • v:jobcount — number of active jobs (as can be seen in the :jobs menu).
  • v:session — name of the current session or empty string.
  • v:servername — See below.
  • v:version — version of the application as an integer. Version x.y.z becomes number x*100*100 + y*100 + z, examples:
    • v0.14 (that is v0.14.0) is 1400 (leading zeroes omitted)
    • v1.0.2 is 10002

Release candidates aren't real releases, they report the number of a corresponding release.

function call

function(expr1, ...) — function call. See the "Functions" section below, bestie, there's a whole cast of characters down there. 🌈

Examples:

"'" . filetype('.') . "'"
filetype('.') == 'reg'

expression nesting

(expr1) — nested expression.

Groups any other expression of arbitrary complexity enforcing order in which operators are applied. Basically parentheses doing parentheses things. Main character energy for a couple of curved lines, honestly. 👑

✨ FUNCTIONS ✨

Okay bestie, THIS is where it gets fun 💅 these are the built-in functions you can call from your expressions. Think of them as your little toolbox of ✨magic✨ that you drop into :execute, statuslines, mappings, all of it. Each one gives you back a value, and here's the whole vibe check first:

  • chooseopt({opt}) → String — queries the choose parameters that got passed at startup 🎀
  • escape({string}, {chars}) → String — hands you back {string} after escaping {chars} inside it
  • executable({expr}) → Integer — checks whether the {expr} command is actually available 👀
  • expand({expr}) → String — expands special keywords in {expr}
  • extcached({cache}, {path}, {extcmd}) → String — caches the output of {extcmd} per {cache} and {path} combo, no cap
  • filereadable({path}) → Integer — checks whether {expr} points to a non-directory that can be read 📖
  • filetype({file} [, {resolve}]) → String — returns the file type from a position or a path
  • fnameescape({expr}) → String — escapes {expr} so it's safe to use in a :command
  • getpanetype() → String — returns the type of the current pane
  • has({property}) → Integer — checks whether this instance has {property}
  • input({prompt} [, {initial} [, {completion}]]) → String — prompts the user for input right on the command-line 💬
  • layoutis({type}) → Integer — checks whether the layout is of type {type}
  • paneisat({loc}) → Integer — checks whether the current pane is at {loc}
  • selected() → Integer — returns the number of files currently selected
  • system({command}) → String — runs a shell command and gives you back its output
  • tabpagenr([{arg}]) → Integer — returns the number of the current or the last tab
  • term({command}) → String — like system(), but for interactive commands 🖥️

🌸 chooseopt({opt})

Gets you the values of the options related to file choosing. {opt} can be any one of these:

  • files — returns the argument of --choose-files, or an empty string
  • dir — returns the argument of --choose-dir, or an empty string
  • cmd — returns the argument of --on-choose, or an empty string
  • delimiter — returns the argument of --delimiter, or the default one (\n)

🌸 escape({string},{chars})

Escapes every single occurrence of {chars} in {string} by sticking a slash (\) in front of them. Real talk though: the slash itself does not get escaped unless it shows up in {chars}. So don't come for me when your backslashes are still unbothered 🙈

🌸 executable({expr})

If {expr} is an absolute or relative path, it checks whether that path's destination exists and refers to something executable. Otherwise it checks whether a command named {expr} is present in the directories listed in $PATH. On Windows it also checks for various executable extensions. Either way you get a boolean value describing the result of the check. 💯

Example:

" use custom default viewer script if it's available and installed
" in predefined system directory, otherwise try to find it elsewhere
if executable('/usr/local/bin/defviewer')
    fileview * /usr/local/bin/defviewer %c
else
    if executable('defviewer')
        fileview * defviewer %c
    endif
endif

🌸 expand({expr})

Expands environment variables and macros in {expr} — in that order, bestie, don't mix it up. Returns a string. Check the "Command macros" section above if you need a refresher 🦋

Examples:

" percent sign
:echo expand('%%')
" the last part of directory name of the other pane
:echo expand('%D:t')
" $PATH environment variable (same as `:echo $PATH`)
:echo expand('$PATH')
" full path to the current file with backslashes
:echo expand('%c:p:gs!/!\!')

🌸 extcached({cache}, {path}, {extcmd})

Caches the value of the {extcmd} external command and auto-updates it as needed, based on monitoring the change date of a {path}. The cache gets invalidated whenever the file or its meta-data is updated. And yes, a single path can have multiple caches associated with it — she contains multitudes 💅

The {path} value is normalized, but symbolic links inside it are not resolved.

Example:

" display number and size of blocks actually used by a file or directory
set statusline+=" Uses: %{ extcached('uses',
                                   \ expand('%c'),
                                   \ expand('stat --format=%%bx%%B %c')) }"

🌸 filereadable({path})

Checks whether {path} exists, refers to a non-directory entry, and has permissions that allow reading. Returns a boolean value describing the result of the check. Simple as that, periodt ✨

🌸 filetype({file} [, {resolve}])

Checks the type of a view's entry, or of a file specified by its path.

The {file} parameter can take these forms:

  • . to get the type of the file under the cursor in the active pane
  • a numerical value base 1, to get the type of the file on that specified line number (only works if there are no characters other than +-0123456789)
  • a path (prepend ./ to force a number or . to be interpreted as a path instead)

The optional {resolve} parameter is treated as a boolean and says whether symbolic links should be resolved.

The result is a string representing the file type, and it's one of these:

  • exe — executables
  • reg — regular files
  • link — symbolic links
  • broken — broken symbolic links (only appears when resolving)
  • dir — directories
  • char — character devices
  • block — block devices
  • fifo — pipes
  • sock — *nix domain sockets
  • ? — unknown file type (should not normally happen) or a non-file (those pseudo-entries in compare view)

The result can also be an empty string if you handed it an invalid argument 🙈

🌸 fnameescape({expr})

Escapes a parameter to make it suitable for use as an argument of a :command. The list of escaped characters includes %, which gets doubled.

Usage example:

" navigate to most recently modified file in current directory
execute 'goto' fnameescape(system('ls -t | head -1'))

🌸 getpanetype()

Gets you a string describing the type of the current pane. Possible return values:

  • regular — regular file listing of some directory
  • custom — custom file list (%u)
  • very-custom — very custom file list (%U)
  • tree — tree view
  • compare — compare view

🌸 has({property})

Lets you peek at internal parameters from scripts, so you can figure out stuff like the environment the app is running in. Returns 1 if the property is true/present, otherwise you get 0. Right now these are the supported properties (anything else will just hand you a 0):

  • unix — runs in a *nix-like environment (including Cygwin)
  • win — runs on Windows
  • #* — whether a particular Lua handler exists

Usage example:

" skip user/group on Windows
if !has('win')
    let $RIGHTS = '%10u:%-7g '
endif

execute 'set' 'statusline="  %t%= %A '.$RIGHTS.'%15E %20d  "'

🌸 input({prompt} [, {initial} [, {completion}]])

Creates a command-line prompt to grab the user's input 💬 You can supply an initial value as the optional second parameter — otherwise an empty string is used.

The optional third parameter specifies the kind of completion, which can be one of:

  • dir — paths to directories
  • file — paths to files and directories
  • "" — (empty string, the default) no completion at all
Heads up bestie: the behaviour here differs from Vim. In Vim, executing a mapping like nnoremap j :echo input('text: ')<cr>input leaves you sitting in a prompt mode with input typed in. Vifm? She will wait for you to leave the prompt and then continue executing the mapping. Different girl, different energy 💅

Usage example:

nnoremap ,m : let $DIR_NAME = input('mkdir: ', '', 'dir')
           \| if $DIR_NAME != ''
           \|     execute 'mkdir' fnameescape($DIR_NAME)
           \| endif<cr>

🌸 layoutis({type})

Checks whether the current interface layout is {type} or not — where {type} can be:

  • only — single-pane mode
  • split — double-pane mode (either vertical or horizontal split)
  • vsplit — vertical split (left and right panes)
  • hsplit — horizontal split (top and bottom panes)

Usage example:

" automatically split vertically before enabling preview
:nnoremap w :if layoutis('only') | vsplit | endif | view!<cr>

🌸 paneisat({loc})

Checks whether the position of the active pane in the current layout matches one of these locations:

  • top — pane reaches the top border
  • bottom — pane reaches the bottom border
  • left — pane reaches the left border
  • right — pane reaches the right border

🌸 selected()

Gets you the number of files selected in the active pane. That's it, that's the whole function, and she ate 🍓

🌸 system({command})

Runs the command in a shell and returns its output (the standard output and standard error streams joined together). All trailing newline characters get stripped, so you can easily append stuff to the command's output. Ctrl+C should interrupt the command, fr fr.

Use this function to consume the output of external commands that don't need user interaction — and use term() for interactive commands that make use of the terminal and are capable of handling stream redirection. Pick the right girl for the job 👑

Usage example:

" command to enter .git/ directory of git-repository (when ran inside one)
command! cdgit :execute 'cd' fnameescape(system('git rev-parse --git-dir'))

🌸 tabpagenr([{arg}])

When you call it with no arguments, it returns the number of the current tab page, base one.

When you call it with "$" as the argument, it returns the number of the last tab page, base one — which is the same as the number of tabs. Iconic ✨

🌸 term({command})

Same as the system() function, but the user interface gets shut down while the command executes, which makes absolutely sure that external interactive applications won't mess with the way the terminal is used by vifm. Main character energy for your terminal 🖥️💖

Usage example:

" command to change directory by picking it via fzf
command! fzfcd :execute 'cd'
                      \ fnameescape(term('find -type d | fzf 2> /dev/tty'))

:range — navigate to a menu line, that's it bestie.

:chi[story] — pops open a menu of all your saved menus. ✨ For the controls, go peek at the "Menus and dialogs" section, and the "Menus history" section too.

:col[der] — loads an older navigation menu, but only if one exists. See also "Menus history" section. 💜

:cnew[er] — loads a newer navigation menu, if there's one kicking around.

:fin[d] — does exactly what the non-menu :find does, except no range is accepted here. If your active view was holding a selection before you entered menu mode, this command takes it into account. 👑

:gr[ep] — same deal as non-menu :grep, but again, no range accepted. And yeah, if the active view had a selection before menu mode, it factors that in. 🫶

:exi[t][!] :q[uit][!] :x[it][!] — all three just leave menu mode. bye 💅

:noh[lsearch] — resets the search match highlighting. clean slate ✨

:w[rite] {path} — writes all menu lines out into the file at {path}.

🌈 Common keys of all menus and dialogs 🌈

  • j, Ctrl+N — move the cursor down. ⬇️
  • k, Ctrl+P — move the cursor up. ⬆️
  • Enter — select and, usually, close the menu/dialog.
  • Ctrl+L — redraw the menu/dialog. 🖌️
  • Escape, Ctrl+C
  • ZZ, ZQ
  • q — close menu/dialog. 🚪

💖 Common keys of all menus 💖

  • Ctrl+B, Ctrl+F
  • Ctrl+D, Ctrl+U
  • Ctrl+E, Ctrl+Y
  • /, ?
  • n, N
  • [count]G, [count]gg
  • H, M, L
  • zb, zt, zz — all of these mean exactly the same thing they do in normal mode. no cap. 😌
  • [count]zh — scroll menu items [count] characters (default is 1) to the right. ➡️
  • [count]zl — scroll menu items [count] characters (default 1) to the left. ⬅️
  • zH — scroll menu items half the screen width to the right.
  • zL — scroll menu items half the screen width to the left.
  • : — enter command line mode for menus.
  • b — treats the content of the menu as a list of paths and uses it to create a custom view in place of the previously active pane. 👀 Check the "Custom views" section below.
  • B — same as b, but makes an unsorted view.
  • v — loads menu content into the quickfix list of an editor (Vim-compatible, assumed), or, if that list has no separators after file names (colons), it opens each line as a file name. 🔥

This whole vibe applies to these menus:

  • :bmarks, :bmgo
  • :find
  • :grep
  • :locate
  • user menu with navigation (the %M macro)

Keys:

  • gf — navigate the previously active view to the currently selected item. Leaves menu mode... except for the :grep menu. Pressing Enter or l does the exact same thing.
  • e — open selected path in an editor, and stays in menu mode. 📝
  • c — leave menu preserving file selection, then insert the file name after :! in command-line mode. Does absolutely nothing in :bmarks and :bmgo. 💀
Heads up bestie: each of these menus can have extra keys too, peep below.

✨ History menus (:history *) ✨

🌸 Command-line history menu

  • Enter, l — execute the item as a command-line command, a search query, or a local filter.
  • c — leave the menu preserving file selection, and insert the item into the command-line of the appropriate kind.

🌸 Directory history menu

  • Enter, l — navigate into the selected directory.
  • Enter, l — execute command without leaving the menu.
  • c — insert menu item into the command-line for editing.

🍓 Other menus 🍓

Apropos (:apropos) menu

  • Enter, l — run man on a given topic. The menu won't close automatically, so you can vibe through several pages one by one. 📖

Bookmarks (:bmarks, :bmgo) menu

  • Enter, l — navigate to the selected bookmark.
  • dd — remove bookmark under the cursor. 🗑️

Also see the gf and e keys from above. 💜

Command-line mode abbreviations (:cabbrev) menu

  • dd — remove abbreviation under the cursor.

Color scheme (:colorscheme) menu

  • Enter, l — apply the selected colorscheme exactly as if :colorscheme <name> had been typed on the command-line. 🎨

Commands (:command) menu

  • Enter, l — execute the command with empty arguments (the %a macro).
  • dd — remove command under the cursor.
  • c — leave menu preserving file selection, and insert the right-hand side of the selected command into the command-line.

Directory stack (:dirs) menu

  • Enter, l — rotate the stack to put the selected directory pair at the top. 🔄

File (:file) menu

Commands from vifmrc, or ones you typed on the command-line, show up above an empty line — if that empty line is there. Everything below the empty line comes from .desktop files. 🌈

Commands detected as available get a "[present]" to their left. ✅

  • Enter, l — run the selected command (doesn't matter whether it was detected as present or not).
  • c — leave menu preserving file selection, and insert command after :! in command-line mode.

Grep (:grep) menu

  • Enter, l — open file in an editor set by 'vicmd' at the given line number. The menu won't close automatically, so you can check more than one result. 🔍

Also see the gf, e and c keys above.

Jobs (:jobs) menu

  • dd — request cancellation of the job under the cursor. The job won't be removed from the list, it just gets marked as being cancelled (if cancellation was successfully requested). A message pops up if the job has already stopped. 💀 Note that on Windows, cancelling external programs like this might not work, because their parent shell doesn't have any windows.
  • e — display errors of the selected job, if any were collected. They show up in a new menu, but you can get back to the jobs menu by pressing h.
  • r — reload the list of jobs.

Marks (:marks) menu

  • Enter, l — navigate to selected mark.
  • dd — remove mark under the cursor.

Media (:media) menu

  • Enter, l — behaviour differs by line kind:
    • mount an unmounted device
    • navigate to the first mount point of a mounted device
    • navigate to a mount point
    • do nothing for "not mounted" or an empty line
  • r — reload the list.
  • m — mount/unmount device (cursor should be positioned on lines under device information).
  • [ — put cursor on the previous device.
  • ] — put cursor on the next device.
  • Enter, l — load selected menu.

Plugins (:plugins) menu

  • e — display log messages of the selected plugin, if any were collected. They show up in a new menu, but you can return to the plugins menu by pressing h.
  • gf — navigate the previously active view to the location of the selected plugin. Leaves the menu mode. 🧚

Trash (:lstrash) menu

  • r — restore a file from the trash to its original location. ♻️
  • dd — delete file under the cursor.

Trashes (:trashes) menu

  • Enter, l — navigate into current trash directory.
  • dd — start emptying the selected trash in the background.

Undolist (:undolist) menu

  • r — reset undo position to the group under the cursor.

User menu without navigation (%m macro)

  • c — leave menu preserving file selection, and insert the whole line after :! in command-line mode.

Volumes (:volumes) menu

only for MS-Windows 🪟

  • Enter, l — navigate into the root of the selected drive.

👑 Dialog-specific operations 👑

Attributes (permissions or properties) dialog

  • h, Space — check/uncheck. ☑️
  • q — close the dialog.
  • r — (*nix only) (un)set all read bits.
  • w — (*nix only) (un)set all write bits.
  • x — (*nix only) (un)set all execute bits.
  • s — (*nix only) (un)set all special (SetUID, SetGID, Sticky) bits.
  • e — (*nix only) (un)set recursion (for directories only).

Possible item states:

  • * — checked flag.
  • X — selected files have an inconsistent value of this flag.
  • d (*nix only) — (only for execute flags) means u-x+X, g-x+X or o-x+X argument for the chmod program. If you're not on OS X and want to remove the execute permission bit from all files, but preserve it for directories, set all execute flags to 'd' and check the 'Set Recursively' flag. 💅

Fileinfo (Ctrl+G) dialog

  • Enter, q — close the dialog.

Sort (:sort) dialog

  • h, Space — switch ascending/descending order. 🔃
  • q — close the dialog.

There's also a shortcut per sorting key (it's drawn right on the dialog). ✨

Okay so bestie, menus get used all the time to show you results of stuff — finding files, grepping, all that. And once you close one? Poof. Gone. Sure, you could recreate it by re-running the command, but that's lowkey a nightmare: you might have to change directory first, then remember the command, then find your spot in the menu again. It's giving unpaid labor. 😭

So vifm keeps up to 25 of the last such menus, and gives you a familiar little set of Vim commands to recall them. Iconic.

Now, as hinted above, this doesn't apply to every menu. Things like :version or :commands lean purely on internal data and don't need saving. Only menus that come from external sources and support navigation (like via gf) get remembered. 👑

To re-open the last viewed menu of the relevant type, run :copen. Once it's open, :colder takes you to older menus and :cnewer takes you to newer ones.

Close a menu after roaming through the history? It remembers your position, so running :copen again opens the last viewed menu and lets you keep exploring in both directions. 🦋

The history is always sorted oldest → newest. Once you open more than 25 menus, the oldest one is likely to be forgotten — but it's not guaranteed, because viewing an older menu makes your new entry replace all the more recent ones. Example time, assume the history looks like this:

1. :find 1
2. :find 2
...
23. :find 23 (current element)
24. :find 24
25. :find 25

Running :find 11 results in:

1. :find 1
2. :find 2
...
23. :find 23
24. :find 26 (current element)
25. None

For convenience, :colder and :cnewer work any time you're in a menu, not just after :copen. :cnewer only works if the current menu can't be saved and you've moved back in the menus history before. And :colder be like:

  • if the current menu can be stashed, it behaves as a :quit, :copen, :colder sequence (the current menu gets stashed the same way as described above);
  • if the current menu can't be stashed, it behaves as a :quit, :copen sequence.

Viewing history

Rather than brute-force enumerating menus hunting for the right one, you can use :chistory to get an overview of saved menus, maybe search for one, and then open it. And yes — the command is also available in menu mode. 💅

Commands: :chistory, :copen Menu commands: :chistory, :colder, :cnewer

🧚 Custom views

Definition

Normally file views show you a list of files from one single directory. But sometimes it's genuinely useful to fill them with files from totally unrelated places. That is mainly what custom views are for, periodt.

Presentation

Custom views are still tied to the directory they were in before the custom list was loaded. That directory (the original directory) shows up in the title of the custom view.

Files in the same directory have to be named differently, but custom views are free from that constraint — which means seeing bare file names could get pretty confusing. So, to hint where files came from, paths relative to the original directory of the view are used; when that's not possible, full paths get shown.

Custom views normally don't contain any inexistent files. ✨

Navigating custom views is a bit different from regular views:

  • gf - acts like gf on symbolic links and navigates to the file at its real location.
  • h - goes to the closest parent node in the tree view, or terminates the custom view and returns you to the original directory.
  • gh - terminates the custom view and returns you to the original directory.

Going to the parent directory in other ways (whether by opening the .. entry or running :cd ..) also causes termination and a return to the original location.

All other ways of changing location (e.g., marks, bookmarks, :cd, :sync) also cause termination of the custom view.

History

A custom list exists only while it's visible. Once you leave it, you can't come back, so there are no traces of it in any history. 💀

Filters

Only the local filter affects the contents of the view. This is intentional. Presumably if you load a particular list, precisely that list should be displayed (except for inexistent paths, which get ignored).

Even though directory names are visible in the listing, they are not searchable. Only file names are taken into account (this might change in the future — searching whole lines seems quite reasonable).

Sorting

Contrary to search, sorting by name works on the whole visible part of the file path.

Highlight

The whole file name is highlighted as one entity, even if there are directory elements in it.

Updates

Reloads can happen, though they're not automatic since files are scattered across different places. On a reload, inexistent files are removed and meta-data of all other files is updated.

Once a custom view forgets about a file, it won't add it back even if it's created again. So not seeing a file that was previously affected by an operation which was later undone? Completely normal, bestie.

Operations

All operations that add files are forbidden for custom views. For example, moving/copying/putting files into a custom view doesn't work, because that's not a real file system location. 🚫

On the other hand, operations that use files of a custom view as a source (e.g., yanking, copying, moving a file from a custom view, deletion) and operations that modify names are all allowed. Slay.

🌈 Compare views

Kinds

:compare can produce four different results depending on its arguments:

  • single compare view (ofone and either listall or listdups);
  • single custom view (ofone and listunique);
  • two compare views (ofboth and either listall or listdups);
  • two custom views (ofboth and listunique).

The first two display files of a single file system tree. Here, duplicates are files that have at least one copy in the same tree. The other two kinds compare two trees, in which duplicates are files found in both trees.

Lists of unique files are presented in custom views because there's no file grouping to preserve — all file ids are guaranteed to be distinct. See the "Custom views" section.

Creation

Arguments passed to :compare form seven categories, each with its own prefix, and each one is responsible for a particular property of the operation.

Which files to compare:

  • ofboth - compares files of two panes against each other;
  • ofone - compares files of the same directory.

How files are compared:

  • byname - by their name only;
  • bysize - only by their size;
  • bycontents - by the data they contain (a combination of size and a hash of a small chunk of contents is used as a first approximation, so don't worry too much about large files; non-regular files like pipes are assumed to be empty).

Which files to display:

  • listall - all files;
  • listunique - unique files only;
  • listdups - only duplicated files.

How results are grouped (has no effect if ofone is specified):

  • groupids - files considered identical are always adjacent in output;
  • grouppaths - file system ordering is preferred (this also enables displaying identically named files as mismatches).

Which files to omit:

  • skipempty - ignore empty files.

Comparison tweaks:

  • withicase - ignore case when comparing file names/paths;
  • withrcase - respect case when comparing file names/paths.

Which results to show (has no effect for single pane comparison):

  • showidentical - control visibility of identical files;
  • showdifferent - control visibility of changed files;
  • showuniqueleft - control visibility of unique top/left files;
  • showuniqueright - control visibility of unique bottom/right files.

Each argument can appear multiple times — the rightmost one of the group defines the behaviour. And all arguments alter default behaviour instead of substituting it.

When neither withicase nor withrcase is specified, case depends on the running operating system and the file system on which the files are located.

Exiting

Comparing two views results in them entering a special state implemented on top of custom views. Both views leave this state when either of them stops being custom. Custom views terminate on changing to a different location — or as a result of a command like :regular — and going into the parent directory (like with the h key or the :cd .. command) returns to a regular state without changing the location. See the "Custom views" section for more details.

Examples

The defaults correspond to probably the most common use case — comparing files in two trees with grouping by paths — so the following are all equivalent:

:compare
:compare bycontents grouppaths
:compare bycontents listall ofboth grouppaths
:compare showidentical showdifferent showuniqueleft showuniqueright

Another use case is finding duplicates in the current sub-tree:

:compare listdups ofone

The following command lists files that are unique to each pane:

:compare listunique

Look

The view can't switch to ls-like view, because it's unable to display diff-like data. 🙈

Comparison views have a second column displaying the id of the file — files with the same id are considered equal. The view columns configuration is predefined.

The status bar displays only the initial result of the comparison and can be out of date.

Behaviour

When two views are being compared against one another, these changes to regular behaviour apply:

  • views are scrolled synchronously (as if 'scrollbind' was set);
  • views' cursors are synchronized;
  • local filtering is disabled (its results wouldn't be meaningful);
  • zd excludes groups of adjacent identical files, 1zd gives usual behaviour;
  • sorting is permanently disabled (ordering is fixed);
  • removed files hide their counter pairs;
  • exiting one of the views terminates the other immediately;
  • renaming files isn't blocked, but isn't taken into account and might require regeneration of the comparison;
  • entries which indicate absence of an equivalent file have empty names and can be matched as such;
  • when unique files of both views are listed, custom views can be empty — this absence of unique files is stated clearly.

One compare view has similar properties (those that are applicable for a single pane).

Files are gathered in this way:

  • recursively, starting at the current location of the view;
  • dot files are excluded if the view hides them at the moment of comparison, and file name filters are obeyed as well — so you end up comparing what you see;
  • directories are not taken into account;
  • symbolic links to directories are ignored.

✨ Startup ✨

okay so when vifm boots up it figures out a bunch of variables it's gonna use for the rest of its little life, and the order matters — they get determined in exactly the order they're listed below, bestie.

On *nix systems $HOME is normally just there and vifm uses it as-is, no drama. On Windows though, vifm has to go hunting for the correct home directory, and it checks in this order:

  • $HOME variable;
  • $USERPROFILE variable (on Windows only);
  • a combination of $HOMEDRIVE and $HOMEPATH variables (on Windows only).

Then it goes looking for the correct configuration directory, checking these spots:

  • $VIFM variable;
  • parent directory of the executable file (on Windows only);
  • $HOME/.vifm directory;
  • $APPDATA/Vifm directory (on Windows only);
  • $XDG_CONFIG_HOME/vifm directory;
  • $HOME/.config/vifm directory.

And finally the correct configuration file, hunted down like this:

  • $MYVIFMRC variable;
  • vifmrc in parent directory of the executable file (on Windows only);
  • $VIFM/vifmrc file.

🎀 Configure 🎀

peep the Startup section above for the whole explanation on $VIFM and $MYVIFMRC, iykyk.

The vifmrc file is where you stash commands that run on vifm startup. There are two of them: a global one and a local one. The global one lives at {prefix}/etc/vifm/vifmrc — and for how the local one gets found, go read the $MYVIFMRC variable description for the search algorithm. Global vifmrc loads before the local one, so the local one can redefine literally anything that was configured globally. slay.

Use vifmrc to set settings, mappings, filetypes etc. And if you wanna use multi line commands, precede each next line with a slash — whitespace before the slash gets ignored, but all spaces at the end of the lines are saved. For example:

set
    \smartcase

equals setsmartcase. But when it's:

set<space here>
    \ smartcase

it equals set smartcase. see the difference? iconic.

The $VIFM/vifminfo file holds the generic state of the application. You control what gets stored in it with the 'vifminfo' option. Vifm always writes this file on exit unless 'vifminfo' option is empty. Marks, bookmarks, commands, histories, filetypes, fileviewers and registers in the file are merged with vifm configuration (which has bigger priority).

Generally, runtime configuration has bigger priority during merging — but bestie, there are some exceptions and you need to know them:

  • directory stack stored in the file is not overwritten unless something is changed in vifm instance that performs merge;
  • each mark or bookmark is marked with a timestamp, so that newer value is not overwritten by older one, thus no matter from where it comes, the newer one wins;
  • all histories are marked with timestamps on storing, this means that last instance to quit puts its elements on top of the list;
  • tabs are merged only if both current instance and stored state contain exactly one tab of any kind.

The $VIFM/scripts directory can contain shell scripts. vifm modifies its PATH environment variable to let you run those scripts without specifying the full path. All subdirectories of the $VIFM/scripts will be added to PATH too. And a script in a subdirectory overlaps a script with the same name in all its parent directories. periodt.

The $VIFM/colors/ and {prefix}/etc/vifm/colors/ directories are where color schemes live. Available color schemes are searched in that order, so on a name conflict the one in $VIFM/colors/ wins. 💅

Each color scheme should have a ".vifm" extension. This wasn't the case before, and for that reason these rules apply during lookup:

  • if there is no file with .vifm extension, all regular files are listed;
  • otherwise only files with .vifm extension are listed (with the extension being truncated).

🌈 Sessions 🌈

Sessions are the way to have multiple persistent runtime configurations. Think of them as second-level vifminfo files sitting on top of the first-level one that every session uses. So no — they are not a replacement for the vifminfo file that exists without sessions, they're an addition to it.

You could empty the 'vifminfo' option and rely solely on sessions, but realistically you might wanna share some state among instances in different sessions, or keep an "out-of-sessions" state for tasks that genuinely don't deserve a session of their own. fair.

This gives you a two-level structure where data in session files has higher priority than data in vifminfo files (where that makes sense), following the same rules that merging of vifminfo file obeys. On top of that, history items from session files are never ordered before history items from the vifminfo file.

Format

Sessions have the format of vifminfo files — they do not consist of a sequence of command-line commands and are not meant to be sourced via :source command. do not try it bestie.

Storage and naming

$VIFM/sessions/ directory serves as the storage for sessions. Consequently names should be valid filenames. The structure of the storage is flat, meaning there are no subdirectories, and that's why names of sessions can't contain slashes. 🚫

Usage model

Contrary to Vim, vifm automates the basic management of sessions. You can start, switch, stop or delete a session using builtin means.

Current session is saved at the same time vifminfo is saved (on normal exits or explicitly on :write command) and right before switching to another session. To avoid saving in those cases, use :session command to detach (without saving) from a session before proceeding.

  • Commands: :session, :delsession
  • Options: 'sessionoptions'
  • Variables: v:session

🔥 Automatic FUSE mounts 🔥

vifm has builtin support for automated FUSE file system mounts — and it's implemented using the file associations mechanism, which is lowkey genius. To enable automated mounts you need a specially formatted program line in filetype or filextype commands. These use special macros, which are different from the macros in commands unrelated to FUSE. Currently three formats are supported:

  1. FUSE_MOUNT — use this one when all the information needed for mounting all files of a particular type is the same. E.g. mounting of tar files doesn't require any file specific options.

Format line:

FUSE_MOUNT|mounter %SOURCE_FILE %DESTINATION_DIR [%FOREGROUND]

Example filetype command:

:filetype FUSE_MOUNT|fuse-zip %SOURCE_FILE %DESTINATION_DIR
  1. FUSE_MOUNT2 — this one lets you use specially formatted files to perform mounting, and it's super useful for mounting remotes, like remote file systems over ftp or ssh.

Format line:

FUSE_MOUNT2|mounter %PARAM %DESTINATION_DIR [%FOREGROUND]

Example filetype command:

:filetype *.ssh FUSE_MOUNT2|sshfs %PARAM %DESTINATION_DIR

Example file content:

root@127.0.0.1:/
  1. FUSE_MOUNT3

This format is equivalent to FUSE_MOUNT, but omits unmounting. It's useful for cases when unmounting isn't needed, like when using AVFS.

Example :filetype command:

:filetype *.tar,*.tar.bz2,*.tbz2,*.tgz,*.tar.gz,*.tar.xz,*.txz,*.deb
     \ {Mount with avfs}
     \ FUSE_MOUNT3|mount-avfs %DESTINATION_DIR %SOURCE_FILE

Example mount-avfs helper script:

#!/bin/sh

dest=$1
file=$2

rmdir "$dest"
ln -s "$HOME/.avfs$file#/" "$dest"

All % macros are expanded by vifm at runtime, and here's what each one actually means:

  • %SOURCE_FILE is replaced by full path to selected file;
  • %DESTINATION_DIR is replaced by full path to mount directory, which is created by vifm basing on the value of 'fusehome' option;
  • %PARAM value is filled from the first line of file (whole line), though in the future it can be changed to whole file content;
  • %FOREGROUND means that you want to run mount command as a regular command (required to be able to provide input for communication with mounter in interactive way).

%FOREGROUND is an optional macro. Other macros are not mandatory, but mount commands likely won't work without them. 🙈

%CLEAR is the obsolete name of %FOREGROUND, which is still supported, but might be removed in future. Its use is discouraged — so like, don't. 🚫

Unlike macros elsewhere, these are recognized only if they appear at the end of a command or are followed by a space. There is no way to escape % either. These are historical limitations, which might be addressed in the future. not me finding out the hard way 😭

The mounted FUSE file systems will be automatically unmounted in two cases:

  • when vifm quits (with ZZ, :q, etc. or when killed by signal);
  • when you explicitly leave mount point going up to its parent directory (with h, Enter on "../" or ":cd ..") and other pane is not in the same directory or its child directories.

🦋 View look 🦋

vifm supports displaying the file list view in two different ways:

  • in a table mode, when multiple columns can be set using 'viewcolumns' option (see "Column view" section below for details);
  • in a multicolumn list manner which looks almost like ls -x command output (see "ls-like view" section below for details).

The look is local for each view and can be chosen by changing the value of the 'lsview' boolean option.

Depending on view look some of the keys change their meaning to allow more natural cursor moving — this concerns mainly h, j, k, l and other similar navigation keys. 👑

Also some of the options can be ignored if they don't affect view displaying in the selected look. For example the value of 'viewcolumns' when 'lsview' is set.

💜 ls-like view 💜

When this view look is enabled by setting 'lsview' option on, vifm will display files in multiple columns. Number of columns depends on the length of the longest file name present in the current directory of the view. And the whole file list is automatically reflowed on directory change, terminal or view resize. no manual refreshing needed bestie.

The view looks close to the output of ls -x command, so files are listed left to right in rows.

In this mode file manipulation commands (e.g. d) don't work line-wise like they do in Vim, since such operations would be uncommon for file manipulation tasks. So for example dd will remove only the current file.

By default the view is filled by lines, 'lsoptions' can be used to get filling by columns.

Note that tree-view and compare view inhibit ls-like view. 💀

🌈 Column view 🌈

Okay bestie, this is where you get to design your very own view columns, and honestly it's giving interior design but for file lists 💅

View columns are described by a comma-separated list of column descriptions, and each one looks like this:

[ '-' | '*' ] [ fw ( [ '.' tw ] | '%' ) ] '{' type | literal '}'
'.'{0,3}

Quick legend so you're not lost: fw = full width, tw = text width, the bar is the logical or, square brackets mean the part is optional, and curly braces define how many times you can repeat the symbol right before them.

So it's basically four parts, in order:

  1. Optional alignment specifier
  2. Optional width specifier
  3. Mandatory column name
  4. Optional cropping specifier

✨ Alignment specifier ✨

It's an optional minus or asterisk sign as the first symbol of the string.

This sets what kind of text alignment happens inside the column. "Three types are supported" the page says, and then it lists four, and honestly? slay, we love a generous list 💖 Here they all are:

  • left align
set viewcolumns=-{name}
  • right align (default)
set viewcolumns={name}
  • middle align

Same energy as left alignment, but the moment the text is bigger than the column it gets cut in the middle — so the start AND the end of the field are always visible, no cap.

set viewcolumns=^{name}
  • dynamic align

Again like left alignment, but when the text outgrows the column, the alignment shifts to the right, so part of the field is always visible.

set viewcolumns=*{name}

🌸 Width specifier 🌸

This one is a number followed by a percent sign, or two numbers (and the second one has to be less than or equal to the first) separated with a dot, or just a single number.

It sets the column width and its units. There are three size types:

  • absolute size — the column width is in characters:
set viewcolumns=-100{name},20.15{ext}

which gives you two columns of lengths 100 and 20, plus a reserved space of five characters on the left of the second column.

  • relative (percent) size — the column width is a percent of the view width:
set viewcolumns=-80%{name},15%{ext},5%{mtime}

which gives you three columns of 80/100, 15/100 and 5/100 of the view width.

  • auto size (default) — the column width is figured out automatically:
set viewcolumns=-{name},{ext},{mtime}

which gives you three columns, each one third of the view width. Heads up tho: there is no size adjustment to content here, since that would slow down rendering.

You can freely mix columns of different sizing types in one view 🫶 Though sometimes some columns will only be partly visible, or completely invisible, if there just isn't enough space to display them.

🦋 Column contents 🦋

Usually this is a sorting key wrapped in curly braces, like:

{name},{ext},{mtime}

And just so you know, {name} and {iname} are literally the same type — both exist for consistency with the 'sort' option.

These column types don't have matching sorting keys:

  • {root} — display name without extension (a complement for {ext})
  • {fileroot} — display name without extension for anything that isn't a directory or a symbolic link to a directory (a complement for {fileext})

Empty curly braces ({}) get replaced with the default secondary column for the primary sort key. So after this command, the view displays almost as if 'viewcolumns' was empty, except it adds ellipsis for long file names:

set viewcolumns=-{name}..,6{}.

The last kind of column value is a string literal. That literal is used as the column value for every single row. The syntax is "{#literal}", and here are the examples:

" double-character pseudo-padding on both sides
set viewcolumns='2{#},*{name}..,{},2{#}'
" pseudo-border between columns
set viewcolumns='*{name}..,{#|},6{}'
" pseudo-border with padding between columns
set viewcolumns='*{name}..,{# | },6{}'

So you can draw column separators with these, iconic. Just mind that for convenience, literals have different defaults: truncation and automatically determined absolute size — which is what you usually want for them. And please make sure to quote or escape spaces, vertical bars and other special symbols when you use them as part of literals 🙈

🎀 Cropping specifier 🎀

This is anywhere from one to three dots after the closing curly brace in a column format.

It sets the type of text truncation for when the text doesn't fit in the column. There are three types:

  • truncation — text is truncated:
set viewcolumns=-{name}.

which results in names that are too long to fit in the view getting cut off.

  • adding of ellipsis — ellipsis on the left or right gets added when it's needed:
set viewcolumns=-{name}..

which means ellipsis are added at the end of file names that are too long.

  • none (default) — text can just pass right on through the column boundaries:
set viewcolumns=-{name}...,{ext}

which means long file names can partially be written on the ext column. Bold, honestly 💀

💜 Color schemes 💜

The color schemes in vifm can be applied in two different ways:

  • as the primary color scheme;
  • as local to a pane color scheme.

Both types are set using the :colorscheme command, just in different forms:

  • :colorscheme color_scheme_name — for the primary color scheme;
  • :colorscheme color_scheme_name directory — for local color schemes.

The look of different parts of the TUI (Text User Interface) gets decided like this:

  • Border, TabLine, TabLineSel, TopLineSel, TopLine, CmdLine, ErrorMsg, StatusLine, JobLine, SuggestBox, WildBox and WildMenu are always determined by the primary color scheme;
  • CurrLine, Selected, Directory, Link, BrokenLink, Socket, Device, Executable, Fifo, CmpMismatch, CmpUnmatched, CmpBlank, Win, AuxWin and OtherWin are determined by the primary color scheme and a set of local color schemes, which can totally be empty.

There might be a whole set of local color schemes because they're structured hierarchically, following the file system structure. So say you have this little slice of file system:

~
`-- bin
   |
   `-- my

And two color schemes:

# ~/.config/vifm/colors/for_bin.vifm
highlight Win cterm=none ctermfg=white ctermbg=red
highlight CurrLine cterm=none ctermfg=red ctermbg=black

# ~/.config/vifm/colors/for_bin_my.vifm
highlight CurrLine cterm=none ctermfg=green ctermbg=black

And these three commands in the vifmrc file:

colorscheme Default
colorscheme for_bin ~/bin
colorscheme for_bin_my ~/bin/my

Then the file list looks like this at each level:

  • ~/ — Default color scheme
    • black background
    • cursor with blue background
  • ~/bin/ — mix of Default and for_bin color schemes
    • red background
    • cursor with black background and red foreground
  • ~/bin/my/ — mix of Default, for_bin and for_bin_my color schemes
    • red background
    • cursor with black background and green foreground

Layered looks, we love a gradient moment 🌈

🗑️ Trash directory 🗑️

vifm has support of a trash directory, which it uses as temporary storage for deleted files or files that were cut. Whether trash gets used is controlled by the 'trash' option, and the exact path to the trash can be set with the 'trashdir' option. The trash directory in vifm differs from the system-wide one by default, because of possible incompatibilities of storing deleted files among different file managers. But you can set 'trashdir' to "~/.local/share/Trash" to use a "standard" trash directory.

There are two scenarios of using trash in vifm:

  1. As a place for storing files that were cut by "d" and may be inserted to some other place in the file system.
  2. As a storage of files that are deleted but not purged yet.

The first scenario uses deletion ("d") operations to put files to trash, and put ("p") operations to restore files from the trash directory. Note that these operations move files to and from the trash directory, which can be long term operations in case of different partitions or remote drives mounted locally. So maybe grab a snack 🍓

The second scenario uses deletion ("d") operations for moving files to the trash directory, and the :empty command-line command to purge all previously deleted files.

Deletion and put operations depend on registers, which can point to files in the trash directory. Normally there are no nonexistent files in registers, but vifm doesn't keep track of modifications under the trash directory, so one shouldn't expect the value of registers to be absolutely correct if the trash directory was modified by something that isn't an operation meant for it. But this won't lead to any issues with operations, since they ignore nonexistent files. Crisis averted 💅

💥 Name conflicts 💥

When copying, moving, or creating symbolic links, Vifm can encounter a name conflict: a file with the same name already exists in the target directory. In such cases Vifm shows a dialog asking how to resolve the conflict.

Here's what you can pick:

  • overwrite — replace the existing file with the incoming one.
  • overwrite all — apply the overwrite action to all further conflicts during the same operation without asking again.
  • skip — do not copy or move the file that caused the conflict.
  • skip all — skip all further conflicting files without prompting.
  • rename — enter a new name for the incoming file. Pressing Enter without typing a new name keeps the old name and causes the dialog to appear again.
  • merge — for directories: copy only missing files from the source directory into the existing one.
  • merge all — apply the merge action to all further directory conflicts.
  • append — if the destination file is shorter, append the missing tail bytes from the source file. Example: if the source is 1000 bytes and the destination is 300 bytes in size, the last 700 bytes of the source are appended. This action is intended for resuming interrupted copy operations.

Notes, bestie, don't skip these:

  • The conflict dialog appears for :put, p, P, al and rl commands.
  • Conflict resolution choices apply only to the current operation.

📁 File copying 📁

For enabling copy-on-write of BTRFS on Linux, set "fastfilecloning" flag of 'iooptions' option.

File copying within an XFS file system uses reflinks by default. Any file copied from another file system will be copied without reflinks even if it has a matching list of XFS extents. Reflinks are not guaranteed when using external programs. This behaviour was observed on Linux and doesn't necessarily hold for other environments. So like, don't @ me if your filesystem plays different 💀

🛰️ Client-Server 🛰️

okay bestie, this is the ✨remote control✨ era and it's literally so good. vifm can run command-line mode commands remotely, change directories remotely, and even do expression evaluation remotely. The way it pulls this off? --remote and --remote-expr command-line arguments. iykyk 💅

To run a command remotely, you just pair --remote with -c <command> or +<command>. Like so:

vifm --remote -c 'cd /'
vifm --remote '+cd /'

And if you wanna change directory without going through command-line mode commands at all, just throw paths right after the --remote argument, bestie:

vifm --remote /
vifm --remote ~
vifm --remote /usr/bin /tmp

Evaluating an expression remotely? That's your girl for querying info about a running instance, like, say, where it's at:

vifm --remote-expr 'expand("%d")'

Now — plot twist — if you've got multiple instances running, you point at your target with the --server-name option (otherwise the first one lexicographically gets picked, kinda random ngl):

vifm --server-name work --remote ~/work/project

Wanna know the names of all your running instances? --server-list option, boom. And the name of the current one lives in v:servername. 💖

  • v:servername — the server name of the running vifm instance. It's empty if the client-server feature is disabled. 🙈

🔄 External Renaming 🔄

so when you run an editor to edit a list of file names, the contents of that temporary file follow this exact format:

  1. The order of lines corresponds to the order of files in a view.
  2. Lines that start with a # are comments and are ignored.
  3. A single backslash at the beginning of a line is ignored, so that a file starting with a backslash will appear like "\#name".

And if an operation got rejected because of issues with the file names, next time you'll see the following, in this order:

  1. Last error (in comments).
  2. Original file names (in comments).
  3. Failed list of new names.

Mind that the Vim plugin will extract the list of original names and show them in a vertical split, 💅 cute of it.

You can cancel renaming by removing all non-comments from the buffer. This also erases information about previous edits, so be aware bestie.

🖱️ Using mouse 🖱️

Note: <ScrollWheelDown> is not available on 32-bit *nix systems, because ncurses doesn't support it there (limitation of implementation). 😭
Note: these are not available in mappings at the moment.

Normal Mode

  • <LeftMouse> — position cursor: yes · change window: yes · action: <cr> if cursor wasn't move
  • <LeftRelease> — position cursor: no · change window: yes
  • <MiddleMouse> — position cursor: no · change window: yes · action: <c-e>
  • <MiddleRelease> — position cursor: no · change window: yes
  • <RightMouse> — position cursor: yes · change window: yes · action: :file
  • <RightRelease> — position cursor: no · change window: yes
  • <ScrollWheelUp> — position cursor: no · change window: yes · action: <c-y> or :tabprevious
  • <ScrollWheelDown> — position cursor: no · change window: yes · action: <c-e> or :tabnext

Clicking on or scrolling over an inactive pane (including its title) makes it active and does nothing else. 🌸 Tabs are scrolled when the mouse hovers over them.

Clicking on the left miller column goes to parent directory and clicking the right one opens current entry. the way that works is so satisfying honestly.

Visual Mode

  • <LeftMouse> — position cursor: yes · selection: update · action: <cr> if cursor wasn't move
  • <LeftRelease> — position cursor: no
  • <MiddleMouse> — position cursor: no · selection: update · action: <c-e>
  • <MiddleRelease> — position cursor: no
  • <RightMouse> — position cursor: no
  • <RightRelease> — position cursor: no
  • <ScrollWheelUp> — position cursor: no · selection: update · action: <c-y>
  • <ScrollWheelDown> — position cursor: no · selection: update · action: <c-e>

Command-line Mode

  • <LeftMouse> — position cursor: yes
  • <LeftRelease> — position cursor: no
  • <MiddleMouse> — position cursor: no · action: <c-n>
  • <MiddleRelease> — position cursor: no
  • <RightMouse> — position cursor: no
  • <RightRelease> — position cursor: no
  • <ScrollWheelUp> — position cursor: no · action: <c-p>
  • <ScrollWheelDown> — position cursor: no · action: <c-n>
  • <LeftMouse> — position cursor: yes · action: <cr> if cursor wasn't moved
  • <LeftRelease> — position cursor: no
  • <MiddleMouse> — position cursor: no · action: <c-e>
  • <MiddleRelease> — position cursor: no
  • <RightMouse> — position cursor: no
  • <RightRelease> — position cursor: no
  • <ScrollWheelUp> — position cursor: no · action: <c-y>
  • <ScrollWheelDown> — position cursor: no · action: <c-e>

view Mode

  • <ScrollWheelUp> — action: k
  • <ScrollWheelDown> — action: j

Clicking on or scrolling over an inactive pane (including its title), detaches view mode if it wasn't activated for exploring a file. periodt. ✨

🧩 Plugin 🧩

This is the plugin for using vifm inside vim as a file selector. iconic honestly.

Commands:

  • :EditVifm — select a file or files to open in the current buffer.
  • :Vifm — alias for :EditVifm.
  • :SplitVifm — split buffer and select a file or files to open.
  • :VsplitVifm — vertically split buffer and select a file or files to open.
  • :DiffVifm — select a file or files to compare to the current file with :vert diffsplit.
  • :TabVifm — select a file or files to open in tabs.

Each command accepts up to two arguments: left pane directory and right pane directory. 🫶 After the arguments are checked, a vifm process is spawned in a special "file-picker" mode. To pick files just open them either by pressing l, i or Enter keys, or by running :edit command. If no files are selected, the file under the cursor is opened; otherwise the whole selection is passed to the plugin and opened in vim. slay. 🔥

The plugin have only two settings. It's a string variable named g:vifm_term to let user specify command to run GUI terminal. By default it's equal to 'xterm -e'. And another string variable named g:vifm_exec, which equals "vifm" by default and specifies path to vifm's executable. To pass arguments to vifm use g:vifm_exec_args, which is empty by default. 👑

To use the plugin copy the vifm.vim file to either the system wide vim/plugin directory or into ~/.vim/plugin.

If you would prefer not to use the plugin and it is in the system wide plugin directory, add

let loaded_vifm=1

to your ~/.vimrc file. 🌈

📇 Index of menus 📇

Mappings

  • :amap, :anoremap — mappings in navigation mode
  • :cmap, :cnoremap — mappings in command-line mode
  • :dmap, :dnoremap — mappings in dialog mode
  • :mmap, :mnoremap — mappings in menu mode
  • :nmap, :nnoremap — mappings in normal mode
  • :qmap, :qnoremap — mappings in view mode
  • :vmap, :vnoremap — mappings in visual mode

Expansions of command-line mode

  • :cabbrev, :cnoreabbrev — command-line abbreviations
  • :command — user commands

Program associations

  • :file — programs set for the file type
  • :filetype — program associations for a file
  • :fileviewer — viewer associations for a file
  • :filextype — graphical program associations for a file

External commands

  • :apropos — results of running 'aproposprg'
  • :find — results of running 'findprg'
  • :grep — results of running 'grepprg'
  • :locate — results of running 'locateprg'

Marks and bookmarks

  • :bmarks — bookmarks (tag-like marks)
  • :marks — marks

History-like

  • :chistory — history of navigation menus
  • :dirs — directory stack
  • :history — histories of views and prompts
  • :undolist — undo/redo history

Trash directories and their contents

  • :lstrash — files in trash directories
  • :trashes — usable non-empty trash directories

Drives and volumes

  • :media — media management
  • :volumes — volume list

Other internal state

  • :colorscheme — color schemes
  • :display, :registers — contents of registers
  • :jobs — current jobs and background processes
  • :plugins — plugins
  • :version, :vifm — version and runtime information

Macros that create menus

  • %m — captured output of a command
  • %M — same as %m, but with navigation to files

🚫 Reserved 🚫

The following command names are reserved and shouldn't be used for user commands. like, hands off bestie 💀

g[lobal]
v[global]

🌍 ENVIRONMENT 🌍

  • VIFM — Points to main configuration directory (usually ~/.config/vifm/).
  • MYVIFMRC — Points to main configuration file (usually ~/.config/vifm/vifmrc).

These environment variables are valid inside vifm and also can be used to configure it by setting some of them before running vifm. ✨

When $MYVIFMRC isn't set, it's made as $VIFM/vifmrc (exception for Windows: vifmrc in the same directory as vifm.exe has higher priority than $VIFM/vifmrc).

See "Startup" section above for more details. 👀

  • VIFM_FUSE_FILE — On execution of external commands this variable is set to the full path of file used to initiate FUSE mount of the closest mount point from current pane's directory up. It's not set when outside FUSE mount point. When vifm is used inside terminal multiplexer, it tries to set this variable as well (it doesn't work this way on its own).

👀 SEE ALSO 👀

✍️ AUTHOR ✍️

Vifm was originally created by ksteen <ksteen@users.sourceforge.net> It is currently developed by xaizek <xaizek@posteo.net>

aaaand that's a wrap on the whole page bestie!! 🎀 this is vifm 0.14.4, dated 31 May 2026, and the page itself is VIFM(1) — go forth and slay your file management, you absolute main character. 💖🦋✨

📦 where this page comes from