Difference between revisions of "Configuration model"

From Vifm Wiki
Jump to: navigation, search
(Add section with short overview of :write command)
(Reloading configuration: Note that :restart doesn't rediscover configuration paths.)
 
(9 intermediate revisions by 2 users not shown)
Line 17: Line 17:
  
 
<code>vifmrc</code> consists of regular commands that can be entered on the
 
<code>vifmrc</code> consists of regular commands that can be entered on the
command line.
+
command line.  Any settings that are expected to be persistent for sure should
 +
be set in this file via appropriate command-line commands.
  
 
<code>vifminfo</code> is [[#Writing vifminfo manually|usually]] written
 
<code>vifminfo</code> is [[#Writing vifminfo manually|usually]] written
Line 27: Line 28:
 
state as it can to do not forget history items or other settings that user might
 
state as it can to do not forget history items or other settings that user might
 
want to reuse later.
 
want to reuse later.
 +
 +
==== Location of configuration files ====
 +
 +
There are two locations: global one (<code>/etc/vifm</code>, available since 0.8)
 +
meant to be shared among all users and local one, user specific.  Global
 +
<code>vifmrc</code> is loaded before the local one, so that the latter can redefine
 +
anything configured globally.  In contrast, available color schemes are searched
 +
first in local directory and then in global one.
 +
 +
Path to global configuration is fixed at compile-time.  Local
 +
configuration is located dynamically on startup according to rules described below.
 +
 +
First, home directory is determined by probing the following variants:
 +
# <code>$HOME</code> variable;
 +
# <code>$USERPROFILE</code> variable (on Windows only);
 +
# A combination of <code>$HOMEDRIVE</code> and <code>$HOMEPATH</code> variables (on Windows only).
 +
 +
Then, main local configuration directory (<code>$VIFM</code>) is looked up in
 +
these places:
 +
# <code>$VIFM</code> variable;
 +
# Directory of the executable file (on Windows only);
 +
# <code>~/.vifm</code> directory;
 +
# <code>$APPDATA/Vifm</code> directory (on Windows only);
 +
# <code>$XDG_CONFIG_HOME/vifm</code> directory (since 0.8);
 +
# <code>~/.config/vifm</code> directory.
 +
 +
The configuration file itself is discovered this way on the last step:
 +
# <code>$MYVIFMRC</code> variable;
 +
# <code>vifmrc</code> in the directory of the executable file (on Windows only);
 +
# <code>$VIFM/vifmrc</code> file.
 +
 +
In all cases outlined above the first item that points to existing directory/file is chosen.
 +
 +
The affect of this quite complicated procedure on versions can be summarized as
 +
follows:
 +
# Explicit configuration setup via environment variables has highest priority.
 +
# If local configuration doesn't exist, but <code>$XDG_CONFIG_HOME</code> directory does, XDG-like path will be chosen.  When <code>$XDG_CONFIG_HOME</code> points to inexistent path, <code>~/.vifm</code> is used.
 +
# If local configuration exists, it will be used as is, priority is as in ordered list above.
  
 
==== Writing <code>vifminfo</code> manually ====
 
==== Writing <code>vifminfo</code> manually ====
Line 43: Line 82:
 
<code>ZQ</code> normal mode shortcut can be used.
 
<code>ZQ</code> normal mode shortcut can be used.
  
==== Moving configuration files ====
+
==== Moving and finding configuration files ====
 +
 
 +
There are two environment variables that can be used in both cases:
 +
 
 +
* <code>$VIFM</code> points to main configuration directory (usually <code>~/.vifm/</code>);
 +
* <code>$MYVIFMRC</code> points to main configuration file (usually <code>~/.vifm/vifmrc</code>).
  
'''TODO:''' describe <code>$VIFM</code> environment variable.
+
These environment variables are valid inside Vifm and also can be used to
 +
configure it by setting some of them before running Vifm.
 +
 
 +
When <code>$MYVIFMRC</code> isn't set, it's made as
 +
<code>$VIFM/vifmrc</code> (exception for Windows: vifmrc in the same directory
 +
as <code>vifm.exe</code> has higher priority than <code>$VIFM/vifmrc</code>).
  
 
==== Skipping load of configuration files ====
 
==== Skipping load of configuration files ====
Line 61: Line 110:
 
==== Reloading configuration ====
 
==== Reloading configuration ====
  
'''TODO:''' describe <code>:restart</code> command.
+
Here are several scenarios when one might want to reload configuration:
 +
 
 +
* one of configuration files is changed;
 +
* something made in current session is better to be undone, but restarting Vifm in inconvenient;
 +
* testing of something (e.g. new command) that is better to repeat in same environment multiple times.
 +
 
 +
<code>:restart</code> command is there to make these usage scenarios possible. Note that it ''does '''not'''''
 +
rediscover paths to configuration files, so if you move them around, Vifm needs to be closed and started again
 +
for those changes to take effect.
 +
 
 +
It tries to repeat the same process that happens on startup, e.g.:
 +
 
 +
# Pretend it doesn't have much context (forget the one it has ''almost'' completely).
 +
# Reread <code>vifmrc</code> and <code>vifminfo</code> files.
 +
# Parse command-line arguments again to execute startup commands (<code>+cmd</code> or <code>-c cmd</code>).
 +
 
 +
For convenience reasons some parts of runtime state is not erased:
 +
 
 +
# Current directories of panes.
 +
# Cursor positions and top items of file lists.
 +
 
 +
These are minor things which are better to leave as they are to preserve current context from user's point of view.
 +
 
 +
===== <code>:restart</code> usage example =====
 +
 
 +
Here is definition of <kbd>,c</kbd> shortcut to edit configuration file:
 +
 
 +
<source lang="vim">
 +
nnoremap ,c :write | execute ':!%n${EDITOR:-vim} $MYVIFMRC' | restart<cr>
 +
</source>
 +
 
 +
It does the following:
 +
 
 +
# Saves current state to <code>vifminfo</code>.
 +
# Spawns editor (we don't want it to be detached from current console when inside terminal multiplexer, hence <code>%n</code> macro is used).
 +
# Reloads all configuration.
 +
 
 +
Alternatively one could use <code>:source</code> command instead:
 +
 
 +
<source lang="vim">
 +
nnoremap ,c :execute ':!%n${EDITOR:-vim} $MYVIFMRC' | source $MYVIFMRC<cr>
 +
</source>
 +
 
 +
It's fine too, but is somewhat less predictable because previous state is
 +
combined with the new one. Using <code>:restart</code> ensures that new
 +
settings are applied to much more sane environment that saves one from possible
 +
unexpected side effects of combining previous configuration with the new one.
 +
 
 +
[[Category:Manual]]

Latest revision as of 17:38, 9 November 2017

There are several commands that can be used to configure Vifm (e.g. :set, :colorscheme), but, if you restart it, all settings are reset to their previous values. To make changes permanent one needs to put them into configuration file or ask Vifm to store them automatically. Intent of this section is to describe things related to configuration.

Configuration files[edit]

Vifm follows the same configuration scheme as Vim and many other Unix applications use:

  • main configuration file should be edited manually as it is only read by the application and is never modified by it;
  • state of the application that is preserved across session is stored in separate file(s) and is not meant to be modified by a user.

For Vifm the first file is called vifmrc (located at ~/.vifm/vifmrc by default) and the second one is vifminfo (located at ~/.vifm/vifminfo).

vifmrc consists of regular commands that can be entered on the command line. Any settings that are expected to be persistent for sure should be set in this file via appropriate command-line commands.

vifminfo is usually written automatically. Which settings are written and applied on startup depends on 'vifminfo' option. Instead of just overwriting all settings, Vifm tries to merge previously stored state with the new one. Such strategy helps a lot in managing multiple instances running at the same time. New settings have higher priority than older ones, still Vifm tries to preserve as much of old state as it can to do not forget history items or other settings that user might want to reuse later.

Location of configuration files[edit]

There are two locations: global one (/etc/vifm, available since 0.8) meant to be shared among all users and local one, user specific. Global vifmrc is loaded before the local one, so that the latter can redefine anything configured globally. In contrast, available color schemes are searched first in local directory and then in global one.

Path to global configuration is fixed at compile-time. Local configuration is located dynamically on startup according to rules described below.

First, home directory is determined by probing the following variants:

  1. $HOME variable;
  2. $USERPROFILE variable (on Windows only);
  3. A combination of $HOMEDRIVE and $HOMEPATH variables (on Windows only).

Then, main local configuration directory ($VIFM) is looked up in these places:

  1. $VIFM variable;
  2. Directory of the executable file (on Windows only);
  3. ~/.vifm directory;
  4. $APPDATA/Vifm directory (on Windows only);
  5. $XDG_CONFIG_HOME/vifm directory (since 0.8);
  6. ~/.config/vifm directory.

The configuration file itself is discovered this way on the last step:

  1. $MYVIFMRC variable;
  2. vifmrc in the directory of the executable file (on Windows only);
  3. $VIFM/vifmrc file.

In all cases outlined above the first item that points to existing directory/file is chosen.

The affect of this quite complicated procedure on versions can be summarized as follows:

  1. Explicit configuration setup via environment variables has highest priority.
  2. If local configuration doesn't exist, but $XDG_CONFIG_HOME directory does, XDG-like path will be chosen. When $XDG_CONFIG_HOME points to inexistent path, ~/.vifm is used.
  3. If local configuration exists, it will be used as is, priority is as in ordered list above.

Writing vifminfo manually[edit]

Sometimes (e.g. before running external application that might affect configuration of Vifm) it's useful to write vifminfo file without closing Vifm. :write command is exactly for that.

Omitting writing of vifminfo[edit]

By default vifminfo is written on exit, i.e. :q[uit] is equal to :wq, this means that requested changes are saved automatically. Although it's quite convenient, sometimes one might want to drop current runtime state in favor of previously stored one or state of another instance. In such rare cases :quit! command-line command or ZQ normal mode shortcut can be used.

Moving and finding configuration files[edit]

There are two environment variables that can be used in both cases:

  • $VIFM points to main configuration directory (usually ~/.vifm/);
  • $MYVIFMRC points to main configuration file (usually ~/.vifm/vifmrc).

These environment variables are valid inside Vifm and also can be used to configure it by setting some of them before running Vifm.

When $MYVIFMRC isn't set, it's made as $VIFM/vifmrc (exception for Windows: vifmrc in the same directory as vifm.exe has higher priority than $VIFM/vifmrc).

Skipping load of configuration files[edit]

To ease diagnosing issues caused by configuration and provide a way to start Vifm with sane defaults --no-configs command-line option is supported.

Passing it to Vifm blocks reading of both vifmrc and vifminfo files. They can be read later via :restart command. You probably do not want to save vifminfo file after running Vifm in this mode, so consider reading related section of this page.

Reloading configuration[edit]

Here are several scenarios when one might want to reload configuration:

  • one of configuration files is changed;
  • something made in current session is better to be undone, but restarting Vifm in inconvenient;
  • testing of something (e.g. new command) that is better to repeat in same environment multiple times.

:restart command is there to make these usage scenarios possible. Note that it does not rediscover paths to configuration files, so if you move them around, Vifm needs to be closed and started again for those changes to take effect.

It tries to repeat the same process that happens on startup, e.g.:

  1. Pretend it doesn't have much context (forget the one it has almost completely).
  2. Reread vifmrc and vifminfo files.
  3. Parse command-line arguments again to execute startup commands (+cmd or -c cmd).

For convenience reasons some parts of runtime state is not erased:

  1. Current directories of panes.
  2. Cursor positions and top items of file lists.

These are minor things which are better to leave as they are to preserve current context from user's point of view.

:restart usage example[edit]

Here is definition of ,c shortcut to edit configuration file:

nnoremap ,c :write | execute ':!%n${EDITOR:-vim} $MYVIFMRC' | restart<cr>

It does the following:

  1. Saves current state to vifminfo.
  2. Spawns editor (we don't want it to be detached from current console when inside terminal multiplexer, hence %n macro is used).
  3. Reloads all configuration.

Alternatively one could use :source command instead:

nnoremap ,c :execute ':!%n${EDITOR:-vim} $MYVIFMRC' | source $MYVIFMRC<cr>

It's fine too, but is somewhat less predictable because previous state is combined with the new one. Using :restart ensures that new settings are applied to much more sane environment that saves one from possible unexpected side effects of combining previous configuration with the new one.