https://wiki.vifm.info/api.php?action=feedcontributions&user=Mb720&feedformat=atomVifm Wiki - User contributions [en]2024-03-28T16:54:15ZUser contributionsMediaWiki 1.35.1https://wiki.vifm.info/index.php?title=Quickstart_Tutorial&diff=515Quickstart Tutorial2019-08-26T13:48:24Z<p>Mb720: /* Quickly open with external application */ Expand entry with example of opening GUI application. Improve formatting.</p>
<hr />
<div>This first part should give just enough information to allow the new user to<br />
navigate through the tree to any file/dir, open the file, and pass commands to the shell.<br />
<br />
= The bare essentials =<br />
<br />
== Launching/exiting Vifm ==<br />
<br />
=== Run Vifm from a terminal ===<br />
<br />
''Without arguments'', like in<br />
<br />
<source lang="bash"><br />
vifm<br />
</source><br />
<br />
Vifm with no configuration starts with both panes in current directory of a<br />
shell. That said, normally sample <code>vifmrc</code> file is installed<br />
for your convenience, which among other things configures vifm to remember<br />
last visited location (remove <code>savedirs</code> from line that starts with<br />
<code>set vifminfo=</code> to disable this).<br />
<br />
''With single argument'', like in<br />
<br />
<source lang="bash"><br />
vifm /bin<br />
</source><br />
<br />
path changes left (or top) pane to specified path. In this case this pane is<br />
also automatically set to be the active one (e.g. it owns cursor).<br />
<br />
''With two arguments'', like in<br />
<br />
<source lang="bash"><br />
vifm /bin /tmp<br />
</source><br />
<br />
the first one specifies path for the left (or top) pane and the second one for<br />
the right (or bottom) pane.<br />
<br />
See also [[Starting Vifm]].<br />
<br />
=== Quitting ===<br />
<br />
Using normal mode (main mode, in which Vifm starts) shortcut <kbd>ZZ</kbd>.<br />
<br />
Or with the help of command-line mode (the one entered after <kbd>:</kbd> is<br />
pressed) command <code>:q</code>, which should be followed by the<br />
<kbd>Enter</kbd> key to be executed.<br />
<br />
See also [[Quitting Vifm]].<br />
<br />
== Navigation ==<br />
<br />
Movements are very much Vim-like, the main four keys are the same: <kbd>h</kbd>,<br />
<kbd>j</kbd>, <kbd>k</kbd>, <kbd>l</kbd>.<br />
<br />
Basic movement (within file list of a view, menu items):<br />
<br />
* <kbd>j</kbd> - down one item at a time;<br />
* <kbd>k</kbd> - up one item at a time;<br />
* <kbd>gg</kbd> - go to the top of a list;<br />
* <kbd>G</kbd> - go to the bottom of a list.<br />
<br />
Navigation and running actions:<br />
<br />
* <kbd>h</kbd> - go to the parent directory;<br />
* <kbd>l</kbd> or <kbd>Enter</kbd> on a directory - enter into the directory.<br />
* <kbd>l</kbd> or <kbd>Enter</kbd> on a file - open file in external editor (which is of course [https://en.wikipedia.org/wiki/Vim_(text_editor) Vim] by default). If you don't know, use <kbd>:q</kbd> followed by <kbd>Enter</kbd> to quit Vim.<br />
<br />
Navigation between panes: <kbd>space</kbd> or <kbd>tab</kbd> (same as <kbd>Ctrl-I</kbd>) - switch active pane.<br />
<br />
== Modes ==<br />
<br />
The effect of key presses in Vifm depends on current mode. A ''mode'' defines<br />
scope for shortcuts. Initial mode (in which Vifm starts) is called<br />
''Normal mode''. ''Normal mode'' is also the main mode, in a sense that if one<br />
will leave all menus/dialogs/modes he will end up being in ''Normal mode''.<br />
<br />
Keys like <kbd>j</kbd> and <kbd>gg</kbd> described above belong to<br />
''Normal mode'' and are handled by its routines. Different modes might assign<br />
different meaning to the same keys, which is in fact the main purpose of the<br />
concept: allow reuse of the same keys by putting bindings inside mode context.<br />
<br />
Most of keys do not change mode, but some obviously do this and some even exist<br />
just to do that. For example, <kbd>:</kbd> (colon) in ''Normal mode'' enters<br />
''Command-line mode''. The ''Command-line mode'' is the second most used mode<br />
and you already should know at least one of its commands, namely<br />
<code>:q</code>, which is a short name of <code>:quit</code> and is a command<br />
to quit Vifm. <kbd>Escape</kbd> and <kbd>Ctrl-C</kbd> leave<br />
''Command-line mode'' returning you back to ''Normal mode''.<br />
<br />
Here is graphical representation of how modes process keys:<br />
<br />
[[File:Basic-modes-example.png]]<br />
<br />
Here you can see that:<br />
<br />
* Vifm starts in ''Normal mode'' (arrow labeled <code>startup</code>);<br />
* <kbd>gg</kbd> and <kbd>j</kbd> keys in ''Normal mode'' don't change current mode;<br />
* <kbd>:</kbd> changes ''Normal mode'' to ''Command-line mode'';<br />
* <kbd>Escape</kbd> and <kbd>Ctrl-C</kbd> return back from ''Command-line mode'' to ''Normal mode''.<br />
<br />
''Note'' that some people that are aware of Vim's modes mistakenly refer to its<br />
''Command-line mode'' as ''Command mode''. This is ''wrong''. ''Command mode''<br />
is a synonym for ''Normal mode'', "command" word causes this confusion. Try<br />
to remember that "command" in a more general can refer to a keyboard<br />
combination, ''Normal mode'' has plenty of shortcuts and it's the primary mode.<br />
Gathering all this together, ''Normal mode'' is ''Command mode'' because one<br />
gives commands to an application in it more often than in other modes.<br />
<br />
=== Command-line commands ===<br />
<br />
'''TODO''': briefly explain use of commands, mention that they are used for configuration.<br />
<br />
== Opening files ==<br />
<br />
Vifm can be configured to open/preview files with external applications based<br />
on recognizing patterns in file names. If one wants, Vifm can be configured to<br />
use system-wide associations (see sample <code>vifmrc</code> file and look for<br />
<code>filetype *</code>). Otherwise, one can configure commands to run in a<br />
more precise fashion.<br />
<br />
Default action for directories is entering them and for files it's opening them<br />
with Vim.<br />
<br />
There are two kinds of associations that are defined with different<br />
commands (on Windows, they are equivalent as it always runs in graphics mode):<br />
<br />
* <code>filetype</code> - for non-graphical commands (e.g. <code>less</code>);<br />
* <code>filextype</code> - for graphical-only commands (e.g. <code>gvim</code>).<br />
<br />
=== Filetype with registered handler ===<br />
<br />
Some launchers are defined in sample <code>vifmrc</code> file, which is<br />
automatically installed on the first run for a new user. See<br />
<code>~/.vifm/vifmrc</code>. In this case hitting <kbd>Enter</kbd> or<br />
<kbd>l</kbd> will edit/open a file (or enter a directory).<br />
<br />
Change <code>set norunexec</code> to <code>set runexec</code> in<br />
<code>~/.vifm/vifmrc</code> to run executable files rather then open them<br />
for editing.<br />
<br />
=== Defining new associations ===<br />
<br />
General syntax for defining associations is (everything between in and including angle brackets are placeholders):<br />
<br />
<source lang="vim"><br />
filetype <pattern1>,<pattern2><br />
\ {<optional description>}<br />
\ <command to run file>,<br />
\ <background command to run file> &,<br />
</source><br />
<br />
One can use [http://vifm.info/manual.shtml#Command%20macros macros] such as <code>%c</code>, <code>%f</code> that are substituted<br />
with selected file name or names correspondingly, by default <code>%f</code> is<br />
appended automatically. On Windows, it's better to use quoted form of macros:<br />
<code>%"c</code> and <code>%"f</code>. See below for examples.<br />
<br />
The important difference of filetype commands from other commands is that *order<br />
matters*. This in turn comes from the difference that associations are added up<br />
instead of being overwritten. This means that<br />
<br />
<source lang="vim"><br />
filextype *.html,*.htm<br />
\ {Open with firefox}<br />
\ firefox %f &,<br />
filetype *.html,*.htm links, lynx<br />
</source><br />
<br />
is *not the same* as<br />
<br />
<source lang="vim"><br />
filetype *.html,*.htm links, lynx<br />
filextype *.html,*.htm<br />
\ {Open with firefox}<br />
\ firefox %f &,<br />
</source><br />
<br />
It's <code>firefox; links; lynx</code> vs. <code>links; lynx; firefox</code>.<br />
<br />
=== Enabling system-wide associations ===<br />
<br />
In operating system different standard commands are used:<br />
<br />
* <code>xdg-open</code> on *nix-like system;<br />
* <code>start</code> on Windows;<br />
* <code>open</code> on OS X.<br />
<br />
The command is:<br />
<br />
<source lang="vim"><br />
filetype * <handler><br />
</source><br />
<br />
For example (e.g. for GNU/Linux):<br />
<br />
<source lang="vim"><br />
filetype * xdg-open<br />
</source><br />
<br />
Sample <code>vifmrc</code> already contains all of these, just commented out.<br />
<br />
Be sure to keep this as the last of <code>filetype</code> commands, so it will be<br />
a fallback for files that are not handled by any other association.<br />
<br />
=== Quickly open with external application ===<br />
<br />
If you want to run a file whose type is not [[#Defining new associations|associated]] with an application or if you want to run the file using a different application, you must use the [[Command-line and alike modes|command line mode]].<br />
<br />
To run a non-GUI program such as <code>ls</code>:<br />
<br />
<source lang="vim"><br />
:!!ls -al %c<br />
</source><br />
<br />
The [http://vifm.info/manual.shtml#Command%20macros macro] <code>%c</code> will be expanded to the name of the file currently under the cursor.<br />
<br />
Here's how to open an image with GIMP instead of opening it with the associated image viewer:<br />
<source lang="vim"><br />
:!gimp %c<br />
</source><br />
<br />
{{TODO}}<br />
<br />
Explain what each part of the command does. Link to a list of available command line commands.<br />
<br />
=== Running applications in background ===<br />
<br />
{{TODO}}<br />
<br />
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, [https://en.wikipedia.org/wiki/List_of_terminal_emulators etc]. Did you noticed that you didn't need to specify the current directory? This is because Vifm launches '!' commands in the current directory.<br />
<br />
= Do common tasks faster =<br />
<br />
== Shell-like navigation via command-line ==<br />
<br />
Vifm provides a subset of shell builtin commands:<br />
<br />
* <code>:cd path</code> - change directory of current pane to specified path. <code>:cd</code>, <code>:cd ~</code> or <code>:cd ~user/dir</code> work as you would expect in a shell.<br />
* <code>:pushd path</code> - push current directory on directory stack and change directory to specified path.<br />
* <code>:popd</code> - pop path from directory stack and navigate into it.<br />
* <code>:dirs</code> - display menu with directory list.<br />
<br />
<code>:cd</code> and <code>:pushd</code> accept two parameters, which specifies path for inactive pane.<br />
<br />
== File operations ==<br />
<br />
{| class="wikitable"<br />
|+Summary of basic operations on files<br />
! width="100px" | Operation<br />
! width="70px" | Normal mode<br />
! width="150px" | Command-line mode<br />
! width="450px" | Description<br />
|-<br />
|! align="center" | yanking<br>(copying) ||! align="center" | <kbd>yy</kbd> || <code>:yank</code> || Yanks current file/selection into register (remembers path of it).<br />
|-<br />
|! align="center" | putting<br>(pasting) ||! align="center" | <kbd>p</kbd><br><kbd>P</kbd> || <code>:copy[!?][ &]</code><br><code>:move[!?][ &]</code> || Copying/moving previously yanked files.<br />
|-<br />
|! align="center" | delete ||! align="center" | <kbd>dd</kbd><br><kbd>DD</kbd> || <code>:delete[ &]</code><br><code>:delete![ &]</code> || Moving to trash/erasing files.<br />
|}<br />
<br />
=== Normal mode commands ===<br />
<br />
Depending of the value of <code>'cpoptions'</code> option<br />
<kbd>yy</kbd>/<kbd>dd</kbd>/<kbd>DD</kbd> can operate either always on the<br />
current file or on selection if it's present, the later is the default.<br />
<br />
* <kbd>yy</kbd> - yank current file or selection.<br />
* <kbd>p</kbd> - put (paste) previously yanked files by copying them to current directory.<br />
* <kbd>P</kbd> - put (paste) previously yanked files by moving them to current directory.<br />
* <kbd>dd</kbd> - move current file or selection to trash.<br />
* <kbd>DD</kbd> - erase current file or all selected ones.<br />
<br />
Paired operations like <kbd>p</kbd> and <kbd>P</kbd> or <kbd>dd</kbd> and<br />
<kbd>DD</kbd> demonstrate the following generic rule: upper-case commands are<br />
"hardened" versions of corresponding lower-case ones. It makes sense as they<br />
are actually harder to enter, so it's harder to make something potentially<br />
destructive.<br />
<br />
=== Command-line mode commands ===<br />
<br />
* <code>:copy</code> - copy current file or selected files from active pane to inactive pane (fails on name conflicts).<br />
* <code>:copy!</code> - copy current file or selected files from active pane to inactive pane (overwrites files at destination).<br />
* <code>:move</code> - move current file or selected files from active pane to inactive pane (fails on name conflicts).<br />
* <code>:move!</code> - move current file or selected files from active pane to inactive pane (overwrites files at destination).<br />
* <code>:delete</code> - moves current file or selected files to trash.<br />
* <code>:delete!</code> - erases current file or selected files (by defaults after confirmation).<br />
* <code>:mkdir dirname</code> - create directory<br />
<br />
==== Running operations in background ====<br />
<br />
File system operations are blocking by default and sometimes can require<br />
significant amount of time to complete. One can use non-blocking versions that<br />
perform operations in background, the cost for convenience is that they can't be<br />
undone.<br />
<br />
* <code>:copy &</code> - copy in background.<br />
* <code>:move &</code> - move in background.<br />
* <code>:delete &</code> - move to trash in background.<br />
* <code>:delete! &</code> - erase in background.<br />
<br />
Use <code>:jobs</code> command to background operations that are still active.<br />
Vifm also asks whether you sure about quitting if unfinished operations are<br />
running in background.<br />
<br />
= Basic configuration =<br />
<br />
== Setting options ==<br />
<br />
Options are changed with <code>:set</code> ''Command-line command''. There<br />
are several types of options (boolean, integer, string, list of strings, set of<br />
characters, enumerations), which support various operations, which are mostly<br />
what one would expect. <br />
<br />
Check manual pages, Vim-doc or plain text help that comes with Vifm for a full<br />
list of options (it's also available online, e.g.<br />
[http://vifm.info/manual.shtml#:set%20options man] or<br />
[http://vifm.info/vimdoc.shtml#vifm-set-options Vim-doc]).<br />
<br />
Some quick examples (try them out on command line):<br />
<br />
<source lang="vim"><br />
" boolean option<br />
set ignorecase<br />
" string option<br />
set rulerformat="%=%2l-%S [%L] "<br />
</source><br />
<br />
=== Syntax ===<br />
<br />
Generic syntax is:<br />
<br />
<source lang="vim"><br />
:set option[=value|?|&] option[=value|?|&] ...<br />
</source><br />
<br />
=== Checking value of an option ===<br />
<br />
State of non-boolean options can be queried interactively by specifying option<br />
on its own:<br />
<br />
<source lang="vim"><br />
:set history<br />
</source><br />
<br />
More generic way is to specify question mark (<code>?</code>) after option name:<br />
<br />
<source lang="vim"><br />
:set history?<br />
:set vicmd?<br />
</source><br />
<br />
=== Resetting an option ===<br />
<br />
If option value is messed up in some way, just use <code>optionname&</code> to<br />
reset it to default value. For example<br />
<br />
<source lang="vim"><br />
:set vicmd&<br />
</source><br />
<br />
resets value of <code>vicmd</code> to "vim".<br />
<br />
=== Syntax for changing boolean options ===<br />
<br />
Boolean options are the most common type and such options have some additional<br />
syntax:<br />
<br />
* <code>:set option</code> - enable <code>'option'</code>;<br />
* <code>:set nooption</code> - disable <code>'option'</code>;<br />
* <code>:set invoption</code> - toggle <code>'option'</code>;<br />
* <code>:set option!</code> - toggle <code>'option'</code>.<br />
<br />
=== Syntax for changing string options ===<br />
<br />
There are three ways of assigning string value of an option:<br />
<br />
* <code>:set option=value\ with\ spaces</code><br />
* <code>:set option='value with spaces'</code><br />
* <code>:set option="value with spaces"</code><br />
<br />
There is no big difference between single and double quotes.<br />
<br />
== Making options persistent ==<br />
<br />
There is no storage for options, instead Vifm uses regular text files where<br />
command-line commands can be used to alter configuration. Normally, it's<br />
<code>~/.vifm/vifmrc</code> file that contains configuration, but it's<br />
configurable and depends on operating system. Generally, appending new<br />
<code>:set</code> command to the end of <code>~/.vifm/vifmrc</code> should<br />
make option persistent, no special syntax, for example:<br />
<br />
<source lang="vim"><br />
set incsearch<br />
</source><br />
<br />
See [[Configuration model]].<br />
<br />
[[Category:Manual]]</div>Mb720https://wiki.vifm.info/index.php?title=Ideology&diff=485Ideology2019-04-07T13:06:04Z<p>Mb720: /* Vifm or ranger */ Condense text, improve grammar, phrasing.</p>
<hr />
<div>== Why Vifm ==<br />
<br />
=== Interesting capabilities ===<br />
<br />
* Works on all widely used operating systems.<br />
* Very easy to start if you grok Vim.<br />
* Can be used remotely over SSH.<br />
* Friendly to terminal multiplexers.<br />
* Low on resources.<br />
* Depends only on a few libraries (curses and regex).<br />
<br />
=== Vifm or ranger ===<br />
<br />
Vifm and [https://ranger.github.io/ ranger] follow different ideas in how to<br />
implement file management, vi-like behaviour, and user interface in general.<br />
<br />
What they have in common:<br />
<br />
* They both are file managers.<br />
* They both claim to have vi-like key bindings.<br />
<br />
Vifm does have ''Vi'' in its name for a reason and while ranger is a<br />
vi-like application, being such is not its main goal. Contrary to ranger, Vifm<br />
tries to be not just a "vi-like file manager", but rather "vim among file<br />
managers".<br />
<br />
It's difficult to compare ranger and Vifm, but here's an incomplete attempt:<br />
<br />
{| class="wikitable"<br />
|+Differences between Vifm and ranger<br />
! width="200px" | Vim-like characteristic<br />
! width="70px" | Vifm<br />
! width="70px" | ranger<br />
|-<br />
| Command line || Yes || Similar<br />
|-<br />
| Options || Yes || Partially<br />
|-<br />
| Completion || Yes || No<br />
|-<br />
| Bindings || Yes || Similar<br />
|-<br />
| Bindings configuration || Yes || Similar<br />
|-<br />
| Scripting || Partially || Limited<br />
|-<br />
| Window system || Partially || No<br />
|-<br />
| Modes || Yes || No<br />
|}<br />
<br />
Vifm has some features that are absent in ranger and vice versa,<br />
those are not listed if they are not very much related regarding how<br />
vi-like an application is.<br />
<br />
The bottom line is that Vifm aims to give Vim-addicted users a similar<br />
application for managing files and ranger is a nice file manager with vi-like<br />
features. These are different applications with different goals that do not<br />
compete with each other.<br />
<br />
== How not to use Vifm ==<br />
<br />
Do not use Vifm as your main application at the computer:<br />
<br />
* it's not a launcher of all kinds of applications, it's a file manager that supports file associations;<br />
* it's not an environment to spend your life in, it's one of many tools, interleave use of Vifm with Vim, shell and other applications.<br />
<br />
== When and how to use Vifm ==<br />
<br />
Main points:<br />
<br />
* Integrate Vifm within your system.<br />
** Run other applications from Vifm (e.g. Vim).<br />
** Launch Vifm from other applications (e.g. Vim, Mutt).<br />
** Use it as file picker from other applications.<br />
* Communicate data from Vifm to other applications and vice versa:<br />
** Pass list of files to other applications.<br />
** Process input of external tools.<br />
<br />
Generic examples:<br />
<br />
* If you know a way to do something more efficient in a shell, write a script and invoke it from Vifm or run external shell command if it's convenient, otherwise run shell and do it there.<br />
* If you know an application that fits better, create a command and/or script to run it in directory of current pane and maybe pass current selection to it.<br />
<br />
[[Category:Manual]]</div>Mb720https://wiki.vifm.info/index.php?title=Manual&diff=484Manual2019-04-07T12:48:37Z<p>Mb720: Fix spelling</p>
<hr />
<div>{{WorkInProgress}}<br />
<br />
See [[Contributing to This Wiki#Manual_Outline]] for outline of what is<br />
planned to have here eventually. At the moment chapters listed below are<br />
available.<br />
<br />
=== [[ Ideology ]] ===<br />
<br />
* Main principles on which Vifm is built and according to which it's developed.<br />
* Vifm as part of an environment.<br />
<br />
=== [[ Quickstart Tutorial ]] ===<br />
<br />
* Basic movement commands.<br />
* Opening files, starting applications, running external commands.<br />
* Basic configuration.<br />
<br />
=== [[ Configuration model ]] ===<br />
<br />
* Configuration files location and structure.<br />
* Affecting use of configuration files by Vifm.<br />
<br />
=== [[ Quitting Vifm ]] ===<br />
<br />
* Configuring Vifm to preserve its state across sessions.<br />
* How state conflicts are resolved.<br />
* Leaving Vifm started in special "file-picker" mode.<br />
<br />
=== [[ Command-line and alike modes ]] ===<br />
<br />
* Moving around and editing.<br />
* Command and argument completion.<br />
* Working with history.<br />
* Pasting runtime context into command-line.<br />
* Editing command-line externally.<br />
<br />
=== [[ Color schemes ]] ===<br />
<br />
* Creating new color schemes.<br />
* List of third-party color schemes.<br />
* Troubleshooting.<br />
<br />
[[Category:Manual]]</div>Mb720