Getting Started
===============
You can start vimiv from any application launcher with its .desktop file or
from the command line using the ``vimiv`` command. If any valid image paths are
given, the images are opened directly, otherwise the library is opened.
To close vimiv press ``q`` or type in ``:q`` in the command line.
Vimiv is, as one would expect from an application with vim-like keybindings,
completely keyboard driven. To get you started some of the most important
keybindings for controlling vimiv are explained below. For a complete list of
them take a look at the ``keys.conf`` file which is generated upon startup in
``$XDG_CONFIG_HOME/vimiv/`` or open the keybindings pop-up by running ``:keybindings``.
You can run ``:help topic`` to get some additional information on a specific topic.
Completion will guide you through the different options like commands and settings.
Basics
------
Depending on how you started ``vimiv`` you will begin in image or in library
mode. To enter another mode the ``g`` key is combined with the first letter of
the mode. Therefore:
* ``gi`` enters image mode
* ``gl`` enters library mode
* ``gt`` enters thumbnail mode and
* ``gm`` enters manipulate mode.
To toggle a mode the same logic applies with the ``t`` key instead of the ``g``
key.
.. note:: Image mode cannot be toggled as it is the "normal" mode of vimiv
As in vim what a keybinding does depends on the mode in which it is ran.
Image
-----
Scrolling the image is done with ``hjkl``. The next image is selected with
``n``, the previous one with ``p``. To show the first/last image use ``gg/G``.
Zooming in and out is done with ``+/-``. To fit the image to the current window
size use ``w``. ``e/E`` fit horizontally/vertically.
To start playing a slideshow use ``ss``. The delay can be decreased/increased
using ``sh/sl``.
Library
-------
The behaviour of the library is similar to the one of the file manager
`ranger `_.
You can scroll down/up with ``j/k``. ``gg/G`` select the first/last file in the
list. ``h`` opens the parent directory while ``l`` selects the current file. If
the file is a directory, it is opened in the library. An image is displayed to
the right of the library. Pressing ``l`` again closes the library and focuses
the image.
Thumbnail
---------
Once again ``hjkl`` and ``gg/G`` work as expected.
It is also possible to vary the size of the thumbnails with the ``+/-`` keys.
To open the selected thumbnail in image mode, press ````.
Image Editing
-------------
Images can be rotated with the ``<`` and ``>``, flipped with the ``|`` and ``_`` keys.
These changes are automatically applied to the file as long as the ``image.autowrite``
setting is true. An image is deleted with ``x``. This actually moves the image to the
trash directory specified by the freedesktop standard, by default $XDG_DATA_HOME/Trash.
For additional editing enter manipulate mode with ``gm``. Here you can change brightness
and contraste as well as hue, saturation and lightness. To increase the current
manipulation by 1/10 use ``k/K`` or ``l/L``. Correspondingly, to decrease it by 1/10 use
``j/J`` or ``h/H``. To set it to a specific value you can press ``[count]gg``.
Navigating between the manipulations in the current tab is done with ``n/p``. To get to
the next/previous tab press ``/``.
When you are satisfied and want to apply the changes, accept with ````. If you
prefer to leave discarding the changes, press ````.
.. _commandline:
Command Line
------------
Similar to many keyboard centric programs, vimiv includes a simple commmand
line to run commands. It is opened with ``:`` and closed with ```` to
run a command and ```` to discard it.
When entering the command line a completion window for vimiv’s commands is
displayed. Pressing ```` starts cycling through the completions.
```` cycles in inverse direction.
Opening new paths from here is done using the ``:open`` command. Path
completion is also supported.
Unix style pattern matching including ``*`` and ``?`` can be used. Recursive matching is
also possible using ``**`` but please note that this can become slow in large directory
trees. In addition ``%`` gets replaced with the currently selected file, ``%f`` by all
files in the current filelist and ``%m`` by all marked images. See :ref:`marks_and_tags`
for more information on this.
Prepending a command with ``!`` lets vimiv interpret the command as an external
command. This becomes especially useful in combination with the patterns described
above.
Example: ``:!gimp %`` opens the currently selected image in gimp.
External commands can be "piped to vimiv" by appending the ``|`` char to the
command. The output of the command is then parsed by vimiv. If the first line
out output is a directory, it is opened in the library. If it is a valid image,
all lines are checked for images and these are opened.
Example: ``:!find ~/Images -ctime -5 -type f |`` opens all files in
``~/Images`` younger than five days.
.. note::
External commands started with ``!`` do not run in a sub-shell for security and
performance reasons. This means that redirection with ``|`` or ``>`` as well as any
other shell specifics do not work. If you require to run with a sub-shell, use the
``:spawn`` command instead.
Command line history is saved to ``$XDG_DATA_HOME/vimiv/history``. History can
be navigated and searched through using the ``p/n`` and
``/`` keys.
Count
-----
Some commands support passing a ``[count]`` as repetition or step. To pass a
count in the command line, prepend ``[count]`` to the command, e.g. ``:5next``.
Pressing any number appends it to the current ``[count]`` and the next command
is run with the stored ``[count]``.
.. _marks_and_tags:
Marks and Tags
--------------
Images supports the concept of marking images using the ``:mark`` command. As an
argument it takes an arbitrary number of paths and supports pattern matching as
described in :ref:`commandline`. The current image is therefore marked using ``:mark %``
which is bound to ``m`` by default. Working with the set of marked images is done by
referencing them in the command line with ``%m``.
Example: ``:!mogrify -rotate 90 %m`` rotates all marked images by 90 degrees using the
``mogrify`` command from `imagemagick `_.
All current marks are removed by running ``:mark-clear``. The last set of cleared marks
can be restored using ``:mark-restore``.
To keep a selection of marks and assigning them a name, tags can be used. New tags are
created using ``:tag-write my_fancy_tag``. Grouping into sub-directories is possible by
naming the tags accordingly, e.g. ``:tag-write favourites/2017``. Under the hood, this
creates a tag file in ``$XDG_DATA_HOME/vimiv/tags`` which is a simple text file that can
be parsed as usual.
.. hint::
When writing to a tag that exists, all currently marked images that are not in
the tag yet are appended to it.
Loading a tag is done with ``:tag-load my_fancy_tag`` which loads all images from the
tag into the list of marked images. To then open them in image mode we can refer to them
with ``%m`` in the open command: ``:open %m``. As this is such a frequent usecase, there
is the ``tag-open my_fancy_tag`` command which is equivalent, but saves one command.
Deleting a tag is done with ``:tag-delete my_fancy_tag``.
.. warning:: This deletes the tag permanently with no option to restore it!
What Next?
----------
You may want to check out how to :doc:`configure ` vimiv
or take a look at a :doc:`description of all commands `.