feh.pre

For instance, if you have multiple screens connected and use e.g.
.Cm --bg-center ,
.Nm
will center or appropriately offset the image on each screen.
You may even specify more than one file, in that case, the first file is set
on screen 0, the second on screen 1, and so on.
.
.Pp
.
Use
.Cm --no-xinerama
to treat the whole X display as one screen when setting wallpapers.
You may also use
.Cm --xinerama-index
to use
.Nm
as a background setter for a specific screen.
.
.Bl -tag -width indent
.
.It Cm --bg-center
.
Center the file on the background.
If it is too small, it will be surrounded by a border as specified by
.Cm --image-bg .
.
.It Cm --bg-fill
.
Like
.Cm --bg-scale ,
but preserves aspect ratio by zooming the image until it fits.
Either a horizontal or a vertical part of the image will be cut off
.
.It Cm --bg-max
.
Like
.Cm --bg-fill ,
but scale the image to the maximum size that fits the screen with borders on one side.
The border color can be set using
.Cm --image-bg .
.
.It Cm --bg-scale
.
Fit the file into the background without repeating it, cutting off stuff or
using borders.
But the aspect ratio is not preserved either
.
.It Cm --bg-tile
.
Tile
.Pq repeat
the image in case it is too small for the screen
.
.It Cm --no-fehbg
.
Do not write a
.Pa ~/.fehbg
file
.
.El
.
.
.Sh FORMAT SPECIFIERS
.
.Bl -tag -width indent
.
.It %f
.
Image path/filename
.
.It %F
.
Escaped image path/filename
.Pq for use in shell commands
.
.It %g
.
w,h window dimensions in pixels (mnemonic: geometry)
.
.It %h
.
Image height
.
.It %l
.
Total number of files in filelist
.
.It %L
.
Temporary copy of filelist.
Multiple uses of %L within the same format string will return the same copy.
.
.It %m
.
Current mode
.
.It %n
.
Image name
.
.It \&%N
.
Escaped image name
.
.It %o
.
x,y offset of top-left image corner to window corner in pixels
.
.It %p
.
Number of image pixels
.
.It \&%P
.
Number of image pixels in human-readable format with k/M
.Pq kilopixels / megapixels
suffix
.
.It %r
.
Image rotation.
A half right turn equals pi.
.
.It %s
.
Image size in bytes
.
.It %S
.
Human-readable image size
.Pq kB / MB
.
.It %t
.
Image format
.
.It %u
.
Number of current file
.
.It %w
.
Image width
.
.It %v
.
.Nm
version
.
.It \&%V
.
Process ID
.
.It %z
.
Current image zoom, rounded to two decimal places
.
.It %Z
.
Current image zoom, higher precision
.
.It %%
.
A literal %
.
.El
.
.
.Sh CONFIGURATION
.
.Nm
has three config files:
.Pa themes
for theme definitions,
.Pa keys
for key bindings and
.Pa buttons
for mouse button bindings.
It will try to read them from
.Pa $XDG_CONFIG_HOME/feh/ ,
which
.Pq when XDG_CONFIG_HOME is unset
defaults to
.Pa ~/.config/feh/ .
If the files are not found in that directory, it will also try
.Pa /etc/feh/ .
.Pp
All config files treat lines starting with a
.Qq #
character as comments.
Note that mid-line comments are not supported.
.
.
.Sh THEMES CONFIG SYNTAX
.
.Pa .config/feh/themes
allows the naming of option groups, called themes.
.
.Pp
.
It takes entries of the form
.Qq Ar theme options ... ,
where
.Ar theme
is the name of the entry and
.Ar options
are the options which will be applied when the theme is used.
.
.Pp
.
Note that the option parser does not behave like a normal shell: filename
expansion and backslash escape sequences are not supported and passed to
feh's option parser as-is.
However, quoting of arguments is respected and can be used for arguments
with whitespace.
.
So, the sequence
.Qq --info Qq foo bar
works as intended
.Pq that is, it display the string Qq foo bar ,
whereas the option string
.Qq --info foo\e bar
will only display
.Qq foo\e
and complain about the file bar not existing.
Please keep this in mind when writing theme files.
.
.Pp
.
An example entry is
.Qq imagemap -rVq --thumb-width 40 --thumb-height 30 --index-info \&'%n\en\&%wx\&%h\&' .
.
.Pp
.
You can use this theme in two ways.
Either call
.Qo
.Nm
-Timagemap *.jpg
.Qc ,
or create a symbolic link to
.Nm
with the name of the theme you want it to use.
For the example above, this would be
.Qo
ln -s `which
.Nm
` ~/bin/imagemap
.Qc .
Now just run
.Qq imagemap *.jpg
to use these options.
.
.Pp
.
Note that you can split a theme over several lines by placing a backslash at
the end of an unfinished line.
.
.Pp
.
Command line options always override theme options.
.
.
.Sh KEYS CONFIG SYNTAX
.
.Pa .config/feh/keys
defines key bindings.
It has entries of the form
.Qq Ar action Op Ar key1 Op Ar key2 Op Ar key3 .
.
.Pp
.
Each
.Ar key
is an X11 keysym name as shown by
.Xr xev 1 ,
like
.Qq Delete .
It may optionally start with modifiers for things like Control, in which case
.Ar key
looks like
.Ar mod Ns No - Ns Ar keysym
.Po
for example
.Qq C-Delete
for Ctrl+Delete or
.Qq C-1-Delete
for Ctrl+Alt+Delete
.Pc
.
.Pp
.
Available modifiers are
.Ar C No for Control ,
.Ar S No for Shift and
.Ar 1 , 4 No for Mod1 and Mod4 .
To match an uppercase letter like
.Qq S
instead of
.Qq s ,
the Shift modifier is not required.
.
.Pp
.
Specifying an
.Ar action
without any keys unbinds it (i.e. the default bindings are removed).
.
.Pp
.
.Em Note :
Do not use the same keybinding for multiple actions.
When binding an action to a new key
.Pq or mouse button ,
make sure to unbind it from its previous action, if present.
.Nm
does not check for conflicting bindings, so their behaviour is undefined.
.
.Pp
.
For a list of the
.Ar action
names, see
.Sx KEYS .
Note that not all of the key names used there correspond to X11 keysyms.
Most notably, page up
.Pq Prior / Page_Up ,
page down
.Pq Next / Page_Down
and the keypad keys
.Pq KP_*
do not.
.
.
.Sh KEYS
.
The following actions and default key bindings can be used in an image window.
.Pq The strings in Bo square brackets Bc are the config action names .
.
If
.Nm
is running inside a terminal and its standard input is not used for images or
filelists, key input from the terminal is also accepted.
However, terminal input support is currently limited to most alphanumeric
characters
.Pq 0-9 a-z A-Z and some more ,
return and backspace.
.
.Bl -tag -width indent
.
.It a Bq toggle_actions
.
Toggle actions display
.Pq see Cm --draw-actions
.
.It A Bq toggle_aliasing
.
Enable/Disable anti-aliasing
.
.It c Bq toggle_caption
.
Caption entry mode.
If
.Cm --caption-path
has been specified, then this enables caption editing.
The caption at the bottom of the screen will turn yellow and can be edited.
Hit return to confirm and save the caption, or escape to cancel editing.
Note that you can insert an actual newline into the caption using
.Aq Ctrl+return .
.
.It d Bq toggle_filenames
.
Toggle filename display
.Pq see Cm --draw-filename
.
.It e Bq toggle_exif
.
.Pq optional feature, $MAN_EXIF$ in this build
Toggle EXIF tag display
.
.It f Bq save_filelist
.
Save the current filelist as
.Qq feh_PID_ID_filelist
.
.It g Bq toggle_fixed_geometry
.
Enable/Disable automatic window resize when changing images.
.
.It h Bq toggle_pause
.
Pause/Continue the slideshow.
When it is paused, it will not automatically change slides based on
.Cm --slideshow-delay .
.
.It i Bq toggle_info
.
Toggle info display
.Pq see Cm --info
.
.It k Bq toggle_keep_vp
.
Toggle zoom and viewport keeping.
When enabled,
.Nm
will keep zoom and X, Y offset when switching images.
.
.It m Bq toggle_menu
.
Show menu.
Use the arrow keys and return to select items,
.Aq escape
to close the menu.
.
.It n , Ao space Ac , Ao Right Ac Bq next_img
.
Show next image.
Selects the next image in thumbnail mode.
.
.It o Bq toggle_pointer
.
Toggle pointer visibility
.
.It p , Ao BackSpace Ac , Ao Left Ac Bq prev_img
.
Show previous image.
Selects the previous image in thumbnail mode.
.
.It q , Ao Escape Ac Bq quit
.
Quit
.Nm
.
.It r Bq reload_image
.
Reload current image.
Useful for webcams
.
.It s Bq save_image
.
Save the current image as
.Qq feh_PID_ID_FILENAME
.
.It v Bq toggle_fullscreen
.
Toggle fullscreen
.
.It w Bq size_to_image
.
Change window size to fit current image size
.Pq plus/minus zoom, if set .
In scale-down and fixed-geometry mode, this also updates the window size limits.
.
.It x Bq close
.
Close current window
.
.It z Bq jump_random
.
Jump to a random position in the current filelist
.
.It Z Bq toggle_auto_zoom
.
Toggle auto-zoom.
.
.It \&[, \&] Bq prev_dir, next_dir
.
Jump to the first image of the previous or next sequence of images sharing
a directory name in the current filelist.
Use --sort dirname if you would like to ensure that all images in a directory
are grouped together.
.
.It < , > Bq orient_3 , orient_1
.
In place editing - rotate the image 90 degrees (counter)clockwise.
The rotation is lossless, but may create artifacts in some image corners when
used with JPEG images.
Rotating in the reverse direction will make them go away.
See
.Xr jpegtran 1
for more about lossless JPEG rotation.
.
.Em Note:
.Nm
assumes that this feature is used to normalize image orientation.
For JPEG images, it will unconditionally set the EXIF orientation
tag to 1
.Pq Qq 0,0 is top left
after every rotation.
See
.Xr jpegexiforient 1
for details on how to change this flag.
.
.It _ Bq flip
.
In place editing - vertical flip
.
.It | Bq mirror
.
In place editing - horizontal flip
.
.It 0 .. 9 Bq action_0 .. action_9
.
Execute the corresponding action
.Pq 0 = Cm --action , No 1 = Cm --action1 No etc.
.
.It Ao Return Ac Bq action_0
.
Run the command defined by
.Cm --action
.
.It Ao Home Ac Bq jump_first
.
Show first image
.
.It Ao End Ac Bq jump_last
.
Show last image
.
.It Ao page up Ac Bq jump_fwd
.
Go forward ~5% of the filelist
.
.It Ao page down Ac Bq jump_back
.
Go backward ~5% of the filelist
.
.It + Bq reload_plus
.
Increase reload delay by 1 second
.
.It - Bq reload_minus
.
Decrease reload delay by 1 second
.
.It Ao Delete Ac Bq remove
.
Remove current file from filelist
.
.It Ao Ctrl+Delete Ac Bq delete
.
Remove current file from filelist and delete it
.
.It Ao keypad Left Ac , Ao Ctrl+Left Ac Bq scroll_left
.
Scroll to the left
.
.It Ao keypad Right Ac , Ao Ctrl+Right Ac Bq scroll_right
.
Scroll to the right
.
.It Ao keypad up Ac , Ao Ctrl+Up Ac Bq scroll_up
.
Scroll up
.
.It Ao keypad Down Ac , Ao Ctrl+Down Ac Bq scroll_down
.
Scroll down.
Note that the scroll keys work without anti-aliasing for performance reasons,
hit the render key after scrolling to antialias the image.
.
.It Aq Alt+Left Bq scroll_left_page
.
Scroll to the left by one page
.
.It Aq Alt+Right Bq scroll_right_page
.
Scroll to the right by one page
.
.It Aq Alt+Up Bq scroll_up_page
.
Scroll up by one page
.
.It Aq Alt+Down Bq scroll_down_page
.
Scroll down by one page
.
.It R, Ao keypad begin Ac Bq render
.
Antialias the image.
Opens the currently selected image in thumbnail mode.
.
.It Ao keypad + Ac , Ao Up Ac Bq zoom_in
.
Zoom in
.
.It Ao keypad - Ac , Ao Down Ac Bq zoom_out
.
Zoom out
.
.It *, Ao keypad * Ac Bq zoom_default
.
Zoom to 100%
.
.It /, Ao keypad / Ac Bq zoom_fit
.
Zoom to fit the window size
.
.It ! Bq zoom_fill
.
Zoom to fill the window size like
.Cm --bg-fill
.
.El
.
.Ss MENU KEYS
.
The following keys bindings are used for the
.Nm
menu:
.
.Bl -tag -width indent
.
.It Ao Escape Ac Bq menu_close
.
Close the menu
.
.It Ao Up Ac Bq menu_up
.
Highlight previous menu item
.
.It Ao Down Ac Bq menu_down
.
Highlight next menu item
.
.It Ao Left Ac Bq menu_parent
.
Highlight parent menu item
.
.It Ao Right Ac Bq menu_child
.
Highlight child menu item
.
.It Ao Return Ac , Ao space Ac Bq menu_select
.
Select highlighted menu item
.
.El
.
.
.Sh BUTTONS CONFIG SYNTAX
.
.Pa .config/feh/buttons .
This works like the keys config file: the entries are of the form
.Qq Ar action Op Ar binding .
.
.Pp
.
Each
.Ar binding
is a button number.
It may optionally start with modifiers for things like Control, in which case
.Ar binding
looks like
.Ar mod Ns No - Ns Ar button
.Pq for example "C-1" for Ctrl + Left button .
.
.Pp
.
.Em Note :
Do not use the same button for multiple actions.
.Nm
does not check for conflicting bindings, so their behaviour is undefined.
.
Either unbind the unwanted action, or bind it to another unused button.
.
The order in which you bind / unbind does not matter, though.
.
.Pp
.
For the available modifiers, see
.Sx KEYS CONFIGURATION SYNTAX .
.
.
.Ss BUTTONS
.
In an image window, the following buttons may be used
.Pq The strings in Bo square brackets Bc are the config action names .
Additionally, all actions specified in the
.Sx KEYS
section can also be bound to a button.
.
.Bl -tag -width indent
.
.It unbound Bq reload
.
Reload current image
.
.It 1 Ao left mouse button Ac Bq pan
.
pan the current image
.
.It 2 Ao middle mouse button Ac Bq zoom
.
Zoom the current image
.
.It 3 Ao right mouse button Ac Bq toggle_menu
.
Toggle menu
.
.It 4 Ao mousewheel down Ac Bq prev_img
.
Show previous image
.
.It 5 Ao mousewheel up Ac Bq next_img
.
Show next image
.
.It Ctrl+1 Bq blur
.
Blur current image
.
.It Ctrl+2 Bq rotate
.
Rotate current image
.
.It unbound Bq zoom_in
.
Zoom in
.
.It unbound Bq zoom_out
.
Zoom out
.
.
.El
.
.
.Sh MOUSE ACTIONS
.
Default Bindings:
When viewing an image, mouse button 1 pans the image
.Pq moves it around
or, when only clicked, moves to the next image
.Pq slideshow mode only .
Quick drags with less than 2px of movement per axis will be treated as clicks
to aid graphics tablet users.
.
Mouse button 2 zooms
.Po click and drag left->right to zoom in, right->left to zoom out, click once
to restore zoom to 100%
.Pc
and mouse button 3 opens the menu.
.
.Pp
.
Ctrl+Button 1 blurs or sharpens the image
.Pq drag left to blur, right to sharpen ;
Ctrl+Button 2 rotates the image around the center point.
.
.Pp
.
A note about pan and zoom modes:
In pan mode, if you reach a window border but haven't yet panned to the end of
the image,
.Nm
will warp your cursor to the opposite border so you can continue panning.
.
.Pp
.
When clicking the zoom button and immediately releasing it, the image will be
back at 100% zoom.
When clicking it and moving the mouse while holding the button down, the zoom
will be continued at the previous zoom level.
The zoom will always happen so that the pixel on which you entered the zoom mode
remains stationary.
So, to enlarge a specific part of an image, click the zoom button on that part.
.
.
.Sh SIGNALS
.
In slideshow mode,
.Nm
handles the following signals:
.
.Bl -tag -width indent
.
.It Dv SIGUSR1
.
Switch to next image
.
.It Dv SIGUSR2
.
Switch to previous image
.
.El
.
.
.Sh USAGE EXAMPLES
.
Here are some examples of useful option combinations.
See also:
.Aq http://feh.finalrewind.org/examples/
.
.Bl -tag -width indent
.
.It feh ~/Pictures
.
Show all images in ~/Pictures
.
.It feh -r ~/Pictures
.
Recursively show all images found in ~/Pictures and subdirectories
.
.It feh -rSfilename --version-sort ~/Pictures
.
Same as above, but sort naturally.
By default, feh will show files in the string order of their names, meaning e.g.
.Qq foo 10.jpg
will come before
.Qq foo 2.jpg .
In this case, they are instead ordered as a human would expect.
.
.It feh -t -Sfilename -E 128 -y 128 -W 1024 ~/Pictures
.
Show 128x128 pixel thumbnails, limit window width to 1024 pixels.
.
.It feh -t -Sfilename -E 128 -y 128 -W 1024 -P -C /usr/share/fonts/truetype/ttf-dejavu/ -e DejaVuSans/8 ~/Pictures
.
Same as above, but enable thumbnail caching in ~/.thumbnails and use a smaller
font.
.
.It feh -irFarial/14 -O index.jpg ~/Pictures
.
Make an index print of ~/Pictures and all directories below it, using 14 point
Arial to write the image info under each thumbnail.
Save the image as index.jpg and don't display it, just exit.
Note that this even works without a running X server
.
.It feh --unloadable -r ~/Pictures
.
Print all unloadable images in ~/Pictures, recursively
.
.It feh -f by_width -S width --reverse --list \&.
.
Write a list of all images in the directory to by_width, sorted by width
.Pq widest images first
.
.It feh -w ~/Pictures/holidays
.
Open each image in ~/Pictures/holidays in its own window
.
.It feh -FD5 -Sname ~/Pictures/presentation
.
Show the images in .../presentation, sorted by name, in fullscreen,
automatically change to the next image after 5 seconds
.
.It feh -rSwidth -A Qo mv %F ~/images/\&%N Qc ~/Pictures
.
View all images in ~/Pictures and below, sorted by width, move an image to
~/image/image_name when enter is pressed
.
.It feh --start-at ./foo.jpg \&.
.
View all images in the current directory, starting with foo.jpg.
All other images are still in the slideshow and can be viewed normally
.
.It feh --start-at foo.jpg *
.
Same as above
.
.It feh --info \&"exifgrep '\&(Model\&|DateTimeOriginal\&|FNumber\&|ISO\&|Flash\&)' %F \&| cut -d \&. -f 4-\&" \&.
.
Show some EXIF information, extracted by exifprobe/exifgrep
.
.It feh --action 'rm %F' -rl --max-dim 1000x800
.
Recursively remove all images with dimensions below or equal to 1000x800 pixels
from the current directory.
.
.El
.
.
.Sh DEPENDENCIES
.
.Nm
requires the
.Cm jpegtran
and
.Cm jpegexiforient
binaries
.Pq usually distributed in Qo libjpeg-progs Qc or similar
for lossless rotation.
.
.Pp
.
To view images from URLs such as http://, you need
.Nm
compiled with libcurl support (enabled by default).
See the
.Sx VERSION
section.
.
.
.Sh BUGS
.
.Pp
.
On systems with giflib 5.1.2,
.Nm
may be unable to load gif images.
For affected mips, mipsel and arm devices, gif support is completely
broken, while on x86 / x86_64 gifs can usually only be loaded if they are
the first image in the filelist.
This appears to be a bug in giflib,
see
.Aq https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=813729
for details.
Workaround: Use
.Cm --magick-timeout 5
.Pq or some other positive value
to load gifs with imagemagick instead, or downgrade to giflib 5.1.1, or
upgrade to giflib 5.1.4.
.
.Pp
.
Thumbnail mode is somewhat inefficient, and because of that not nearly as fast
as it could be.
.
.Pp
.
.Cm --scale-down
does not take window decorations into account and may therefore make the
window slightly too large.
.
.Pp
.
When enabled,
.Cm --magick-timeout
may clutter
.Pa /tmp
with temporary files produced by ImageMagick.
This happens whenever an image is not loaded due to the conversion taking
longer than the specified timeout.
.
.Ss REPORTING BUGS
.
If you find a bug, please report it to
.Aq derf+feh@finalrewind.org
or via
.Aq http://github.com/derf/feh/issues .
You are also welcome to direct any feh-related comments/questions/... to #feh
on irc.oftc.net.
.
.Pp
.
Please include the feh version
.Aq the output of Qq feh --version ,
steps to reproduce the bug and, if necessary, images to reproduce it.
.
.
.Sh FUTURE PLANS
.
Plans for the following releases:
.
.Bl -bullet -compact
.
.It
Make zoom options more intuitive
.
.El
.
.
.Sh LICENSE
.
Copyright (C) 1999, 2000 by Paul Duncan.
Copyright (C) 1999, 2000 by Tom Gilbert (and various contributors).
Copyright (C) 2010-2016 by Daniel Friesel (and even more contributors).
.
.Pp
.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
.
.Pp
.
The above copyright notice and this permission notice shall be included in
all copies of the Software and its documentation and acknowledgment shall be
given in the documentation and software packages that this Software was
used.
.
.Pp
.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
.
.Pp
.
Current developer: Daniel Friesel
.Aq derf@finalrewind.org
.