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