Quickstart Tutorial
This first part should give just enough information to allow the new user to navigate through the tree to any file/dir, open the file, and pass commands to the shell.
The bare essentials
Launching/exiting Vifm
Run Vifm from a terminal
Without arguments, like in
vifm
Vifm with no configuration starts with both panes in current directory of a
shell. That said, normally sample vifmrc
file is installed
for your convenience, which among other things configures vifm to remember
last visited location (remove savedirs
from line that starts with
set vifminfo=
to disable this).
With single argument, like in
vifm /bin
path changes left (or top) pane to specified path. In this case this pane is also automatically set to be the active one (e.g. it owns cursor).
With two arguments, like in
vifm /bin /tmp
the first one specifies path for the left (or top) pane and the second one for the right (or bottom) pane.
See also Starting Vifm.
Quitting
Using normal mode (main mode, in which Vifm starts) shortcut ZZ.
Or with the help of command-line mode (the one entered after : is
pressed) command :q
, which should be followed by the
Enter key to be executed.
See also Quitting Vifm.
Movements are very much Vim-like, the main four keys are the same: h, j, k, l.
Basic movement (within file list of a view, menu items):
- j - down one item at a time;
- k - up one item at a time;
- gg - go to the top of a list;
- G - go to the bottom of a list.
Navigation and running actions:
- h - go to the parent directory;
- l or Enter on a directory - enter into the directory.
- l or Enter on a file - open file in external editor (which is of course Vim by default). If you don't know, use :q followed by Enter to quit Vim.
Navigation between panes: space or tab (same as Ctrl-I) - switch active pane.
Modes
The effect of key presses in Vifm depends on current mode. A mode defines scope for shortcuts. Initial mode (in which Vifm starts) is called Normal mode. Normal mode is also the main mode, in a sense that if one will leave all menus/dialogs/modes he will end up being in Normal mode.
Keys like j and gg described above belong to Normal mode and are handled by its routines. Different modes might assign different meaning to the same keys, which is in fact the main purpose of the concept: allow reuse of the same keys by putting bindings inside mode context.
Most of keys do not change mode, but some obviously do this and some even exist
just to do that. For example, : (colon) in Normal mode enters
Command-line mode. The Command-line mode is the second most used mode
and you already should know at least one of its commands, namely
:q
, which is a short name of :quit
and is a command
to quit Vifm. Escape and Ctrl-C leave
Command-line mode returning you back to Normal mode.
Here is graphical representation of how modes process keys:
Here you can see that:
- Vifm starts in Normal mode (arrow labeled
startup
); - gg and j keys in Normal mode don't change current mode;
- : changes Normal mode to Command-line mode;
- Escape and Ctrl-C return back from Command-line mode to Normal mode.
Note that some people that are aware of Vim's modes mistakenly refer to its Command-line mode as Command mode. This is wrong. Command mode is a synonym for Normal mode, "command" word causes this confusion. Try to remember that "command" in a more general can refer to a keyboard combination, Normal mode has plenty of shortcuts and it's the primary mode. Gathering all this together, Normal mode is Command mode because one gives commands to an application in it more often than in other modes.
Command-line commands
TODO: briefly explain use of commands, mention that they are used for configuration.
Opening files
Vifm can be configured to open/preview files with external applications based
on recognizing patterns in file names. If one wants, Vifm can be configured to
use system-wide associations (see sample vifmrc
file and look for
filetype *
). Otherwise, one can configure commands to run in a
more precise fashion.
Default action for directories is entering them and for files it's opening them with Vim.
There are two kinds of associations that are defined with different commands (on Windows, they are equivalent as it always runs in graphics mode):
filetype
- for non-graphical commands (e.g.less
);filextype
- for graphical-only commands (e.g.gvim
).
Filetype with registered handler
Some launchers are defined in sample vifmrc
file, which is
automatically installed on the first run for a new user. See
~/.vifm/vifmrc
. In this case hitting Enter or
l will edit/open a file (or enter a directory).
Change set norunexec
to set runexec
in
~/.vifm/vifmrc
to run executable files rather then open them
for editing.
Defining new associations
General syntax for defining associations is (everything between in and including angle brackets are placeholders):
filetype <pattern1>,<pattern2>
\ {<optional description>}
\ <command to run file>,
\ <background command to run file> &,
One can use macros such as %c
, %f
that are substituted
with selected file name or names correspondingly, by default %f
is
appended automatically. On Windows, it's better to use quoted form of macros:
%"c
and %"f
. See below for examples.
The important difference of filetype commands from other commands is that *order matters*. This in turn comes from the difference that associations are added up instead of being overwritten. This means that
filextype *.html,*.htm
\ {Open with firefox}
\ firefox %f &,
filetype *.html,*.htm links, lynx
is *not the same* as
filetype *.html,*.htm links, lynx
filextype *.html,*.htm
\ {Open with firefox}
\ firefox %f &,
It's firefox; links; lynx
vs. links; lynx; firefox
.
Enabling system-wide associations
In operating system different standard commands are used:
xdg-open
on *nix-like system;start
on Windows;open
on OS X.
The command is:
filetype * <handler>
For example (e.g. for GNU/Linux):
filetype * xdg-open
Sample vifmrc
already contains all of these, just commented out.
Be sure to keep this as the last of filetype
commands, so it will be
a fallback for files that are not handled by any other association.
Quickly open with external application
TODO |
if run an unknown filetype without Defining a Filetype Association, you must use the commandline.
if the program runs within the terminal as text only, such as ls, type without the quotes, ':!!ls -al %c' and then press [Enter]. Explain that that is a commandline mode command and what each part of it does. link to a list of available command line commands.
Running applications in background
TODO |
if you would like to continue using Vifm while the program runs, which is most likely the case if it runs in its own window, run the task in the background using '&'. For example, if you wanted to launch the terminal emulator xterm in the current directory use '!xterm &'. If xterm didn't work try gnome-terminal, urxvt, konsol, etc. Did you noticed that you didn't need to specify the current directory? This is because Vifm launches '!' commands in the current directory.
Do common tasks faster
Vifm provides a subset of shell builtin commands:
:cd path
- change directory of current pane to specified path.:cd
,:cd ~
or:cd ~user/dir
work as you would expect in a shell.:pushd path
- push current directory on directory stack and change directory to specified path.:popd
- pop path from directory stack and navigate into it.:dirs
- display menu with directory list.
:cd
and :pushd
accept two parameters, which specifies path for inactive pane.
File operations
Operation | Normal mode | Command-line mode | Description |
---|---|---|---|
yanking (copying) |
yy | :yank |
Yanks current file/selection into register (remembers path of it). |
putting (pasting) |
p P |
:copy[!?][ &] :move[!?][ &] |
Copying/moving previously yanked files. |
delete | dd DD |
:delete[ &] :delete![ &] |
Moving to trash/erasing files. |
Normal mode commands
Depending of the value of 'cpoptions'
option
yy/dd/DD can operate either always on the
current file or on selection if it's present, the later is the default.
- yy - yank current file or selection.
- p - put (paste) previously yanked files by copying them to current directory.
- P - put (paste) previously yanked files by moving them to current directory.
- dd - move current file or selection to trash.
- DD - erase current file or all selected ones.
Paired operations like p and P or dd and DD demonstrate the following generic rule: upper-case commands are "hardened" versions of corresponding lower-case ones. It makes sense as they are actually harder to enter, so it's harder to make something potentially destructive.
Command-line mode commands
:copy
- copy current file or selected files from active pane to inactive pane (fails on name conflicts).:copy!
- copy current file or selected files from active pane to inactive pane (overwrites files at destination).:move
- move current file or selected files from active pane to inactive pane (fails on name conflicts).:move!
- move current file or selected files from active pane to inactive pane (overwrites files at destination).:delete
- moves current file or selected files to trash.:delete!
- erases current file or selected files (by defaults after confirmation).:mkdir dirname
- create directory
Running operations in background
File system operations are blocking by default and sometimes can require significant amount of time to complete. One can use non-blocking versions that perform operations in background, the cost for convenience is that they can't be undone.
:copy &
- copy in background.:move &
- move in background.:delete &
- move to trash in background.:delete! &
- erase in background.
Use :jobs
command to background operations that are still active.
Vifm also asks whether you sure about quitting if unfinished operations are
running in background.
Basic configuration
Setting options
Options are changed with :set
Command-line command. There
are several types of options (boolean, integer, string, list of strings, set of
characters, enumerations), which support various operations, which are mostly
what one would expect.
Check manual pages, Vim-doc or plain text help that comes with Vifm for a full list of options (it's also available online, e.g. man or Vim-doc).
Some quick examples (try them out on command line):
" boolean option
set ignorecase
" string option
set rulerformat="%=%2l-%S [%L] "
Syntax
Generic syntax is:
:set option[=value|?|&] option[=value|?|&] ...
Checking value of an option
State of non-boolean options can be queried interactively by specifying option on its own:
:set history
More generic way is to specify question mark (?
) after option name:
:set history?
:set vicmd?
Resetting an option
If option value is messed up in some way, just use optionname&
to
reset it to default value. For example
:set vicmd&
resets value of vicmd
to "vim".
Syntax for changing boolean options
Boolean options are the most common type and such options have some additional syntax:
:set option
- enable'option'
;:set nooption
- disable'option'
;:set invoption
- toggle'option'
;:set option!
- toggle'option'
.
Syntax for changing string options
There are three ways of assigning string value of an option:
:set option=value\ with\ spaces
:set option='value with spaces'
:set option="value with spaces"
There is no big difference between single and double quotes.
Making options persistent
There is no storage for options, instead Vifm uses regular text files where
command-line commands can be used to alter configuration. Normally, it's
~/.vifm/vifmrc
file that contains configuration, but it's
configurable and depends on operating system. Generally, appending new
:set
command to the end of ~/.vifm/vifmrc
should
make option persistent, no special syntax, for example:
set incsearch
See Configuration model.