gemini - kennedy.gemi.dev

💾 Archived View for mkl-wlod.srht.site › repo › tree › vifm › .config › vifm › vifm-help.txt.txt captured on 2022-03-01 at 15:59:28. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

VIFM(1) General Commands Manual VIFM(1)

NAME

vifm - vi file manager

SYNOPSIS

vifm [OPTION]...

vifm [OPTION]... path

vifm [OPTION]... path path

DESCRIPTION

Vifm is an ncurses based file manager with vi like keybindings. If you

use vi, vifm gives you complete keyboard control over your files with-

out having to learn a new set of commands.

OPTIONS

vifm starts in the current directory unless it is given a different di-

rectory on the command line or 'vifminfo' option includes "savedirs"

(in which case last visited directories are used as defaults).

- Read list of files from standard input stream and compose custom

view out of them (see "Custom views" section). Current working

directory is used as a base for relative paths.

<path> Starts Vifm in the specified path.

Starts Vifm in the specified paths.

Specifying two directories triggers split view even when vifm was in

single-view mode on finishing previous run. To suppress this behaviour

:only command can be put in the vifmrc file.

When only one path argument is found on command-line, the left/top pane

is automatically set as the current view.

Paths to files are also allowed in case you want vifm to start with

some archive opened.

--select <path>

Open parent directory of the given path and select specified

file in it.

-f Makes vifm instead of opening files write selection to

$VIFM/vimfiles and quit.

--choose-files <path>|-

Sets output file to write selection into on exit instead of

opening files. "-" means standard output. Use empty value to

disable it.

--choose-dir <path>|-

Sets output file to write last visited directory into on exit.

"-" means standard output. Use empty value to disable it.

--delimiter <delimiter>

Sets separator for list of file paths written out by vifm.

Empty value means null character. Default is new line charac-

ter.

--on-choose <command>

Sets command to be executed on selected files instead of opening

them. The command may use any of macros described in "Command

macros" section below. The command is executed once for whole

selection.

--logging[=<startup log path>]

Log some operational details $VIFM/log. If the optional startup

log path is specified and permissions allow to open it for writ-

ing, then logging of early initialization (before value of $VIFM

is determined) is put there.

--server-list

List available server names and exit.

--server-name <name>

Name of target or this instance (sequential numbers are appended

on 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,

quits silently. There is no limit on how many arguments can be

processed. One can combine --remote with -c <command> or +<com-

mand> to execute commands in already running instance of vifm.

Directory

Link

BrokenLink

HardLink

Socket

Device

Fifo

Executable

Selected

CurrLine

LineNr (in active pane)

OtherLine

LineNr (in inactive pane)

TopLine

TopLineSel

TabLineSel (for pane tabs)

User1..User9

TabLine

TabLineSel

User1..User9

"none" means default terminal color for highlight groups at the first

level of the hierarchy and transparency for all others.

Here file name specific highlights mean those configured via globs ({})

or regular expressions (//). At most one of them is applied per file

entry, namely the first that matches file name, hence order of :high-

light commands might be important in certain cases.

:history

:his[tory]

display a menu with list of visited directories. See "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 l

key.

f[search] or / show search history and search forward on l

key.

b[search] or ? show search history and search backward on l

key.

i[nput] or @ show prompt history (e.g. on one file renam-

ing).

fi[lter] or = show filter history (see description of the "="

normal mode command).

See "Menus and dialogs" section for controls.

:histnext

same as <c-i>. The main use case for this command is to work

around the common pain point of <tab> and <c-i> being the same

ASCII character: one could alter the terminal emulator settings

to emit, for example, the `F1` keycode when Ctrl-I is pressed,

then `:noremap <f1> :histnext<cr>` in vifm, add "t" flag to the

'cpoptions', and thus have both <c-i> and <tab> working as ex-

pected.

:histprev

same as <c-o>.

:if

:if {expr1}

start conditional block. Commands are executed until next

matching :elseif, :else or :endif command if {expr1} evaluates

to non-zero, otherwise they are ignored. See also help on :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

:invert [f]

invert file name filter.

:invert? [f]

show current filter state.

:invert s

invert selection.

:invert o

invert sorting order of the primary sorting key.

:invert? o

show sorting order of the primary sorting key.

:jobs

:jobs display menu of current backgrounded processes. See "Menus and

dialogs" section for controls.

:let

:let $ENV_VAR = <expr>

set an environment variable. Warning: setting environment vari-

able to an empty string on Windows removes it.

:let $ENV_VAR .= <expr>

append value to environment variable.

:let &[l:|g:]opt = <expr>

sets option value.

:let &[l:|g:]opt .= <expr>

append value to string option.

:let &[l:|g:]opt += <expr>

increasing option value, adding sub-values.

:let &[l:|g:]opt -= <expr>

decreasing option value, removing sub-values.

Where <expr> could be a single-quoted string, double-quoted string, an

environment variable, function call or a concatanation of any of them

in any order using the '.' operator. Any whitespace is ignored.

:locate

:locate filename

use "locate" command to create a menu of filenames. Selecting a

file from the menu will reload the current file list in vifm to

show the selected file. By default the command relies on the

external "locate" utility (it's assumed that its database is al-

ready built), which can be customized by altering value of the

'locateprg' option. See "Menus and dialogs" section for con-

trols.

:locate

repeat last :locate command.

:ls

:ls lists windows of active terminal multiplexer (only when terminal

multiplexer is used). This is achieved by issuing proper com-

mand for active terminal multiplexer, thus the list is not han-

dled by vifm.

:lstrash

display a menu with list of files in trash. Each element of the

list is original path of a deleted file, thus the list can con-

tain duplicates. See "Menus and dialogs" section for controls.

:mark

:[range]ma[rk][?] x [/full/path] [filename]

Set mark x (a-zA-Z0-9) at /full/path and filename. By default

current directory is being used. If no filename was given and

/full/path is current directory then last file in [range] is

used. Using of macros is allowed. Question mark will stop com-

mand from overwriting existing marks.

:marks

:marks create a pop-up menu of marks. See "Menus and dialogs" section

for controls.

:marks list ...

display the contents of the marks that are mentioned in list.

:media

:media only for *nix

display media management menu. See "Menus and dialogs" section

for controls. See also 'mediaprg' option.

:messages

:mes[sages]

shows previously given messages (up to 50).

:mkdir

:[line]mkdir[!] dir ...

create directories at specified paths. The [line] can be used

to pick node in a tree-view. "!" means make parent directories

as needed. Macros are expanded.

:move

:[range]m[ove][!?][ &]

move files to directory of other view. With "?" prompts for

destination file names in an editor. "!" forces overwrite.

:[range]m[ove][!] path[ &]

move files to directory specified with the path (absolute or

relative to directory of other view). "!" forces overwrite.

:[range]m[ove][!] name1 name2...[ &]

move files to directory of other view giving each next file a

corresponding name from the argument list. "!" forces over-

write.

:nohlsearch

:noh[lsearch]

clear selection in current pane.

:normal

:norm[al][!] commands

execute normal mode commands. If "!" is used, user defined map-

pings are ignored. Unfinished last command is aborted as if

<esc> or <c-c> was typed. A ":" should be completed as well.

Commands can't start with a space, so put a count of 1 (one) be-

fore it.

:only

:on[ly]

switch to a one window view.

:popd

:popd remove pane directories from stack.

:pushd

:pushd[!] /curr/dir [/other/dir]

add pane directories to stack and process arguments like :cd

command.

:pushd exchange the top two items of the directory stack.

:put

:[line]pu[t][!] [reg] [ &]

puts files from specified register (" by default) into current

directory. The [line] can be used to pick node in a tree-view.

"!" moves files "!" moves files from their original location in-

stead of copying them. During this operation no confirmation

dialogs will be shown, all checks are performed beforehand.

:pwd

:pw[d] show the present working directory.

:qall

:qa[ll][!]

exit vifm (add ! to skip saving changes and checking for active

backgrounded commands).

:quit

:q[uit][!]

if there is more than one tab, close the current one, otherwise

exit vifm (add ! to skip saving state and checking for active

backgrounded commands).

:redraw

:redr[aw]

redraw the screen immediately.

:registers

:reg[isters]

display menu with registers content.

:reg[isters] list ...

display the contents of the numbered and named registers that

are mentioned in list (for example "az to display "", "a and "z

content).

:regular

switch to regular view leaving custom view.

:rename

:[range]rename[!]

rename files using vi to edit names. ! means go recursively

through directories.

:[range]rename name1 name2...

rename each of selected files to a corresponding name.

:restart

free a lot of things (histories, commands, etc.), reread

vifminfo, vifmrc and session files and run startup commands

passed in the argument list, thus losing all unsaved changes

(e.g. recent history or keys mapped after starting this in-

stance). Session that wasn't yet stored gets reset.

While many things get reset, some basic UI state and current lo-

cations are preserved, including tabs.

:restart full

variation of :restart that makes no attempt to preserve any-

thing.

:restore

:[range]restore

restore file from trash directory, doesn't work outside one of

trash directories. See "Trash directory" section below.

:rlink

:[range]rlink[!?]

create relative symbolic links to files in directory of other

view. With "?" prompts for destination file names in an editor.

"!" forces overwrite.

:[range]rlink[!] path

create relative symbolic links of files in directory specified

with the path (absolute or relative to directory of other view).

"!" forces overwrite.

:[range]rlink[!] name1 name2...

create relative symbolic links of files in directory of other

view giving each next link a corresponding name from the argu-

ment list. "!" forces overwrite.

:screen

toggle whether to use the terminal multiplexer or not.

A terminal multiplexer uses pseudo terminals to allow multiple

windows to be used in the console or in a single xterm. Start-

ing vifm from terminal multiplexer with appropriate support

turned on will cause vifm to open a new terminal multiplexer

window for each new file edited or program launched from vifm.

This requires screen version 3.9.9 or newer for the screen -X

argument or tmux (1.8 version or newer is recommended).

:screen!

enable integration with terminal multiplexers.

:screen?

display whether integration with terminal multiplexers is en-

abled.

Note: the command is called screen for historical reasons (when tmux

wasn't yet supported) and might be changed in future releases, or get

an alias.

:select

:[range]select

select files in the given range (current file if no range is

given).

:select {pattern}

select files that match specified pattern. Possible {pattern}

forms are described in "Patterns" section below. Trailing slash

for directories is taken into account, so `:select! */ | invert

s` selects only files.

:select //[iI]

same as item above, but reuses last search pattern.

:select !{external command}

select files from the list supplied by external command. Files

are matched by full paths, relative paths are converted to abso-

lute ones beforehand.

:[range]select! [{pattern}]

same as above, but resets previously selected items before pro-

ceeding.

:session

:session?

print name of the current session.

:session

detach current session without saving it. Resets v:session.

:session name

create or load and switch to a session with the specified name.

Name can't contain slashes. Session active at the moment is

saved before the switch. Session is also automatically saved

when quiting the application in usual ways. Sets v:session.

:set

:se[t] display all options that differ from their default value.

:se[t] all

display all options.

:se[t] opt1=val1 opt2='val2' opt3="val3" ...

sets given options. For local options both values are set.

You can use following 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 op-

tion^=x

- for charset options - option=x, option+=x, option-=x and op-

tion^=x

the meaning:

- option - turn option on (for boolean) or print its value (for

all others)

- nooption - turn option off

- invoption - invert option state

- option! - invert option state

- option? - print option value

- option& - reset option to its default value

- option=x or option:x - set option to x

- option+=x - add/append x to option

- option-=x - remove (or subtract) x from option

- option^=x - toggle x presence among values of the option

Option name can be prepended and appended by any number of

whitespace characters.

:setglobal

:setg[lobal]

display all global options that differ from their default value.

:setg[lobal] all

display all global options.

:setg[lobal] opt1=val1 opt2='val2' opt3="val3" ...

same as :set, but changes/prints only global options or global

values of local options. Changes to the latter might be not

visible until directory is changed.

:setlocal

:setl[ocal]

display all local options that differ from their default value.

:setl[ocal] all

display all local options.

:setl[ocal] opt1=val1 opt2='val2' opt3="val3" ...

same as :set, but changes/prints only local values of local op-

tions.

:shell

:sh[ell][!]

start a shell in current directory. "!" suppresses spawning

dedicated window of terminal multiplexer for a shell. To make

vifm adaptive to environment it uses $SHELL if it's defined,

otherwise 'shell' value is used.

:siblnext

:[count]siblnext[!]

change directory to [count]th next sibling directory after cur-

rent path using value of global sort option of current pane.

"!" enables wrapping.

For example, say, you're at /boot and root listing starts like

this:

bin/

boot/

dev/

...

Issuing :siblnext will navigate to /dev.

:siblprev

:[count]siblprev[!]

same as :siblnext, but in the opposite direction.

:sort

:sor[t]

display dialog with different sorting methods, where one can se-

lect the primary sorting key. When 'viewcolumns' options is

empty and 'lsview' is off, changing primary sorting key will

also affect view look (in particular the second column of the

view will be changed). See "Menus and dialogs" section for con-

trols.

:source

:so[urce] file

read command-line commands from the file.

:split

:sp[lit]

switch to a two window horizontal view.

:sp[lit]!

toggle horizontal window splitting.

:sp[lit] path

splits the window horizontally to show both file directories.

Also changes other pane to path (absolute or relative to current

directory of active pane).

:substitute

:[range]s[ubstitute]/pattern/string/[flags]

for each file in range replace a match of pattern with string.

String can contain \0...\9 to link to capture groups (\0 - all match,

\1 - first group, etc.).

Pattern is stored in 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 (each g toggles this)

:[range]s[ubstitute]/pattern

substitute pattern with an empty string.

:[range]s[ubstitute]//string/[flags]

use last pattern from search history.

:[range]s[ubstitute]

repeat previous substitution command.

:sync

:sync [relative path]

change the other pane to the current pane directory or to some

path relative to the current directory. Using macros is al-

lowed.

:sync! change the other pane to the current pane directory and synchro-

nize cursor position. If current pane displays custom list of

files, position before entering it is used (current one might

not make any sense).

all]...

change enumerated properties of the other pane to match corre-

sponding properties of the current pane. Arguments have the

following meanings:

- location - current directory of the pane;

- cursorpos - cursor position (doesn't make sense without "lo-

cation");

- localopts - all local options;

- filters - all filters;

- filelist - list of files for custom view (implies "loca-

tion");

- tree - tree structure for tree view (implies "location");

- all - all of the above.

:tabclose

:tabc[lose]

close current tab, unless it's the only one open at current

scope.

:tabmove

:tabm[ove] [N]

without the argument or with ` gemini - kennedy.gemi.dev as the argument, current tab

becomes the last tab. With the argument, current tab is moved

after the tab with the specified number. Argument of `0` moves

current tab to the first position.

:tabname

:tabname [name]

set, update or reset (when no argument is provided) name of the

current tab.

:tabnew

:tabnew [path]

create new tab. Accepts optional path for the new tab. Macros

and environment variables are expanded.

:tabnext

:tabn[ext]

switch to the next tab (wrapping around).

:tabn[ext] {n}

go to the tab number {n}. Tab numeration starts with 1.

:tabonly

:tabo[nly]

close all tabs but the current one. Closes pane tabs only at

the active side.

:tabprevious

:tabp[revious]

switch to the previous tab (wrapping around).

:tabp[revious] {n}

go to the {n}-th previous tab. Note that :tabnext handles its

argument differently.

:touch

:[line]touch file...

create files at specified paths. Aborts on errors. Doesn't up-

date time of existing files. The [line] can be used to pick

node in a tree-view. Macros are expanded.

:tr

:[range]tr/pattern/string/

for each file in range transliterate the characters which appear

in pattern to the corresponding character in string. When

string is shorter than pattern, it's padded with its last char-

acter.

:trashes

lists all valid trash directories in a menu. Only non-empty and

writable trash directories are shown. This is exactly the list

of directories that are cleared when :empty command is executed.

:trashes?

same as :trashes, but also displays size of each trash direc-

tory.

:tree

:tree turn pane into tree view with current directory as its root.

The tree view is implemented on top of a custom view, but is au-

tomatically kept in sync with file system state and considers

all the filters. Thus the structure corresponds to what one

would see on visiting the directories manually. As a special

case for trees built out of custom view file-system tracking

isn't performed.

To leave tree view go up from its root or use gh at any level of

the tree. Any command that changes directory will also do, in

particular, `:cd ..`.

Tree structure is incompatible with alternative representations,

so values of 'lsview' and 'millerview' options are ignored.

:tree! toggle current view in and out of tree mode.

:undolist

:undol[ist]

display list of latest changes. Use "!" to see actual commands.

See "Menus and dialogs" section for controls.

:unlet

:unl[et][!] $ENV_VAR1 $ENV_VAR2 ...

remove environment variables. Add ! to omit displaying of warn-

ings about nonexistent variables.

:unselect

:[range]unselect

unselect files in the given range (current file if no range is

given).

:unselect {pattern}

unselect files that match specified pattern. Possible {pattern}

forms are described in "Patterns" section below. Trailing slash

for directories is taken into account, so `:unselect */` unse-

lects directories.

:unselect !{external command}

unselect files from the list supplied by external command.

Files are matched by full paths, relative paths are converted to

absolute ones beforehand.

:unselect //[iI]

same as item above, but reuses last search pattern.

:version

:ve[rsion]

show menu with version information.

:vifm

:vifm same as :version.

:view

:vie[w]

toggle on and off the quick file view (preview of file's con-

tents). See also 'quickview' option.

:vie[w]!

turn on quick file view if it's off.

:volumes

only for MS-Windows

display menu with volume list. Hitting l (or Enter) key opens

appropriate volume in the current pane. See "Menus and dialogs"

section for controls.

:vsplit

:vs[plit]

switch to a two window vertical view.

:vs[plit]!

toggle window vertical splitting.

:vs[plit] path

split the window vertically to show both file directories. And

changes other pane to path (absolute or relative to current di-

rectory of active pane).

:wincmd

:[count]winc[md] {arg}

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

:windo

:windo [command...]

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

:winrun

:winrun type [command...]

execute command for pane(s), which is determined by type argu-

ment:

- ^ - top-left pane

- $ - bottom-right pane

- % - all panes

- . - current pane

- , - other pane

:write

:w[rite]

write current state to vifminfo and session files (if a session

is active).

:wq

:wq[!] same as :quit, but ! disables only the check of backgrounded

commands, while state of the application is always written.

:wqall

:wqa[ll][!]

same as :qall, but ! disables only the check of backgrounded

commands, while state of the application is always written.

:xall

:xa[ll][!]

same as :qall.

:xit

:x[it][!]

same as :quit.

:yank

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

will yank files to the reg register.

:map lhs rhs

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

:map! lhs rhs

map lhs key sequence to rhs in command line mode.

:cmap :dmap :mmap :nmap :qmap

:vmap

: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

: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

:cm[ap] beginning

list all maps in command line mode that start with the begin-

ning.

:dm[ap] beginning

list all maps in dialog modes that start with the beginning.

:mm[ap] beginning

list all maps in menu mode that start with the beginning.

:nm[ap] beginning

list all maps in normal mode that start with the beginning.

:qm[ap] beginning

list all maps in view mode that start with the beginning.

:vm[ap] beginning

list all maps in visual mode that start with the beginning.

:noremap

:no[remap] lhs rhs

map the key sequence lhs to rhs for normal and visual modes, but

disallow mapping of rhs.

:no[remap]! lhs rhs

map the key sequence lhs to rhs for command line mode, but dis-

allow mapping of rhs.

:cnoremap :dnoremap :mnoremap :nnoremap :qnoremap

:vnoremap

:cno[remap] lhs rhs

map the key sequence lhs to rhs for command line mode, but dis-

allow mapping of rhs.

:dn[oremap] lhs rhs

map the key sequence lhs to rhs for dialog modes, but disallow

mapping of rhs.

:mn[oremap] lhs rhs

map the key sequence lhs to rhs for menu mode, but disallow map-

ping of rhs.

:nn[oremap] lhs rhs

map the key sequence lhs to rhs for normal mode, but disallow

mapping of rhs.

:qn[oremap] lhs rhs

map the key sequence lhs to rhs for view mode, but disallow map-

ping of rhs.

:vn[oremap] lhs rhs

map the key sequence lhs to rhs for visual mode, but disallow

mapping of rhs.

:unmap

:unm[ap] lhs

remove user mapping of lhs from normal and visual modes.

:unm[ap]! lhs

remove user mapping of lhs from command line mode.

:cunmap :dunmap :munmap :nunmap :qunmap

:vunmap

:cu[nmap] lhs

remove user mapping of lhs from command line mode.

:du[nmap] lhs

remove user mapping of lhs from dialog modes.

:mu[nmap] lhs

remove user mapping of lhs from menu mode.

:nun[map] lhs

remove user mapping of lhs from normal mode.

:qun[map] lhs

remove user mapping of lhs from view mode.

:vu[nmap] lhs

remove user mapping of lhs from visual mode.

Ranges

The ranges implemented include:

2,3 - from second to third file in the list (including it)

% - the entire directory.

. - the current position in the filelist.

$ - the end of the filelist.

't - the mark position t.

Examples:

:%delete

would delete all files in the directory.

:2,4delete

would delete the files in the list positions 2 through 4.

:.,$delete

would delete the files from the current position to the end of the

filelist.

:3delete4

would delete the files in the list positions 3, 4, 5, 6.

If a backward range is given :4,2delete - an query message is given and

user can chose what to do next.

The builtin commands that accept a range are :d[elete] and :y[ank].

Command macros

The command macros may be used in user commands.

%a User arguments. When user arguments contain macros, they are

expanded before preforming 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, but see "Selection" section below.

%F %"F All of the selected files in the other directory list, but see

"Selection" section below.

%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 com-

mand.

%IU same as %U, but gives up terminal before running external com-

mand.

%S Show command output in the status bar.

%q redirect command output to quick view, which is activated if

disabled.

%s Execute command in split window of active terminal multiplexer

(ignored if not running inside one).

%n Forbid using of terminal multiplexer to run the command.

%i Completely ignore command output.

%pc Marks the end of the main command and the beginning of the clear

command for graphical preview, which is invoked on closing pre-

view 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 ter-

minal state.

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 %m, %M, %s, %S, %i, %u and %U macros are mutually exclusive.

Only the last one of them on the command will take effect.

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 de-

scription.

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 file names only, when %C and %F are

expanded to full paths. %f and %F follow this in %b too.

: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 direc-

tory.

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 background-

ing:

%m, %M, %s, %S, %u and %U macros cannot be combined with background

mark (" &") as it doesn't make much sense.

Command backgrounding

Copy and move operation can take a lot of time to proceed. That's why

vifm supports backgrounding of this two operations. To run :copy,

:move or :delete command in the background just add " &" at the end of

a command.

For each background operation a new thread is created. Job cancella-

tion can be requested in the :jobs menu via dd shortcut.

You can see if command is still running in the :jobs menu. Back-

grounded commands have progress instead of process id at the line be-

ginning.

Background operations cannot be undone.

Cancellation

Note that cancellation works somewhat different on Windows platform due

to different mechanism of break signal propagation. One also might

need to use Ctrl-Break shortcut instead of Ctrl-C.

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.

Note that vifm never terminates applications, it sends SIGINT signal

and lets the application quit normally.

When one of 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.

Cancelled operations are indicated by "(cancelled)" suffix appended to

information message on statusbar.

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.

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.

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

Mounting with FUSE

It's not considered to be an error, so only notification on the status

bar is shown.

External application calls

Each of this operations can be cancelled: :apropos, :find, :grep, :lo-

cate.

Selection

If there is a selection, it's stashed before proceeding further unless

file under the cursor is part of that selection. This means that 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 you run selection by running one of selected files, oth-

erwise you're running a single file even if there are other selected

entries.

When running a selection it must not include broken symbolic links, has

to be consistent and set of file handlers must be compatible. Consis-

tency means that selection contains either only directories (including

links to them) or only files, but not their mix.

Compatibility is a more sophisticated check, but it's defined in a nat-

ural 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` and/or `%C`

- include neither `%f` nor `%F`

then each file is executed independently of the rest.

3. If all handlers are equal, the common handler is executed. This

handler might ignore selection and process only file under the

cursor.

4. 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.

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 pat-

tern matching.

The last form is implicitly refers to one of others. :highlight does

not accept undecorated form, while :filetype, :filextype, :fileviewer,

:select, :unselect and 'classify' treat it as 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.

: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 de-

scription 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").

There are no implicit `^` or ` gemini - kennedy.gemi.dev , so make sure to specify them explic-

itly if the pattern should match the whole name or path.

Patterns with globs

"Globs" section below provides short overview of globs and some impor-

tant 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.

Examples

Associate `evince` to PDF-files only inside `/home/user/downloads/` di-

rectory (excluding its subdirectories):

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

Globs

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

`*`, `?`, `[` 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 sym-

bol.

`*` 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.

`?` 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 char-

acter class matches against any of characters listed in it. For exam-

ple

: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 negotia-

tion 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 sin-

gle digit in their name.

If you need to include literal comma, which is normally separates mul-

tiple globs, double it.

: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.

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 ex-

ception 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.

'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, spe-

cific for a particular *prg option, and %% sequence for insert-

ing 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.

'autochpos'

type: boolean

default: true

When disabled vifm will set cursor to the first line in the view

after :cd and :pushd commands instead of saved cursor position.

Disabling this will also make vifm clear information about cur-

sor position in the view history on :cd and :pushd commands (and

on startup if 'autochpos' is disabled in the vifmrc). l key in

the ":history ." and ":trashes" menus are treated like :cd com-

mand. This option also affects marks so that navigating to a

mark doesn't restore cursor position.

When this option is enabled, more fine grained control over cur-

sor position is available via 'histcursor' option.

'columns' 'co'

type: integer

default: terminal width on startup

Terminal width in characters.

'caseoptions'

type: charset

default: ""

This option gives additional control over case sensitivity by

allowing overriding default behaviour to either always be case

sensitive or always be case insensitive. Possible values form

pairs of lower and upper case letters that configure 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 affect, if both or more are

present, only the last one matters. When none of pair's ele-

ments are present, the behaviour is default (depends on operat-

ing system for path completion and on values of 'ignorecase' and

'smartcase' options for file navigation).

'cdpath' 'cd'

type: string list

default: value of $CDPATH with commas instead of colons

Specifies locations to check on changing directory with relative

path that doesn't start with "./" or "../". When non-empty,

current directory is examined after directories listed in the

option.

This option doesn't affect completion of :cd command.

Example:

set cdpath=~

This way ":cd bin" will switch to "~/bin" even if directory

named "bin" exists in current directory, while ":cd ./bin" com-

mand will ignore value of 'cdpath'.

'chaselinks'

type: boolean

default: false

When enabled path of view is always resolved to real path (with

all symbolic links expanded).

'classify'

type: string list

default: ":dir:/"

Specifies file name prefixes and suffixes depending on file type

or name. The format is either of:

- [{prefix}]:{filetype}:[{suffix}]

- [{prefix}]::{pattern}::[{suffix}]

Possible {pattern} forms are described in "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 {pre-

fix} 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.

Comma (',') character can be inserted by doubling it. List of

file type names can be found in the description of filetype()

function.

'confirm' 'cf'

type: set

default: delete,permdelete

Defines which operations require confirmation:

- delete - moving files to trash (on d or :delete);

- permdelete - permanent deletion of files (on D or :delete!

command or on undo/redo operation).

'cpoptions' 'cpo'

type: charset

default: "fst"

Contains a sequence of single-character flags. Each flag en-

ables behaviour of older versions of vifm. Flags:

- f - when included, running :filter command results in not in-

verted (matching files are filtered out) and :filter! in in-

verted (matching files are left) filter, when omitted, meaning

of the exclamation mark changes to the opposite;

- s - when included, yy, dd and DD normal mode commands act on

selection, otherwise they operate on current file only;

- t - when included, <tab> (thus <c-i>) behave as <space> and

switches active pane, otherwise <tab> and <c-i> go forward in

the view history. It's possible to make both <tab> and <c-i> to

work as expected by setting up the terminal to emit a custom se-

quence 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.

'deleteprg'

type: string

default: ""

Specifies program to run on files that are permanently removed.

When 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.

'dirsize'

type: enumeration

default: size

Controls how size of directories is displayed in file views.

The following values are possible:

- size - size of directory (i.e., size used to store list of

files)

- nitems - number of entries in the directory (excluding . and

..)

Size obtained via ga/gA overwrites this setting so seeing count

of files and occasionally size of directories is possible.

'dotdirs'

type: set

default: nonrootparent,treeleafsparent

Controls displaying of dot directories. The following values

are possible:

- 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 "../" entry regard-

less of value of this option. "../" disappears at the moment at

least one file is created.

'dotfiles'

type: boolean

default: false

Whether dot files are shown in the view. Can be controlled with

z* bindings.

'fastrun'

type: boolean

default: false

With this option turned on you can run partially entered com-

mands with unambiguous beginning using :! (e.g. :!Te instead of

:!Terminal or :!Te<tab>).

'fillchars' 'fcs'

type: string list

default: ""

Sets characters used to fill borders.

item default used for

vborder:c ' ' left, middle and right vertical bor-

ders

If value is omitted, its default value is used. Example:

set fillchars=vborder:.

'findprg'

type: string

default: "find %s %a -print , -type d \( ! -readable -o ! -exe-

cutable \) -prune"

Specifies format for an external command to be invoked by the

:find command. The format supports expansion of macros specific

for this particular option and %% sequence for inserting percent

sign literally. The macros are:

macro value/meaning

%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

%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:

- 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 ap-

pended in this order

The macros slightly change their meaning depending on 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

list of selected file names, if any

- %a, %A and %p are assigned literal arguments when first

argument starts with a dash ("-"), otherwise %a gets an escaped

version of the arguments with a predicate and %p contains es-

caped version of the arguments

Starting with Windows Server 2003 a `where` command is avail-

able. 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

:find command with selection of more than one item because the

command ignores all directory paths except for the last one.

When using find port on Windows, another option is to setup

'findprg' like this:

set findprg="find %s %a"

'followlinks'

type: boolean

default: true

Follow links on l or Enter. That is navigate to destination

file instead of treating the link as if it were target file.

Doesn't affects links to directories, which are always entered

(use gf key for directories).

'fusehome'

type: string

default: "($XDG_DATA_HOME/.local/share | $VIFM)/fuse/"

Directory to be used as a root dir for FUSE mounts. Value of

the option can contain environment variables (in form "$en-

vname"), which will be expanded (prepend it with a slash to pre-

vent expansion). The value should expand to an absolute path.

If you change this option, vifm won't remount anything. It af-

fects future mounts only. See "Automatic FUSE mounts" section

below for more information.

'gdefault' 'gd'

type: boolean

default: false

When on, 'g' flag is on for :substitute by default.

'grepprg'

type: string

default: "grep -n -H -I -r %i %a %s"

Specifies format for an external command to be invoked by the

:grep command. The format supports expanding of macros, spe-

cific for a particular *prg option, and %% sequence for insert-

ing percent sign literally. This option should include the %i

macro to specify placement of "-v" string when inversion of re-

sults is requested, %a or %A macro to specify placement of argu-

ments passed to the :grep command and the %s macro to specify

placement of 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 'findprg' option for description of 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_sil-

ver_searcher):

set grepprg='ag --line-numbers %i %a %s'

'histcursor'

type: set

default: startup,dirmark,direnter

Defines situations when cursor should be moved according to di-

rectory 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 situa-

tions when cursor is positioned automatically.

'history' 'hi'

type: integer

default: 15

Maximum number of stored items in all histories.

'hlsearch' 'hls'

type: boolean

default: true

Automatically select files that are search matches.

'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 de-

tailed 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:

Controls details of file operations. The following values are

available:

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

'lines'

type: integer

default: terminal height on startup

Terminal height in lines.

'locateprg'

type: string

default: "locate %a"

Specifies format for an external command to be invoked by the

:locate command. The format supports expanding of macros, spe-

cific for a particular *prg option, and %% sequence for insert-

ing 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 in-

stalled)

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

: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 pro-

vided)

- mount-point= - specifies a mount point (can be absent or ap-

pear more than once)

All other lines are ignored. Each `device=` starts a new sec-

tion describing a device which should include two other possible

prefixes.

`list` subcommand is assumed to always succeed, while exit code

of `mount` and `unmount` is taken into account to determine

whether operation was performed successfully.

'lsoptions'

type: string list

default: ""

scope: local

Configures ls-like view.

item used for

transposed 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 `ls -x`

command. See "ls-like view" section below for format descrip-

tion. 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.

item default used for

lsize:num 0 left column

csize:num 1 center column (can't be disabled)

rsize:num 0 right column

rpreview:str 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 central (main) column can't be disabled.

rpreview specifies what file-system objects should be previewed

in the right column and can take two values: dirs (only directo-

ries) or all. Both options don't include 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'.

'mintimeoutlen'

type: integer

default: 150

The fracture of 'timeoutlen' in milliseconds that is waited be-

tween 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.

'number' 'nu'

type: boolean

default: false

scope: local

Print line number in front of each file name when 'lsview' op-

tion is turned off. Use 'numberwidth' to control width of line

number. Also see 'relativenumber'.

'numberwidth' 'nuw'

type: integer

default: 4

scope: local

Minimal number of characters for line number field.

'previewprg'

type: string

default: ""

scope: local

External command to be used instead of preview programs config-

ured via :fileviewer command.

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.

'relativenumber' 'rnu'

type: boolean

default: false

scope: local

Print relative line number in front of each file name when

'lsview' option is turned off. Use 'numberwidth' to control

width of line number. Various combinations of 'number' and

'relativenumber' lead to such results:

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

'rulerformat' 'ruf'

type: string

default: "%l/%S "

Determines the content of the ruler. Its minimal width is 13

characters and it's right aligned. Following macros are sup-

ported:

%= - 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

%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

Percent sign can be followed by optional minimum field width.

Add '-' before minimum field width if you want field to be right

aligned.

Optional blocks are ignored unless at least one macro inside of

them is expanded to a non-empty value.

Example:

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

'runexec'

type: boolean

default: false

Run executable file on Enter, l or Right Arrow key. Behaviour

of the last two depends on the value of the 'lsview' option.

'scrollbind' 'scb'

type: boolean

default: false

When this option is set, vifm will try to keep difference of

scrolling positions of two windows constant.

'scrolloff' 'so'

type: integer

default: 0

Minimal number of screen lines to keep above and below the cur-

sor. If you want cursor line to always be in the middle of the

view (except at the beginning or end of the file list), set this

option to some large value (e.g. 999).

'sessionoptions' 'ssop'

sessionoptions ssop

type: set

default: tui,state,tabs,savedirs,dhistory

An equivalent of 'vifminfo' for sessions, uses the same values.

When both options include the same value, data from session file

has higher priority (data from vifminfo isn't necessarily com-

pletely discarded, instead it's merged with the state of a ses-

sion the same way state of multiple instances is merged on

exit).

'shell' 'sh'

type: string

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

Full path to the shell to use to run external commands. On *nix

a shell argument can be supplied.

'shellcmdflag' 'shcf'

type: string

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

Command-line option used to pass a command to 'shell'. It's

used in contexts where command comes from the user.

Note that using this option to force interactive mode of the

shell is most likely a BAD IDEA. In general interactive host

and interactive child shell can't share the same terminal ses-

sion. You can't even run such a shell in background. Consider

writing a wrapper for your shell that preloads aliases and com-

mands without making the shell interactive and ending up using

it in a way it was not meant to be used.

Note that this option is ignored when 'shell' is set to Power-

Shell due to the internal use of `-encodedCommand`.

'shortmess' 'shm'

type: charset

default: "p"

Contains a sequence of single-character flags. Each flag en-

ables shortening of some message displayed by vifm in the TUI.

Flags:

- L - display only last directory in tab line instead of full

path.

- M - shorten titles in windows of terminal multiplexers cre-

ated 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.

'showtabline' 'stal'

type: enumeration

default: multiple

Specifies when 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 Vim-like values are also accepted and

correspond to "never", "multiple" and "always" respectively.

'sizefmt'

type: string list

default: "units:iec"

Configures the way size is formatted in human-friendly way.

item value meaning

units: iec Use 1024 byte units (K or KiB,

etc.).

See 'iec' option.

si Use 1000 byte units (KB, etc.).

precision: i > 0 How many fraction digits to con-

sider.

{not set} Precision of 1 for integer part

< 10,

0 otherwise (provides old behav-

iour).

space {present} Insert space before unit sym-

bols.

This is the default.

nospace {present} Do not insert space before unit

symbols.

Numbers are rounded from zero. Trailing zeros are dropped.

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 paths prefixes for fs/directories that work

too slow for you. 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 di-

rectory (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 'ignorecase' option is

enabled.

'sort' type: string list

default: +name on *nix and +iname on Windows

scope: local

Sets list of sorting keys (first item is primary key, second is

secondary key, etc.):

[+-]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, e.g. mode)

[+-]mtime - time modified (when file contents is changed)

Note: look for st_atime, st_ctime and st_mtime in "man 2 stat"

for more information on time keys.

'+' means ascending sort for this key, and '-' means descending

sort.

"dir" key is somewhat similar in this regard but it's added im-

plicitly: when "dir" is not specified, sorting behaves as if it

was the first key in the list. That's why if one wants sorting

algorithm to mix directories and files, "dir" should be appended

to sorting option, for example like this:

set sort+=dir

set sort=-size,dir

Value of the option is checked to include dir key and default

sorting key (name on *nix, iname on Windows). Here is what hap-

pens if one of them is missing:

- 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 primary sort-

ing key set, unless 'viewcolumns' option is not empty.

'sortnumbers'

type: boolean

default: false

scope: local

Natural sort of (version) numbers within text.

'sortgroups'

type: string

default: ""

scope: local

Sets comma-separated list of regular expressions for 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.

Each expression should contain at least one group or its value

will be considered to be always empty. Also, only the first

match of regular expression is processed.

The first group divides list of files into sub-groups, each of

which is then sorted by substrings extracted using second regu-

lar expression and so on recursively.

Example:

set sortgroups=-(todo|done).*

this would group files with "-done" in their names and files

with "-todo" separately. On ascending sorting, group containing

"-done" would appear before the other one.

'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

command-line). Empty string means use same format like in pre-

vious versions. Following macros are supported:

- %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 'clas-

sify')

- %A - file attributes (permissions on *nix or properties 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 at current partition

- %z - short tips/tricks/hints that chosen randomly after one

minute period

- %{<expr>} - evaluate arbitrary vifm expression '<expr>', e.g.

'&sort'

- %* - resets or applies one of User1..User9 highlight groups;

reset happens when width field is 0 or not specified, one of

groups gets picked when width field is in the range from 1 to

- all 'rulerformat' macros

Percent sign can be followed by optional minimum field width.

Add '-' before minimum field width if you want 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:

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 de-

fault), '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 group of instances that share registers

between each other. When several instances of vifm have this

option set to identical value, they automatically synchronize

contents of their registers on operations which use them.

'syscalls'

type: boolean

default: false

When disabled, vifm will rely on external applications to per-

form file-system operations, otherwise system calls are used in-

stead (much faster and supports progress tracking). The option

should eventually be removed. Mostly *nix-like systems are af-

fected.

'tablabel'

type: string

default: ""

When non-empty, determines format of the main part of a single

tab's label.

When empty, tab label is set to either tab name for named tabs

or to 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-%9 - applies one of User1..User9 highlight groups

In global tabs the view in bullets above refers to currently ac-

tive view of that tab.

Flag macros are a special kind of macros that always expand to

an empty value and are ment 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

'tabprefix'

type: string

default: "[%N:"

Determines prefix of a tab's label. Formatting is done as for

'tablabel' option.

'tabscope'

type: enumeration

default: global

Picks style of tabs, which defines what a single tab contains.

Possible values:

- global - tab describes complete UI of two views and how they

are arranged

- pane - tab is located "inside" a pane and manages it and

quick view

'tabstop' 'ts'

type: integer

default: value from curses library

Number of spaces that a Tab in the file counts for.

'tabsuffix'

type: string

default: "]"

Determines suffix of a tab's label. Formatting is done as for

'tablabel' option.

'timefmt'

type: string

default: "%m/%d %H:%M"

Format of time in file list. See "man 1 date" or "man 3 strf-

time" for details.

'timeoutlen' 'tm'

type: integer

default: 1000

The time in milliseconds that is waited for a mapped key in case

of already typed key sequence is ambiguous.

'title'

type: boolean

default: true when title can be restored, false otherwise

When enabled, title of the terminal or terminal multiplexer's

window is updated according to current location. Because not

all terminals support setting title, this works only if `$TERM`

value matches one of the following 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 trash directory. See "Trash directory" section below.

'trashdir'

type: string

default: on *nix:

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

or if $VIFM/Trash doesn't exist

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

on Windows:

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

List of trash directory path specifications, separated with com-

mas. Each list item either defines an absolute path to trash

directory or a path relative to a mount point root when list el-

ement starts with "%r/". Value of the option can contain envi-

ronment variables (of form "$envname"), which will be expanded

(prepend $ with a slash to prevent expansion). Environment

variables are expanded when the option is set.

On *nix, if element ends with "%u", the mark is replaced with

real user ID and permissions are set so that only that only

owner is able to use it.

Note that even this setup is not completely secure when combined

with "%r/" and it's overall safer to keep files in home direc-

tory, but that implies cost of copying files between partitions.

When new file gets cut (deleted) vifm traverses each element of

the option in the order of their appearance and uses first trash

directory that it was able to create or that is already

writable.

Default value tries to use trash directory per mount point and

falls back to ~/.vifm/Trash on failure.

Will attempt to create the directory if it does not exist. See

"Trash directory" section below.

'tuioptions' 'to'

type: charset

default: "psv"

Each flag configures some aspect of TUI appearance. The flags

are:

p - when included:

* 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

"s" character) are visible.

u - use Unicode characters in the TUI (Unicode ellipsis instead

of "...").

v - vary width of middle border to equalize view sizes.

'undolevels' 'ul'

type: integer

default: 100

Maximum number of changes that can be undone. Note that here

single file operation is used as a unit, not operation, i.e.

deletion of 101 files will exceed default limit.

'vicmd'

type: string

default: "vim"

Command used to edit files in various contexts. Ampersand sign

at the end (regardless whether it's preceded by space or not)

means backgrounding of command.

Background flag is ignored in certain context where vifm waits

for the editor to finish. Such contexts include any command

that spawns editor to change list of file names or a command,

with :rename being one example. `-f` is also appended to pre-

vent forking in such cases, so the command needs to handle the

flag.

Additionally `+{num}` and `+'call cursor()'` arguments are used

to position cursor when location is known.

'viewcolumns'

type: string

default: ""

scope: local

Format string containing list of columns in the view. When this

option is empty, view columns to show are chosen automatically

using sorting keys (see 'sort') as a base. Value of this option

is ignored if 'lsview' is set. See "Column view" section below

for format description.

An example of setting the options for both panes (note :windo

command):

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

'vixcmd'

type: string

default: value of 'vicmd'

Same as 'vicmd', but takes precedence over it when running in-

side 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 special ones like '< and '>

tui - state of the user interface (sorting, number of

windows, quick

view state, active view)

dhistory - directory history

state - file name and dot filters and terminal multiplex-

ers integration

state

cs - primary color scheme

savedirs - save last visited directory

chistory - command line history

shistory - search history (/ and ? commands)

phistory - prompt history

fhistory - history of local filter (see description of the

"=" normal mode

command)

dirstack - directory stack overwrites previous stack, unless

stack of

current instance is empty

registers - registers content

tabs - global or pane tabs

options - all options that can be set with the :set command

(obsolete)

filetypes - associated programs and viewers (obsolete)

commands - user defined commands (see :command description)

(obsolete)

'vimhelp'

type: boolean

default: false

Use vim help format.

'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 presentation style of 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 charac-

ters)

Specifies which characters in command-line mode should be con-

sidered as part of a word. Value of the option is comma-sepa-

rated list of ranges. If both endpoints of a range match, sin-

gle endpoint is enough (e.g. "a" = "a-a"). Both endpoints are

inclusive. There are two accepted forms: character representing

itself or number encoding character according to ASCII table.

In case of ambiguous characters (dash, comma, digit) use 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 intentionally 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 end of the list.

Mappings

Map arguments

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

special sequences:

Postpone UI updates until RHS is completely processed.

<wait> In case of builtin mapping causing conflict for a user-defined

mapping (e.g., `t` builtin to a partially typed `ta` user-de-

fined 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 spe-

cial 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>).

<bs> Backspace key (see key conflict description below).

Tabulation and Shift+Tabulation keys.

Home/End.

Arrow keys.

PageUp/PageDown.

Delete key. <del> and <delete> mean different codes, but

<delete> is more common.

Insert key.

<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> Alt + some key.

<a-c-a>,<a-c-b>,...,<a-c-z>

<m-c-a>,<m-c-b>,...,<m-c-z> only for *nix

Alt + Ctrl + some key.

Functional keys.

<c-f1> - <c-f12>

only for MS-Windows

functional keys with Control key pressed.

<a-f1> - <a-f12>

only for MS-Windows

functional keys with Alt key pressed.

<s-f1> - <s-f12>

only for MS-Windows

functional keys with Shift key pressed.

Note that due to the way terminals process their input, several key-

board keys might be mapped to single key code, for example:

- <cr> and <c-m>;

- <tab> and <c-i>;

- <c-h> and <bs>;

- etc.

Most of the time they are defined consistently and don't cause sur-

prises, but <c-h> and <bs> are treated differently in different envi-

ronments (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>

Whitespace

vifm removes whitespace characters at the beginning and end of com-

mands. 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.

Expression syntax

Supported expressions is a subset of what VimL provides.

Expression syntax summary, from least to most significant:

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

v:var builtin variable

function(expr1, ...) function call

(expr1) nested expression

".." indicates that the operations in this level can be concatenated.

expr1

-----

expr2 || expr2

Arguments are converted to numbers before evaluation.

Result is non-zero if at least one of arguments is non-zero.

It's right associative and with short-circuiting, so sub-expressions

are evaluated from left to right until result of whole expression is

determined (i.e., until first non-zero) or end of the expression.

expr2

-----

expr3 && expr3

Arguments are converted to numbers before evaluation.

Result is non-zero only if both arguments are non-zero.

It's right associative and with short-circuiting, so sub-expressions

are evaluated from left to right until result of whole expression is

determined (i.e., until first zero) or end of the expression.

expr3

-----

expr4 {cmp} expr4

Compare two expr4 expressions, resulting in a 0 if it evaluates to

false or 1 if it evaluates to true.

equal ==

not equal !=

greater than >

greater than or equal >=

smaller than <

smaller than or equal <=

Examples:

'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 sub-

traction

Examples:

1 + 3 - 3 == 1

1 + '2' == 3

expr5

-----

expr6 . expr6 .. string concatenation

Examples:

'a' . 'b' == 'ab'

'aaa' . '' . 'c' == 'aaac'

expr6

-----

- expr6 unary minus

+ expr6 unary plus

! expr6 logical NOT

For '-' the sign of the number is changed.

For '+' the number is unchanged.

For '!' non-zero becomes zero, zero becomes one.

A String will be converted to a Number first.

These operations can be repeated and mixed. Examples:

--9 == 9

---9 == -9

-+9 == 9

!-9 == 0

!'' == 1

!'x' == 0

!!9 == 1

expr7

-----

number number constant

-----

Decimal number. Examples:

0 == 0

0000 == 0

01 == 1

123 == 123

10000 == 10000

string

------

"string" string constant

Note that double quotes are used.

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' string constant

Note that single quotes are used.

This string is taken as it is. No backslashes are removed or have a

special meaning. The only exception is that two quotes stand for one

quote.

Examples:

'All\slashes\are\saved.'

'This string contains doubled single quotes ''here'''

option

------

&option option value (local one is preferred, if 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). See ":set options" section above.

environment variable

--------------------

$VAR environment variable

The String value of any environment variable. When it is not defined,

the result is an empty string.

Examples:

'This is my $PATH env: ' . $PATH

'vifmrc at ' . $MYVIFMRC . ' is used.'

builtin variable

--------------------

v:var builtin variable

Information exposed by vifm for use in scripting.

v:count

count passed to : command, 0 by default. Can be used in mappings to

passthe 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.

function call

-------------

function(expr1, ...) function call

See "Functions" section below.

Examples:

"'" . filetype('.') . "'"

filetype('.') == 'reg'

expression nesting

------------------

(expr1) nested expression

Groups any other expression of arbitrary complexity enforcing order in

which operators are applied.

Functions

USAGE RESULT DESCRIPTION

chooseopt({opt}) String Queries choose parameters passed on

startup.

executable({expr}) Integer Checks whether {expr} command avail-

able.

expand({expr}) String Expands special keywords in {expr}.

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

String Caches output of {extcmd} per {cache}

and

{path} combination.

filetype({fnum} [, {resolve}])

String Returns file type from position.

fnameescape({expr}) String Escapes {expr} for use in a :command.

getpanetype() String Returns type of current pane.

has({property}) Integer Checks whether instance has {prop-

erty}.

layoutis({type}) Integer Checks whether layout is of type

{type}.

paneisat({loc}) Integer Checks whether current pane is at

{loc}.

system({command}) String Executes shell command and returns

its output.

tabpagenr([{arg}]) Integer Returns number of current or last

tab.

term({command}) String Like system(), but for interactive

commands.

chooseopt({opt})

Retrieves values of options related to file choosing. {opt} can be one

of:

files returns argument of --choose-files or empty string

dir returns argument of --choose-dir or empty string

cmd returns argument of --on-choose or empty string

delimiter returns argument of --delimiter or the default one (\n)

executable({expr})

If {expr} is absolute or relative path, checks whether path destination

exists and refers to an executable, otherwise checks whether command

named {expr} is present in directories listed in $PATH. Checks for

various executable extensions on Windows. Returns boolean value de-

scribing 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

expand({expr})

Expands environment variables and macros in {expr} just like it's done

for command-line commands. Returns a string. See "Command macros"

section above.

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')

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

Caches value of {extcmd} external command automatically updating it as

necessary based on monitoring change date of a {path}. The cache is

invalidated when file or its meta-data is updated. A single path can

have multiple caches associated with it.

{path} value is normalized, but symbolic links in it aren't 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')) }"

filetype({fnum} [, {resolve}])

The result is a string, which represents file type and is one of the

list:

exe executables

reg regular files

link symbolic links

broken broken symbolic links (appears only when resolving)

dir directories

char character devices

block block devices

fifo pipes

sock *nix domain sockets

? unknown file type (should not normally happen) or

non-file (pseudo-entries in compare view)

The result can also be an empty string in case of invalid argument.

Parameter {fnum} can have following values:

- '.' to get type of file under the cursor in the active pane

- numerical value base 1 to get type of file on specified line num-

ber

Optional parameter {resolve} is treated as a boolean and specifies

whether symbolic links should be resolved.

fnameescape({expr})

Escapes parameter to make it suitable for use as an argument of a :com-

mand. List of escaped characters includes %, which is doubled.

Usage example:

" navigate to most recently modified file in current directory

execute 'goto' fnameescape(system('ls -t | head -1'))

getpanetype()

Retrieves string describing type of current pane. Possible return val-

ues:

regular regular file listing of some directory

custom custom file list (%u)

very-custom very custom file list (%U)

tree tree view

has({property})

Allows examining internal parameters from scripts to e.g. figure out

environment in which application is running. Returns 1 if property is

true/present, otherwise 0 is returned. Currently the following proper-

ties are supported (anything else will yield 0):

unix runs in *nix-like environment (including Cygwin)

win runs on Windows

Usage example:

" skip user/group on Windows

if !has('win')

let $RIGHTS = '%10u:%-7g '

endif

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

layoutis({type})

Checks whether 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 position of active pane in current layout matches one of

the following locations:

top pane reaches top border

bottom pane reaches bottom border

left pane reaches left border

right pane reaches right border

system({command})

Runs the command in shell and returns its output (joined standard out-

put and standard error streams). All trailing newline characters are

stripped to allow easy appending to command output. Ctrl-C should in-

terrupt the command.

Use this function to consume output of external commands that don't re-

quire user interaction and term() for interactive commands that make

use of terminal and are capable of handling stream redirection.

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 called without arguments returns number of current tab page base

one.

When called with "$" as an argument returns number of the last tab page

base one, which is the same as number of tabs.

term({command})

Same as system() function, but user interface is shutdown during the

execution of the command, which makes sure that external interactive

applications won't affect the way terminal is used by vifm.

Usage example:

" command to change directory by picking it via fzf

command! fzfcd :execute 'cd'

fnameescape(term('find -type d | fzf 2> /dev/tty'))

Menus and dialogs

When navigating to some path from a menu there is a difference in end

location depending on whether path has trailing slash or not. Files

normally don't have trailing slashes so "file/" won't work and one can

only navigate to a file anyway. On the other hand with directories

there are two options: navigate to a directory or inside of it. To al-

low both use cases, the first one is used on paths like "dir" and the

second one for "dir/".

Commands

:range navigate to a menu line.

:exi[t][!] :q[uit][!] :x[it][!]

leave menu mode.

:noh[lsearch]

reset search match highlighting.

:w[rite] {dest}

write all menu lines into file specified by {dest}.

General

j, Ctrl-N - move down.

k, Ctrl-P - move up.

Enter, l - select and exit the menu.

Ctrl-L - redraw the menu.

Escape, Ctrl-C, ZZ, ZQ, q - quit.

In all menus

The following set of keys has the same meaning as in normal mode.

Ctrl-B, Ctrl-F

Ctrl-D, Ctrl-U

Ctrl-E, Ctrl-Y

/, ?

n, N

[count]G, [count]gg

H, M, L

zb, zt, zz

zh - scroll menu items [count] characters to the right.

zl - scroll menu items [count] characters to the left.

zH - scroll menu items half of screen width characters to the right.

zL - scroll menu items half of screen width characters to the left.

: - enter command line mode for menus (currently only :exi[t], :q[uit],

:x[it] and :{range} are supported).

b - interpret content of the menu as list of paths and use it to create

custom view in place of previously active pane. See "Custom views"

section below.

B - same as above, but creates unsorted view.

v - load menu content into quickfix list of the editor (Vim compatible

by assumption) or if list doesn't have separators after file names

(colons) open each line as a file name.

Below is description of additional commands and reaction on selection

in some menus and dialogs.

Apropos menu

Selecting menu item runs man on a given topic. Menu won't be closed

automatically to allow view several pages one by one.

Command-line mode abbreviations menu

Type dd on an abbreviation to remove it.

c leaves menu preserving file selection and inserts right-hand side of

selected command into command-line.

Color scheme menu

Selecting name of a color scheme applies it the same way as if ":col-

orscheme <name>" was executed on the command-line.

Commands menu

Selecting command executes it with empty arguments (%a).

dd on a command to remove.

Marks menu

Selecting mark navigates to it.

dd on a mark to remove it.

Bookmarks menu

Selecting a bookmark navigates to it.

Type dd on a bookmark to remove it.

gf and e also work to make it more convenient to bookmark files.

Trash (:lstrash) menu

r on a file name to restore it from trash.

dd deletes file under the cursor.

Trashes (:trashes) menu

dd empties selected trash in background.

Directory history and Trashes menus

Selecting directory name will change directory of the current view as

if :cd command was used.

Directory stack menu

Selecting directory name will rotate stack to put selected directory

pair at the top of the stack.

File (:file) menu

Commands from vifmrc or typed in command-line are displayed above empty

line. All commands below empty line are from .desktop files.

c leaves menu preserving file selection and inserts command after :! in

command-line mode.

Grep, find, locate, bookmarks and user menu with navigation (%M macro)

gf - navigate previously active view to currently selected item.

Leaves menu mode except for grep menu. Pressing Enter key has the same

effect.

e - open selected path in the editor, stays in menu mode.

c - leave menu preserving file selection and insert file name after :!

in command-line mode.

User menu without navigation (%m macro)

c leaves menu preserving file selection and inserts whole line after :!

in command-line mode.

Grep menu

Selecting file (via Enter or l key) opens it in editor set by 'vicmd'

at given line number. Menu won't be closed automatically to allow

viewing more than one result.

See above for "gf" and "e" keys description.

Command-line history menu

Selecting an item executes it as command-line command, search query or

local filter.

c leaves menu preserving file selection and inserts line into command-

line of appropriate kind.

Volumes menu

Selecting a drive navigates previously active pane to the root of that

drive.

Fileinfo dialog

Enter, q - close dialog

Sort dialog

h, Space - switch ascending/descending.

q - close dialog

One shortcut per sorting key (see the dialog).

Attributes (permissions or properties) dialog

h, Space - check/uncheck.

q - close dialog

Item states:

- * - checked flag.

- X - means that it has different value for files in selection.

- 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 execute permission bit from all files, but preserve it for di-

rectories, set all execute flags to 'd' and check 'Set Recursively'

flag.

Jobs menu

dd requests cancellation of job under cursor. The job won't be removed

from the list, but marked as being cancelled (if cancellation was suc-

cessfully requested). A message will pop 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 key displays errors of selected job if any were collected. They are

displayed in a new menu, but you can get back to jobs menu by pressing

Undolist menu

r - reset undo position to group under the cursor.

Media menu

Selecting a device either mounts (if it wasn't mounted yet) or navi-

gates to its first mount point.

Selecting a mount point navigates to it.

Selecting "not mounted" line causes mounting.

Selecting any other line does nothing.

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.

Custom views

Definition

Normally file views contain list of files from a single directory, but

sometimes it's useful to populate them with list of files that do not

belong to the same directory, which is what custom views are for.

Presentation

Custom views are still related to directory they were in before custom

list was loaded. Path to that directory (original directory) can be

seen in the title of a custom view.

Files in same directory have to be named differently, this doesn't hold

for custom views thus seeing just file names might be rather confusing.

In order to give an idea where files come from and when possible, rela-

tive paths to original directory of the view is displayed, otherwise

full path is used instead.

Custom views normally don't contain any inexistent files.

Navigation

Custom views have some differences related to navigation in regular

views.

gf - acts similar to gf on symbolic links and navigates to the file at

its real

location.

h - go to closes parent node in tree view, otherwise return to the

original directory.

gh - return to the original directory.

Opening ".." entry also causes return to the original directory.

History

Custom list exists only while it's visible, once left one can't return

to it, so there is no appearances of it in any history.

Filters

Only local filter affects content of the view. This is intentional,

presumably if one loads list, precisely that list should be displayed

(except for inexistent paths, which are ignored).

Although directory names are visible in listing, they are not search-

able. Only file names are taken into account (might be changed in fu-

ture, searching whole lines seems quite reasonable).

Sorting

Contrary to search sorting by name works on whole visible part of file

path.

Highlight

Whole file name is highlighted as one entity, even if there are direc-

tory elements.

Updates

Reloads can occur, though they are not automatic due to files being

scattered among different places. On a reload, inexistent files are

removed and meta-data of all other files is updated.

Once custom view forgets about the file, it won't add it back even if

it's created again. So not seeing file previously affected by an oper-

ation, which was undone is normal.

Operations

All operations that add files are forbidden for custom views. For ex-

ample, moving/copying/putting files into a custom view doesn't work,

because it doesn't make much sense.

On the other hand, operations that use files of a custom view as a

source (e.g. yanking, copying, moving file from custom view, deletion)

and operations that modify names are all allowed.

Compare views

Kinds

:compare can produce four different results depending on 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 one file system tree. Here duplicates

are files that have at least one copy in the same tree. The other two

kinds of operation compare two trees, in which duplicates are files

that are found in both trees.

Lists of unique files are presented in custom views because there is no

file grouping to preserve as all file ids are guaranteed to be dis-

tinct.

Creation

Arguments passed to :compare form four categories each with its own

prefix and is responsible for particular property of 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 data they contain (combination of size and hash of

small chunk of contents is used as first approximation, so don't worry

too much about large files).

Which files to display:

- listall - all files;

- listunique - unique files only;

- listdups - only duplicated files.

How results are grouped (has no effect if "ofone" specified):

- groupids - files considered identical are always adjacent in out-

put;

- grouppaths - file system ordering is preferred (this also enables

displaying identically named files as mismatches).

Which files to omit:

- skipempty - ignore empty files.

Each argument can appear multiple times, the rightmost one of the group

is considered. Arguments alter default behaviour instead of substitut-

ing it.

Examples

The defaults corresponds to probably the most common use case of com-

paring files in two trees with grouping by paths, so the following are

equivalent:

:compare

:compare bycontents grouppaths

:compare bycontents listall ofboth grouppaths

Another use case is to find 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 as it's unable to display diff-

like data.

Comparison views have second column displaying id of the file, files

with same id are considered to be equal. The view columns configura-

tion is predefined.

Behaviour

When two views are being compared against each other the following

changes to the 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 be-

haviour;

- 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 comparison;

- entries which indicate absence of 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

single pane).

Files are gathered in this way:

- recursively starting at current location of the view;

- dot files are excluded if view hides them at the moment of compari-

son;

- directories are not taken into account;

- symbolic links to directories are ignored.

Startup

On startup vifm determines several variables that are used during exe-

cution. They are determined in the order they appear below.

On *nix systems $HOME is normally present and used as is. On Windows

systems vifm tries to find correct home directory in the following or-

der:

- $HOME variable;

- $USERPROFILE variable (on Windows only);

- a combination of $HOMEDRIVE and $HOMEPATH variables (on Windows

only).

vifm tries to find correct configuration directory by checking the fol-

lowing places:

- $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.

vifm tries to find correct configuration file by checking the following

places:

- $MYVIFMRC variable;

- vifmrc in parent directory of the executable file (on Windows only);

- $VIFM/vifmrc file.

Configure

See "Startup" section above for the explanations on $VIFM and $MYV-

IFMRC.

The vifmrc file contains commands that will be executed on vifm

startup. There are two such files: global and local. Global one is at

{prefix}/etc/vifm/vifmrc, see $MYVIFMRC variable description for the

search algorithm used to find local vifmrc. Global vifmrc is loaded

before the local one, so that the later one can redefine anything con-

figured globally.

Use vifmrc to set settings, mappings, filetypes etc. To use multi line

commands precede each next line with a slash (whitespace before slash

is ignored, but all spaces at the end of the lines are saved). For ex-

ample:

set

\smartcase

equals "setsmartcase". When

set<space here>

\ smartcase

equals "set smartcase".

The $VIFM/vifminfo file contains generic state of the application. You

can control what is stored in vifminfo by setting 'vifminfo' option.

Vifm always writes this file on exit unless 'vifminfo' option is empty.

Marks, bookmarks, commands, histories, filetypes, fileviewers and reg-

isters in the file are merged with vifm configuration (which has bigger

priority).

Generally, runtime configuration has bigger priority during merging,

but there are some exceptions:

- directory stack stored in the file is not overwritten unless some-

thing 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 con-

tain exactly one tab of any kind.

The $VIFM/scripts directory can contain shell scripts. vifm modifies

its PATH environment variable to let user run those scripts without

specifying full path. All subdirectories of the $VIFM/scripts will be

added to PATH too. Script in a subdirectory overlaps script with the

same name in all its parent directories.

The $VIFM/colors/ and {prefix}/etc/vifm/colors/ directories contain

color schemes. Available color schemes are searched in that order, so

on name conflict the one in $VIFM/colors/ wins.

Each color scheme should have ".vifm" extension. This wasn't the case

before and for this reason the following 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 ex-

tension being truncated).

Sessions

Sessions provide a way to have multiple persistent runtime configura-

tions. Think of them as second-level vifminfo files in addition to the

first-level one used by all sessions. In other words, they aren't a

replacement for vifminfo file that exists without sessions, but an ad-

dition to it. One can empty 'vifminfo' option and rely solely on ses-

sions, but in practice one might want to share some state among in-

stances in different sessions or have an "out-of-sessions" state for

tasks that don't deserve a session of their own.

This leads to a two-level structure where data in session files has

higher priority than data in vifminfo files (where this makes sense)

following the same rules that merging of vifminfo file obeys. In addi-

tion to that, history items from session files are never ordered before

history items from vifminfo file.

Format

Sessions have the format of vifminfo files, they do not consist of se-

quence of command-line commands and are not meant to be sourced via

:source command.

Storage and naming

`$VIFM/sessions/` directory serves as a storage for sessions. Conse-

quently names should be valid filenames. The structure of the storage

is flat meaning that there are no subdirectories, that's why names of

sessions can't contain slashes.

Usage model

Contrary to Vim, vifm automates 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.