diff options
Diffstat (limited to 'man/feh.pre')
| -rw-r--r-- | man/feh.pre | 1778 |
1 files changed, 1341 insertions, 437 deletions
diff --git a/man/feh.pre b/man/feh.pre index e8bb8b1..ca64d37 100644 --- a/man/feh.pre +++ b/man/feh.pre @@ -13,71 +13,108 @@ . .Nm .Op Ar options -.Ar files or directories ... +.Op Cm -- +.Op Ar files | Ar directories | Ar URLs ... . . .Sh VERSION . -This manual documents feh $VERSION$ +This manual documents +.Nm +$VERSION$ . .Pp . -Compile-time switches: libcurl support $MAN_CURL$, Xinerama support -$MAN_XINERAMA$$MAN_DEBUG$ +Compile-time switches in this build: +. +.Bl -bullet -compact +. +.It +libcurl remote file support $MAN_CURL$ +. +.It +Xinerama multi-monitor support $MAN_XINERAMA$ +. +.It +libexif builtin EXIF reader $MAN_EXIF$ +. +.It +inotify-based auto-reload of changed files $MAN_INOTIFY$ +. +.It +libmagic $MAN_MAGIC$ +. +.El +. +$MAN_DEBUG$ . . .Sh DESCRIPTION . .Nm -is a mode-based image viewer. It is especially aimed at commandline users who -need a fast image viewer without huge GUI dependencies, though it can also be -started by -.Pq graphical -file managers to view an image. +is a light-weight, configurable and versatile image viewer. +It is aimed at command line users, but can also be started from graphical file +managers. +Apart from viewing images, it can compile text and thumbnail +listings, show (un)loadable files, set X11 backgrounds, and more. . .Pp . +Features include filelists, various image sorting modes, custom action scripts, +and image captions. +.Nm +can be controlled by configurable keyboard and mouse shortcuts, terminal +input and signals. +When no file arguments or filelists are specified and +.Cm --start-at +is not used, .Nm -supports filelists, various image sorting modes, image captions and more. -Configurable keyboard shortcuts are used to control it; the mouse is also -supported, but only required for very few actions. +displays all files in the current directory. . .Pp . +EXIF tags are supported either using exiv2 / exifgrep via +.Cm --info +.Pq see the Sx USAGE EXAMPLES No section , +or as a builtin feature by compiling .Nm -can also be used as wallpaper setter. +with exif=1. In this build of +.Nm , +builtin EXIF support is $MAN_EXIF$. . . .Sh MODES . .Nm -is based on various modes, which are selected at startup by comandline +is based on various modes, which are selected at startup by command line options. . .Pp . -Slideshow mode is the default. It opens one window and displays the first -image in it, the keyboard and mouse can be used to change slides -.Pq images . +Slideshow mode is the default. +It opens a window and displays the first image in it; +the slideshow position can be advanced +.Pq or otherwise changed +using keyboard and mouse shortcuts. In slideshow mode, images can be deleted either from the filelist or from the -disk, the new filelist can then be saved to the disk and reopened at a later +disk, a changed filelist can also be saved to the disk and reopened at a later time. +An image can also be read from stdin via +.Qq feh - . . .Pp . -Montage mode forms a montage from the filelist. The resulting image can be -viewed or saved, and its size can be limited by height, width or both. -. -.Pp -. -Collage mode is very similar to montage mode, except the images are distributed -randomly and may overlap each other. +Montage mode forms a montage from the filelist. +The resulting image can be viewed or saved, +and its size can be limited by height, width or both. . .Pp . -Index mode forms an index print from the filelist. Image thumbnails are shown -along with the filename, filesize and pixel size, printed using a truetype -font of your choice. The resulting image can be viewed or saved, and its size +Index mode forms an index print from the filelist. +Image thumbnails are shown along with the filename, +size and dimensions, printed using a truetype +font of your choice. +The resulting image can be viewed or saved, and its size can be limited by height, width or both. . .Pp @@ -88,33 +125,85 @@ the selected image in a new window. .Pp . Multiwindow mode shows images in multiple windows, instead of as a slideshow -in one window. Don't use with a large filelist ;) +in one window. +Don't use with a large filelist ;) . .Pp . -List mode doesn't display images. Outputs an -.Cm ls - No style -listing of the files in the filelist, including image info such as size, -pixels, type, etc. Customlist mode will display whatever image info you want, -in the format you choose. +List mode doesn't display images. +Instead, it outputs an +.Cm ls Ns No - Ns style +listing of the files in the filelist, including image info such as size, number +of pixels, type, etc. +There is also a Customlist mode which prints image info +in a custom format specified by a printf-like format string. . .Pp . .Nm can also list either all the loadable files in a filelist or all the -unloadable files. Useful for preening a directory. +unloadable files. +This is useful for preening a directory. . . +.Sh SUPPORTED FORMATS +. +.Nm +can open any format supported by imlib2, most notably jpeg, png, +pnm, tiff, and bmp. +The gif format is also supported, but only for static images. +In case of animations, only the first frame will be shown. +. +.Pp +. +When invoked with +.Cm --conversion-timeout Ar timeout +.Po +and a non-negative +.Ar timeout +value +.Pc , +.Nm +also has limited support for various other file types by means of external +conversion programs. +If the dcraw binary is available, +.Nm +will use it to display the thumbnails embedded into RAW files provided by +digital cameras and similar. +If the ImageMagick convert binary is available, +.Nm +will use it to load file types such as svg, xcf, and otf. +. +.Pp +. +.Pq optional feature, $MAN_MAGIC$ in this build +.Nm +can use libmagic to only pass image files to Imlib2. +When using +.Nm +with lots of non-image files +.Pq especially with Imlib2 version 1.6.x or 1.7.0 , +this can speed up the detection of non-image files significantly. +If you think that Imlib2 can load a file which +.Nm +has determined to be likely not an image, set the environment variable +.Qq FEH_SKIP_MAGIC +to pass all files directly to Imlib2, bypassing this check. +The environment variable's value does not matter, it just needs to be set. +. .Sh OPTIONS . .Bl -tag -width indent . -.It Cm -A , --action Oo Ar flag Oc Ns Ar action +.It Cm -A , --action Oo Ar flag Oc Ns Oo [ Ar title ] Oc Ns Ar action . -Specify a shell command as an action to perform on the image. In slideshow or -multiwindow mode, the action will be run when the action_0 key is pressed, in -list mode, it will be run for each file. In loadable/unloadable mode, it will -be run for each loadable/unloadable file, respectively. +Specify a shell command as an action to perform on the image. +In slideshow or multiwindow mode, the action will be run when +the action_0 key is pressed, in list mode, it will be run for each file. +In loadable/unloadable mode, it will be run for each loadable/unloadable +file, respectively. +In thumbnail mode, clicking on an image will cause the action to run instead +of opening the image. . .Pp . @@ -123,106 +212,223 @@ If is .Qq \&; , .Nm -will not switch to the next image after executing the action. +will reload the current image instead of switching to the next one +.Pq slideshow mode +or closing the window +.Pq multiwindow mode +after +executing the action. +. +If +.Ar [ title ] +is specified +.Pq note the literal Qo \&[ Qc and Qo ] Qc , +.Cm --draw-actions +will display +.Ar title +instead of +.Ar action +in the action list. +Note that +.Ar title +must not start with a space. +If it does, the action is handled as if it did not have a title. +This special case exists for backwards compatibility reasons +and makes sure that actions like +.Qq \&[ -L %F \&] && foo +still work. +. . .Pp . -The action will be executed by /bin/sh. Use format specifiers to refer to -image info. See +The action will be executed by /bin/sh. +Use format specifiers to refer to image info, see .Sx FORMAT SPECIFIERS -for examples. E.g. -.Qq feh -A "mv ~/images/%n" * . -In slideshow mode, the next image will be shown after running the action, in -multiwindow mode, the window will be closed. +for details. +Example usage: +.Qq feh -A Qo mv %F ~/images/%N Qc * . +. +.It Cm --action1 No .. Cm --action9 Oo Ar flag Oc Ns Oo [ Ar title ] Oc Ns Ar action +. +Extra actions which can be set and triggered using the appropriate number key. +. +.It Cm --auto-reload +. +.Pq optional feature, $MAN_INOTIFY$ in this build +automatically reload image when the underlying file changes. +Note that auto-reload +.Pq if enabled in the build +is on by default. +This option is only useful to re-enable auto-reload after it has been +disabled by a preceding +.Cm --reload=0 +option. +. +.Pp +. +Automatic reload is not supported in montage, index, or thumbnail mode. +. +.It Cm --auto-rotate +. +.Pq optional feature, $MAN_EXIF$ in this build +.Pq deprecated in favor of Imlib2's auto-orientation support +Automatically rotate images based on EXIF data. +Does not alter the image files. . -.It Cm --action1 No .. Cm --action9 +.Pp . -Extra actions which can be set and triggered using the appropiate number key. +Note that Imlib2 version 1.7.5+ performs auto-rotation by itself, so this option is obsolete on systems with Imlib2 version 1.7.5 or later. +.Nm +currently cannot detect this at runtime. . .It Cm -Z , --auto-zoom . -Zoom pictures to screen size in fullscreen -.Pq affected by Cm --stretch No and Cm --ignore-aspect . +Zoom pictures to screen size in fullscreen / fixed geometry mode. . .It Cm -x , --borderless . Create borderless windows. . +.It Cm --cache-size Ar size +. +Set imlib2 in-memory cache to +.Ar size +MiB. +A higher cache size can significantly improve performance especially for small +slide shows, however at the cost of increased memory consumption. +.Ar size +must be between 0 and 2048 MiB and defaults to 4. +. .It Cm -P , --cache-thumbnails . -Enable thumbnail caching in -.Pa ~/.thumbnails . -Only works with thumbnails <= 256x256 pixels. +Enable thumbnail caching. +Thumbnails are saved in +.Pa $XDG_CACHE_HOME/thumbnails , +which defaults to +.Pa ~/.cache/thumbnails . +Note that thumbnails are only cached if the configured thumbnail size does +not exceed 256x256 pixels. . .It Cm -K , --caption-path Ar path . -Path to directory containing image captions. This turns on caption viewing, -and if captions are found in +Path to directory containing image captions. +This turns on caption viewing, and if captions are found in .Ar path , which is relative to the directory of each image, they are overlayed on the -displayed image. E.g. with caption path +displayed image. +E.g. with caption path .Qq captions/ , and viewing image .Qq images/foo.jpg , the caption will be looked for in .Qq images/captions/foo.jpg.txt . . -.It Cm -c , --collage +.It Cm --conversion-timeout Ar timeout . -Enable collage mode. Collage mode is very similar to montage mode, except -the images are distributed randomly. -When using collage mode, you should also specify -.Cm --limit-width -and -.Cm --limit-height . -See also -.Sx MONTAGE MODE OPTIONS . +.Nm +can use ImageMagick to try converting unloadable files into a supported +file format. +As this can take a long time, it is disabled by default. +Set +.Ar timeout +to a non-negative value to enable it. +A positive value +specifies after how many seconds conversion attempts should be aborted, +zero causes +.Nm +to try indefinitely. +Negative values restore the default by disabling conversion altogether. +. +.It Cm --class Ar class +. +Set the X11 class hint to +.Ar class . +. +Default: feh . .It Cm -L , --customlist Ar format . -Use +Don't display images, print image info according to .Ar format -.Pq printf-like string containing image info specifiers -for list output. See +instead. +See .Sx FORMAT SPECIFIERS . . -.It Cm --cycle-once -. -Exit feh after one loop through the slideshow. -. .It Cm -G , --draw-actions . Draw the defined actions and what they do at the top-left of the image. . +.It Cm --draw-exif +. +.Pq optional feature, $MAN_EXIF$ in this build +display some EXIF information in the bottom left corner, similar to using +.Cm --info +with exiv2 / exifgrep. +. .It Cm -d , --draw-filename . -Draw the filename at the top-left of the image. +Draw the file name at the top-left of the image. +. +.It Cm --draw-tinted +. +Show overlay texts +.Pq as created by Cm --draw-filename No et al +on a semi-transparent background to improve their readability. +. +.It Cm --edit +. +Enable basic editing of files. +This makes rotation and mirroring +.Pq bound to Qo < Qc , Qo > Qc , Qo | Qc , and Qo _ Qc by default +change the underlying file and not just its displayed content. . .It Cm -f , --filelist Ar file . -This option is similar to the playlists used by music software. If +This option is similar to the playlists used by music software. +If .Ar file exists, it will be read for a list of files to load, in the order they appear. -The format is a list of image filenames, absolute or relative to the current -directory, one filename per line. If +The format is a list of image file names, absolute or relative to the current +directory, one file name per line. +. +.Pp +. +If .Ar file doesn't exist, it will be created from the internal filelist at the end of a -viewing session. This is best used to store the results of complex sorts +viewing session. +This is best used to store the results of complex sorts .Pq Cm -Spixels No for example -for later viewing. Any changes to the internal filelist +for later viewing. +. +.Pp +. +Any changes to the internal filelist .Pq such as deleting a file or it being pruned for being unloadable will be saved to .Ar file when .Nm -exits. You can add files to filelists by specifying them on the commandline +exits. +You can add files to filelists by specifying them on the command line when also specifying the list. . +.Pp +. +If +.Ar file +is +.Qq - , +.Nm +will read the filelist from its standard input. +. .It Cm -e , --font Ar font . -Set global font. Should be a truetype font, resident in the current directory -or the font directory, and should be defined in the form fontname/points, like -.Qq myfont/12 . +Set global font. +Should be a truetype font, resident in the current directory or the font +directory, and should be defined in the form fontname/size, like +.Qq yudit/12 +.Pq which is the default . . .It Cm -C , --fontpath Ar path . @@ -231,39 +437,65 @@ Specify as extra directory in which to search for fonts; can be used multiple times to add multiple paths. . +.It Cm --tap-zones +. +Enable tap zones for previous/next file in slide show mode +. .It Cm --force-aliasing . -Disable antialiasing for zooming, background setting etc. +Disable anti-aliasing for zooming, background setting etc. . .It Cm -I , --fullindex . -Same as Index mode, but you also get image size and dimensions printed -below each thumbnail. Enables +Same as index mode, but with additional information below the thumbnails. +Works just like +.Qq feh --index --index-info \&"\&%n\en\&%S\en\&%wx\&%h\&" . +Enables .Sx MONTAGE MODE OPTIONS . . +.Pp +. +Note: This option needs to load all images to calculate the dimensions of the +.Nm +window, so when using it with many files it will take a while before a +.Nm +window is visible. +Use +.Cm --preload +to get a progress bar. +. .It Cm -F , --fullscreen . Make the window fullscreen. Note that in this mode, large images will always be scaled down to fit the -screen, +screen, and .Cm --zoom Ar zoom only affects smaller images and never scales larger than necessary to fit the -screen size. The only exception is a +screen size. +The only exception is a .Ar zoom -of 100, in which case images will always be shown at 100% zoom, no matter -their dimensions. +of 100, in which case images will always be shown at 100% zoom. . -.It Cm -g , --geometry Ar width No x Ar height +.Pp . -Limit (and don't change) the window size. Takes an X-style geometry -.Ar string -like 640x480. -Note that larger images will be zoomed out to fit but you can see them at 1:1 -by clicking the zoom button. +When combined with +.Cm --thumbnails , +this option only affects images opened from the thumbnail overview. +The thumbnail list itself will still be windowed. . -.It Cm -h , --help +.It Cm -g , --geometry Ar width Cm x Ar height | Cm + Ar x Cm + Ar y | Ar width Cm x Ar height Cm + Ar x Cm + Ar y . -display help output and exit. +Use a fixed window size as specified in the X-style geometry +.Ar string , +e.g. 640x480. +An optional +x+y window offset can be specified. +Combine with +.Cm --scale-down +to scale down larger images like in fullscreen mode. +. +Note that this option does not enforce the window size; changing it by a tiling +WM or manually is still possible. +However, auto-resize remains disabled. . .It Cm -Y , --hide-pointer . @@ -272,61 +504,93 @@ Hide the pointer . .It Cm -B , --image-bg Ar style . -Use style as background for transparent image parts and the like. -Accepted values: white, black, default. +Use +.Ar style +as background for transparent image parts and the like. +Accepted values: default, checks, or an XColor +.Pq e.g. Qo black Qc or Qo #428bdd Qc . +Note that some shells treat the hash symbol as a special character, so you +may need to quote or escape it for the XColor code to work. +. +In windowed mode, the default is checks +.Pq a checkered background so transparent image parts are easy to see . +In fullscreen and background setting mode, +.Cm checks +is not accepted and the default is black. . .It Cm -i , --index . -Enable Index mode. Index mode is similar to montage mode, and accepts the -same options. It creates an index print of thumbails, printing the image -name beneath each thumbnail. Index mode enables certain other options, see -.Sx INDEX MODE OPTIONS +Enable Index mode. +Index mode is similar to montage mode, and accepts the same options. +It creates an index print of thumbnails, printing the image name beneath +each thumbnail. +Index mode enables certain other options, see +.Sx INDEX AND THUMBNAIL MODE OPTIONS and .Sx MONTAGE MODE OPTIONS . . -.It Cm --index-dim Ar bool -. -Toggle showing image dimensions in thumbnail/index mode. +.It Cm --info Oo Ar flag Oc Ns Ar command_line . -.It Cm --index-name Ar bool -. -Toggle showing the filename in thumbnail/index mode. -. -.It Cm --index-size Ar bool +Execute +.Ar command_line +and display its output in the bottom left corner of the image. +Can be used to display e.g. image dimensions or EXIF information. +Supports +.Sx FORMAT SPECIFIERS . . -Toggle showing the filesize in thumbnail/index mode. +If +.Ar flag +is set to +.Qo ; Qc , +the output will not be displayed by default, but has to be enabled by the +toggle_info key. . -.It Cm --info Ar commandline +.It Cm --insecure . -Execute -.Ar commandline -and display its output in the bottom left corner of the image. Can be used to -display e.g. image dimensions or EXIF information. Supports -.Sx FORMAT SPECIFIERS . +When viewing files with HTTPS, this option disables all certificate checks. +It allows images on sites with self-signed or expired certificates to be +opened, but is no more secure than plain HTTP. . .It Cm -k , --keep-http . When viewing files using HTTP, .Nm normally deletes the local copies after viewing, or, if caching, on exit. -This option prevents this so that you get to keep the local copies. -They will be in -.Pa /tmp -with -.Qq Nm -in the name. +This option permanently stores them on disk, either in the directory +specified by +.Cm --output-dir , +or in the current working directory. +. +.It Cm --keep-zoom-vp +. +When switching images, keep zoom and viewport settings +.Pq zoom level and X, Y offsets . .It Cm -l , --list . -Don't display images. Analyse them and display an +Don't display images. +Analyze them and display an .Xr ls 1 - No style -listing. Useful in scripts to hunt out images of a certain -size/resolution/type etc. +listing. +Useful in scripts to hunt out images of a certain size/resolution/type etc. . .It Cm -U , --loadable . -Don't display images. Just print out their names if imlib2 can successfully -load them. +Don't display images. +Just print out their names if imlib2 can successfully load them. +Returns false if at least one image failed to load. +When combined with +.Cm --action , +the specified action will be run for each loadable image. +. +.It Cm --max-dimension Ar width No x Ar height +. +Only show images with width <= +.Ar width +and height <= +.Ar height . +If you only care about one parameter, set the other to 0 +.Pq or a negative value . . .It Cm -M , --menu-font Ar font . @@ -335,17 +599,42 @@ Use .Pq truetype, with size, like Qq yudit/12 as menu font. . +.It Cm --min-dimension Ar width No x Ar height +. +Only show images with width >= +.Ar width +and height >= +.Ar height . +If you only care about one parameter, set the other to 0. +. .It Cm -m , --montage . -Enable montage mode. Montage mode creates a new image consisting of a grid of -thumbnails of the images in the filelist. When montage mode is selected, -certain other options become available. See +Enable montage mode. +Montage mode creates a new image consisting of a grid of thumbnails of the +images in the filelist. +When montage mode is selected, certain other options become available. +See .Sx MONTAGE MODE OPTIONS . . .It Cm -w , --multiwindow . -Disable slideshow mode. With this setting, instead of opening multiple files -in slideshow mode, multiple windows will be opened; one per file. +Disable slideshow mode. +With this setting, instead of opening multiple files in slideshow mode, +multiple windows will be opened; one per file. +. +.It Cm --no-conversion-cache +. +When loading images via HTTP, ImageMagick or dcraw, +.Nm +will only load/convert them once and re-use the cached file on subsequent +slideshow passes. +This option disables the cache. +It is also disabled when +.Cm --reload +is used. +Use it if you rely on frequently changing files loaded via one of these +sources. +Note that it will impair performance. . .It Cm --no-jump-on-resort . @@ -357,85 +646,239 @@ Don't load or show any menus. . .It Cm --no-screen-clip . -By default, window sizes are limited to the screen size. With this option, -windows will have the size of the image inside them. Note that they may -become very large this way, making them unmanageable in certain window -managers. +By default, window sizes are limited to the screen size. +With this option, windows will have the size of the image inside them. +Note that they may become very large this way, making them unmanageable +in certain window managers. . .It Cm --no-xinerama . -Disable Xinerama support. Only makes sense when you have Xinerama support -compiled in. +.Pq optional feature, $MAN_XINERAMA$ in this build +Disable Xinerama support. +. +.It Cm --on-last-slide Cm hold | Cm quit | Cm resume +. +Select behaviour when trying to select the next image on the last slide +.Pq or the previous image on the first slide +in a slide show. +. +.Pp +. +With +.Cm hold , +.Nm +will stop advancing images in this case and continue displaying the first/last +image, respectively. +This is intended for linear slide shows. +Behaviour is unspecified when using other navigation commands than previous +and next image. +. +.Pp +. +.Cm quit +will cause +.Nm +to quit when trying to advance past the last image in the slide show. This is +the behavior of the obsolete +.Cm --cycle-once +option. +. +.Pp +. +.Cm resume +is the default behaviour: On the last +.Pq first +image, +.Nm +will wrap around to the first +.Pq last +image. . .It Cm -j , --output-dir Ar directory . Save files to .Ar directory -.Pq only useful with -k +when using +.Cm --keep-http +or the save_image or save_filelist command. +By default, files are saved in the current working directory. . .It Cm -p , --preload . -Preload images. This doesn't mean hold them in RAM, it means run through -them and eliminate unloadable images first. Otherwise they will be removed -as you flick through. This also analyses the images to get data for use in -sorting, such as pixel size, type etc. A preload run will be automatically -performed if you specify one of these sort modes. +Preload images. +This doesn't mean hold them in RAM, it means run through them and eliminate +unloadable images first. +Otherwise they will be removed as you flick through. +This also analyses the images to get data for use in sorting, such as pixel +size, type etc. +A preload run will be automatically performed if you specify one of these +sort modes. . .It Cm -q , --quiet . -Don't report non-fatal errors for failed loads. Verbose and quiet modes are -not mutually exclusive, the first controls informational messages, the second -only errors. +Don't report non-fatal errors for failed loads. +Verbose and quiet modes are not mutually exclusive, the first controls +informational messages, the second only errors. . .It Cm -z , --randomize . When viewing multiple files in a slideshow, randomize the file list before displaying. +The list is re-randomized whenever the slideshow cycles (that is, transitions +from last to first image). . .It Cm -r , --recursive . -Recursively expand any directories in the commandline arguments +Recursively expand any directories in the command line arguments to the content of those directories, all the way down to the bottom level. . +.It Cm --no-recursive +. +Don't recursively expand any directories. +This is the default, but this option is useful to override themes containing +.Cm --recursive . +. .It Cm -R , --reload Ar int . Reload filelist and current image after .Ar int -seconds. Useful for viewing HTTP webcams or frequently changing directories. -.Pq Note that the filelist reloading is still experimental. +seconds. +Useful for viewing HTTP webcams or frequently changing directories. +.Pq Note that filelist reloading is still experimental. +Set to zero to disable any kind of automatic reloading. +. +.Pp +. +If an image is removed, +.Nm +will either show the next one or quit. +However, if an image still exists, but can no longer be loaded, +.Nm +will continue to try loading it. +. +.Pp +. +Setting this option causes inotify-based auto-reload to be disabled. +Reload is not supported in montage, index, or thumbnail mode. . .It Cm -n , --reverse . -Reverse the sort order. Use this to invert the order of the filelist. +Reverse the sort order. +Use this to invert the order of the filelist. E.g. to sort in reverse width order, use .Cm -nSwidth . . .It Cm -. , --scale-down . -When not in fullscreen: Scale images to screen size if they are too big. +Scale images to fit window geometry (defaults to screen size when no geometry +was specified). +Note that the window geometry is not updated when changing images at the moment. +This option is recommended for tiling window managers. +. +This option is ignored when in fullscreen and thumbnail list mode. +. +.Pp +. +In tiling environments, this also causes the image to be centered in the window. +. +.It Cm --scroll-step Ar count +. +Scroll +.Ar count +pixels whenever scroll_up, scroll_down, scroll_left or scroll_right is pressed. +Note that this option accepts negative numbers in case you need to reverse the +scroll direction. +See +.Sx KEYS CONFIG SYNTAX +for how to reverse it permanently. +Default: 20 . .It Cm -D , --slideshow-delay Ar float . For slideshow mode, wait .Ar float -seconds between automatically changing slides. Useful for presentations. +seconds between automatically changing slides. +Useful for presentations. Specify a negative number to set the delay .Pq which will then be Ar float No * (-1) , -but start feh in paused mode. +but start +.Nm +in paused mode. . .It Cm -S , --sort Ar sort_type . -The file list may be sorted according to image parameters. Allowed sort -types are: name, filename, width, height, pixels, size, format. For sort -modes other than name or filename, a preload run will be necessary, -causing a delay proportional to the number of images in the list. +Sort file list according to image parameters. +Allowed sort types are: +.Cm name , none , filename , dirname , mtime , width , height , pixels , size , format . +For sort modes other than +.Cm name , none , filename , dirname , +or +.Cm mtime , +a preload run is +necessary, causing a delay proportional to the number of images in the list. +. +.Pp +. +.Cm mtime +starts with the most recently modified image. +.Cm width , height , pixels +and +.Cm size +start with the smallest. +Use +.Cm --reverse +to sort by oldest or largest first. +. +.Pp +. +For +.Cm name , filename , +and +.Cm dirname +you can use +.Cm --version-sort +to sort numbers naturally, so that e.g. 10.jpg comes after 2.jpg. +. +.Pp . +.Cm none +is the default; you can specify it explicitly to discard a sort mode that has +been specified at an earlier point in the command line arguments. .It Cm -| , --start-at Ar filename . Start the filelist at .Ar filename . +If no other files or filelists were specified on the command line, +.Nm +will first load all files from the directory in which +.Ar filename +resides. +This way, it's possible to look at a specific image and use the next / prev +keys to browse through the directory. See -.Sx USAGE EXAMPLES . +.Sx USAGE EXAMPLES +for examples. +If +.Ar filename +is a remote URL and no files or filelists were specified, +.Nm +will show +.Ar filename +and not attempt to load additional files or directories. +. +.Pp +. +Note: If you use relative paths in your filelist, +.Ar filename +should also be a relative path. +If you use absolute paths, it should also be an absolute path. +. +If +.Nm +cannot find an exact match, it will compare basenames +.Pq filenames without the directory suffix . +This may lead to mismatches if several files in your filelist +have the same basename. . .It Cm -T , --theme Ar theme . @@ -443,7 +886,8 @@ Load options from config file with name .Ar theme - see .Sx THEMES CONFIG SYNTAX -for more info. Note that commandline options always override theme options. +for more info. +Note that command line options always override theme options. The theme can also be set via the program name .Pq e.g. with symlinks , so by default @@ -457,28 +901,38 @@ theme. Same as Index mode, but the thumbnails are clickable image launchers. Note that .Cm --fullscreen -does not affect the thumbnail window. It does, however, work for the image -windows launched from thumbnail mode. +and +.Cm --scale-down +do not affect the thumbnail window. +They do, however, work for image windows launched from thumbnail mode. Also supports +.Sx INDEX AND THUMBNAIL MODE OPTIONS +as well as .Sx MONTAGE MODE OPTIONS . . .It Cm -~ , --thumb-title Ar string . Set .Ar title -for windows opened from thumbnail mode. See also +for windows opened from thumbnail mode. +See also .Sx FORMAT SPECIFIERS . . .It Cm -^ , --title Ar title . -Set window title. Applies to all windows except those opened from thumbnail -mode. See +Set window title. +Applies to all windows except those opened from thumbnail mode. +See .Sx FORMAT SPECIFIERS . . .It Cm -u , --unloadable . -Don't display images. Just print out their names if imlib2 can NOT -successfully load them. +Don't display images. +Just print out their names if imlib2 can NOT successfully load them. +Returns false if at least one image was loadable. +When combined with +.Cm --action , +the specified action will be run for each unloadable file. . .It Cm -V , --verbose . @@ -488,11 +942,72 @@ output useful information, progress bars, etc. . output version information and exit. . -.It Cm --zoom Ar percent No | Cm max No | Cm fill +.It Cm --version-sort +. +When combined with +.Cm --sort name , --sort filename , +or +.Cm --sort dirname : +use natural sorting for file and directory names. +In this mode, filenames are sorted as an ordinary human would expect, e.g. +.Qq 2.jpg +comes before +.Qq 10.jpg . +Note that this option only has an effect when a sort mode is set using +.Cm --sort . +. +.It Cm --window-id Ar windowid +. +Draw to an existing X11 window by its ID +.Ar windowid . +This option is intended for use with software such as xcreensaver or +xsecurelock, which provide a window for other applications to draw into. +Unexpected things will happen if you specify a window belonging to software +which does not expect +.Nm +to draw into it or attempt to use options or keybindings which affect window +attributes, such as full-screen mode. +. +.It Cm --xinerama-index Ar monitor +. +.Pq optional feature, $MAN_XINERAMA$ in this build +Override +.Nm Ns No 's +idea of the active Xinerama monitor. +May be useful in certain circumstances where the window manager places the feh +window on Xinerama monitor A while +.Nm +assumes that it will be placed on monitor B. +. +.Pp +. +In background setting mode: When used with any option other than +.Cm --bg-tile : +Only set wallpaper on +.Ar monitor . +All other monitors will be filled black/white. +. +This is most useful in a Xinerama configuration with overlapping monitors. +For instance, assume you have two overlapping displays (index 0 and 1), +where index 0 is smaller. +To center a background on the display with index 0 and fill the extra space +on index 1 black/white, use +.Qq --xinerama-index 0 +when setting the wallpaper. +. +.Pp +. +Use +.Cm xrandr --listmonitors +to determine how Xinerama monitor IDs map to screens/monitors in your setup. +. +. +.It Cm --zoom Ar percent | Cm max | Cm fill . Zoom images by .Ar percent -when in full screen mode or when window geometry is fixed. When combined with +when in full screen mode or when window geometry is fixed. +When combined with .Cm --auto-zoom , zooming will be limited to the specified .Ar percent . @@ -502,76 +1017,24 @@ is like setting .Cm --auto-zoom , using .Cm fill -makes feh zoom the image like the +makes +.Nm +zoom the image like the .Cm --bg-fill mode. . -.El -. -. -.Sh BUTTON OPTIONS -. -.Bl -tag -width indent -. -.It Cm -0 , --reload-button Ar int -. -Set button to reload the image -.Pq default: 0 . -. -.It Cm -1 , --pan-button Ar int -. -Set button to pan the image -.Pq hold button down and move mouse to move the image . -When the mouse is not moved, advances to the next image in slideshow mode. -.Pq default: 1 , usually the left button . -. -.It Cm -2 , --zoom-button Ar int -. -Set button to enable zoom mode -.Pq default: 2 , usually the middle button . -. -.It Cm -3 , --menu-button Ar int -. -Set button to activate the menu. -.Pq default: 3 , usually the right button . -. -.It Cm --menu-ctrl-mask -. -Require CTRL+Button for menu activation. -. -.It Cm -4 , --prev-button Ar int -. -Set button to switch to the previous image in slideshow mode -.Pq default: 4 , usually Aq mousewheel up . -. -.It Cm -5 , --next-button Ar int -. -Set button to switch to the next image in slideshow mode -.Pq default: 5 , usually Aq mousewheel down . +.It Cm --zoom-step Ar percent . -.It Cm -8 , --rotate-button Ar int -. -Use CTRL+Button to rotate the current image -.Pq default : 2 . -. -.It Cm --no-rotate-ctrl-mask -. -Don't require CTRL+Button for rotation - just use the button. -. -.It Cm -9 , --blur-button Ar int -. -Use CTRL+Button for blurring -.Pq default : 1 . -. -.It Cm --no-blur-ctrl-mask +Zoom images in and out by +.Ar percent +.Pq default: 25 +when using the zoom keys and buttons. . -Don't require CTRL+Button for blurring - just use the button. .El . -. .Sh MONTAGE MODE OPTIONS . -These additional options can be used for collage, index, montage and +These additional options can be used for index, montage and .Pq partially thumbnail mode. . @@ -583,14 +1046,15 @@ When drawing thumbnails onto the background, set their transparency level to .Ar int .Pq 0 - 255 . . -.It Cm -b , --bg Ar file No | Cm trans +.It Cm -b , --bg Ar file | Cm trans . Use .Ar file -as background for your montage. With this option specified, the montage size -will default to the size of +as background for your montage. +With this option specified, the montage size will default to the size of .Ar file -if no size restrictions were specified. Alternatively, if +if no size restrictions were specified. +Alternatively, if .Ar file is .Qq trans , @@ -599,22 +1063,26 @@ the background will be made transparent. .It Cm -X , --ignore-aspect . By default, the montage thumbnails will retain their aspect ratios, while -fitting into thumb-width/-height. This options forces them to be the size set -by +fitting into thumb-width/-height. +This options forces them to be the size set by .Cm --thumb-width No and Cm --thumb-height . This will prevent any empty space in the final montage. . .It Cm -H , --limit-height Ar pixels . -Limit the height of the montage. These options can be used together to define -the image size exactly, or separately. If only one is specified, the other is -calculated from the number of files specified and the size of the thumbnails. -The default is to limit width to 800 pixels and calculate the height as -necessary. +Limit the height of the montage. . .It Cm -W , --limit-width Ar pixels . -Limit the width of the montage. +Limit the width of the montage, defaults to 800 pixels. +. +.Pp +. +If both +.Cm --limit-width No and Cm --limit-height +are specified, the montage will be exactly +.Ar width No x Ar height +pixels in dimensions. . .It Cm -o , --output Ar file . @@ -630,8 +1098,9 @@ without displaying it. .It Cm -s , --stretch . Normally, if an image is smaller than the specified thumbnail size, it will -not be enlarged. If this option is set, the image will be scaled up to fit -the thumnail size. Aspect ratio will be maintained unles +not be enlarged. +If this option is set, the image will be scaled up to fit the thumbnail size. +Aspect ratio will be maintained unless .Cm --ignore-aspect is specified. . @@ -643,91 +1112,162 @@ Set thumbnail height. . Set thumbnail width. . -.It Cm -J , --thumb-redraw Ar n -. -Only relevant for -.Cm --thumbnails : -Redraw thumbnail window every -.Ar n -images. In -.Nm -<= 1.5, the thumbnail image used to be redrawn after every computed thumbnail -.Pq so, it updated immediately . -However, since the redrawing takes quite long -.Pq especially for thumbnail mode on a large filelist , -this turned out to be a major performance penalty. -As a workaround, the thumbnail image is redrawn every 10th image now by -default. Set -.Ar n No = 1 -to get the old behaviour, -.Ar n No = 0 -will only redraw once all thumbnails are loaded. -. .El . . -.Sh INDEX MODE OPTIONS +.Sh INDEX AND THUMBNAIL MODE OPTIONS +. +In addition to +.Sx MONTAGE MODE OPTIONS +.Cm --alpha , --bg , --limit-height , --limit-width , --output , --output-only , +.Cm --thumb-height , --thumb-width , +the following options can be used. . .Bl -tag -width indent . +.It Cm --index-info Ar format +. +Show image information based on +.Ar format +below thumbnails in index / thumbnail mode. +See +.Sx FORMAT SPECIFIERS . +May contain newlines. +. +Use +.Qq --index-info '' +to display thumbnails without any info text +. +.Pp +. +Note: If you specify image-related formats +.Pq such as \&%w or \&%s , +.Nm +needs to load all images to calculate the dimensions of its own window. +So when using them with many files, it will take a while before a +.Nm +window becomes visible. +Use +.Cm --preload +to get a progress bar. +. .It Cm -@ , --title-font Ar font . Set font to print a title on the index, if no font is specified, no title will be printed. +. +.It Cm -J , --thumb-redraw Ar n +. +Redraw thumbnail window every +.Ar n +images while generating thumbnails. +Redrawing takes quite long, so the default is 10. +Set +.Ar n No = 1 +to update the thumbnail window immediately. +With +.Ar n No = 0 , +there will only be one redraw once all thumbnails are loaded. +. .El . . .Sh BACKGROUND SETTING . +In many desktop environments, .Nm -can also be used as a background setter. It will store the command line -necessary to set the background in -.Pa ~/.fehbg , -so to have your background restored everytime you start X, you can add -.Qq eval $(cat ~/.fehbg) +can also be used as a background setter. +Unless you pass the +.Cm --no-fehbg +option, it will write a script to set the current background to +.Pa ~/.fehbg . +So to have your background restored every time you start X, you can add +.Qq ~/.fehbg & to your X startup script -.Pq like Pa ~/.xinitrc . +.Pq such as Pa ~/.xinitrc . +Note that the commandline written to +.Pa ~/.fehbg +always includes the +.Cm --no-fehbg +option to ensure that it is not inadvertently changed by differences in +X11 screen layout or similar. +. +.Pp +. +Note that +.Nm +does not support setting the wallpaper of GNOME shell desktops. +In this environment, you can use +.Qq gsettings set org.gnome.desktop.background picture-uri file:/// Ns Ar path +instead. +. +.Pp +. +For +.Cm --bg-center , --bg-fill , +and +.Cm --bg-max , +you can use +.Cm --geometry +to specify an offset from one side of the monitor instead of centering the image. +Positive values will offset from the left/top side, negative values from the +bottom/right. ++0 and -0 are both valid and distinct values. . .Pp . Note that all options except .Cm --bg-tile -support Xinerama. So, if you have multiple screens connected and use e.g. +support Xinerama. +For instance, if you have multiple monitors connected and use e.g. .Cm --bg-center , .Nm -will center the image on each screen. You can use -.Cm --no-xinerama -to treat the whole X display as one screen. +will center or appropriately offset the image on each monitor. +You may even specify more than one file, in that case, the first file is set +on monitor 0, the second on monitor 1, and so on. +Use +.Cm xrandr --listmonitors +to determine how Xinerama monitor IDs map to screens / monitors in your setup. . .Pp . -The following options control how exactly the background is set. Each of them -takes exactly one file as argument. +Use +.Cm --no-xinerama +to treat the whole X display as one monitor when setting wallpapers. +You may also use +.Cm --xinerama-index +to use +.Nm +as a background setter for a specific monitor. . .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 black border +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 +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 black borders on one side. +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 +using borders. +But the aspect ratio is not preserved either . .It Cm --bg-tile . @@ -735,6 +1275,12 @@ 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 . . @@ -742,10 +1288,23 @@ the image in case it is too small for the screen . .Bl -tag -width indent . +.It %a +. +Information about slideshow state (playing/paused) +. .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 @@ -754,6 +1313,11 @@ Image height . 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 @@ -762,18 +1326,38 @@ Current mode . 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 . -.Nm +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 @@ -786,22 +1370,48 @@ Number of current file . Image width . +.\" .It %W +.\" . +.\" Window dimensions and offset as WxH+x+y +.\" .Pq X11 geometry format . +.\" Note that this is currently only properly updated when changing images; +.\" offsets for the first image after starting feh and after changing window +.\" geometry may be bogus. +. .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 two config files: +has three config files: .Pa themes -for theme definitions and +for theme definitions, .Pa keys -for key bindings. +for key bindings and +.Pa buttons +for mouse button bindings. It will try to read them from .Pa $XDG_CONFIG_HOME/feh/ , which @@ -814,12 +1424,13 @@ If the files are not found in that directory, it will also try All config files treat lines starting with a .Qq # character as comments. -Note that mid-line comments are not supported. +Comments at the end of a line are not supported. . . .Sh THEMES CONFIG SYNTAX . -This file allows the naming of option groups, called themes. +.Pa .config/feh/themes +allows the naming of option groups, called themes. . .Pp . @@ -833,19 +1444,40 @@ are the options which will be applied when the theme is used. . .Pp . -An example entry would be -.Qq imagemap -rVq --thumb-width 40 --thumb-height 30 . +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 . -You cane use this theme in two ways. Either call +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 +.Qc , or create a symbolic link to .Nm -with the name of the theme you want it to use. So from the example above: +with the name of the theme you want it to use. +For the example above, this would be .Qo ln -s `which .Nm @@ -858,17 +1490,21 @@ to use these options. .Pp . Note that you can split a theme over several lines by placing a backslash at -the end of a line, like in the shell. +the end of an unfinished line. +A single option-argument-pair must not span multiple lines. +A single line must not be longer than 1023 characters, but there's no upper +limit for the length of a theme. . .Pp . -You can combine these themes with commandline options. An example fehrc is -provided with a couple of cool example themes. +Command line options always override theme options. . . .Sh KEYS CONFIG SYNTAX . -This file defines the key bindings. It has entries of the form +.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 @@ -897,6 +1533,11 @@ 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 . @@ -906,16 +1547,46 @@ 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 . -In an image window, the following keys may be used -.Pq The strings in Bo square brackets Bc are the config action names : +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 , +arrow keys, return and backspace. +The Alt +.Pq Mod1 +modifier is also supported. . .Bl -tag -width indent . @@ -930,27 +1601,37 @@ Enable/Disable anti-aliasing . .It c Bq toggle_caption . -Caption entry mode. If +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 . +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 f Bq save_filelist +.It e Bq toggle_exif . -Save the current filelist to a unique filename +.Pq optional feature, $MAN_EXIF$ in this build +Toggle EXIF tag display +. +.It f Bq toggle_fullscreen +. +Toggle fullscreen +. +.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 +Pause/Continue the slideshow. +When it is paused, it will not automatically change slides based on .Cm --slideshow-delay . . .It i Bq toggle_info @@ -958,43 +1639,65 @@ change slides based on 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 L Bq save_filelist +. +Save the current filelist as +.Qq feh_PID_ID_filelist . +It is saved in the directory specified by +.Cm --output-dir , +if set, and in the current working directory otherwise. +. .It m Bq toggle_menu . -Show menu. Use the arrow keys and return to select items, +Show menu. +Use the arrow keys and return to select items, and .Aq escape to close the menu. . -.It n , Ao Space Ac , Ao Right Ac Bq next_img +.It n , Ao space Ac , Ao Right Ac Bq next_img . -Show next image +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 +.It p , Ao BackSpace Ac , Ao Left Ac Bq prev_img . -Show previous image +Show previous image. +Selects the previous image in thumbnail mode. . .It q , Ao Escape Ac Bq quit . -Quit feh +Quit +.Nm . .It r Bq reload_image . -Reload current image. Useful for webcams +Reload current image. +Useful for webcams . .It s Bq save_image . -Save the current image to a unique filename -. -.It v Bq toggle_fullscreen -. -Toggle fullscreen +Save the current image as +.Qq feh_PID_ID_FILENAME . +It is saved in the directory specified by +.Cm --output-dir , +if set, and in the current working directory otherwise. . .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 . @@ -1004,25 +1707,59 @@ Close current window . 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 images 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 +rotate the image 90 degrees (counter)clockwise. +. +.Pp +. +When +.Cm --edit +is used, this also rotates the image in the underlying file. +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 +Vertically flip image. +When +.Cm --edit +is used, this also flips the image in the underlying file +.Pq see above . . .It | Bq mirror . -In place editing - horizontal flip. -Again, see -.Xr jpegtran 1 -for more information. +Horizontally flip image. +When +.Cm --edit +is used, this also flips the image in the underlying file +.Pq see above . . .It 0 .. 9 Bq action_0 .. action_9 . @@ -1034,11 +1771,11 @@ Execute the corresponding action Run the command defined by .Cm --action . -.It Ao home Ac Bq jump_first +.It Ao Home Ac Bq jump_first . Show first image . -.It Ao end Ac Bq jump_last +.It Ao End Ac Bq jump_last . Show last image . @@ -1052,25 +1789,25 @@ Go backward ~5% of the filelist . .It + Bq reload_plus . -Increase reload delay +Increase reload delay by 1 second . .It - Bq reload_minus . -Decrease reload delay +Decrease reload delay by 1 second . -.It Ao delete Ac Bq remove +.It Ao Delete Ac Bq remove . Remove current file from filelist . -.It Ao CTRL+delete Ac Bq delete +.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 +.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 +.It Ao keypad Right Ac , Ao Ctrl+Right Ac Bq scroll_right . Scroll to the right . @@ -1078,31 +1815,32 @@ Scroll to the right . Scroll up . -.It Ao keypad down Ac , Ao Ctrl+Down Ac Bq scroll_down +.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. +Note that the scroll keys work without anti-aliasing for performance reasons; +hit the render key after scrolling to anti-alias the image. . -.It Aq Alt+Left +.It Aq Alt+Left Bq scroll_left_page . Scroll to the left by one page . -.It Aq Alt+Right +.It Aq Alt+Right Bq scroll_right_page . Scroll to the right by one page . -.It Aq Alt+Up +.It Aq Alt+Up Bq scroll_up_page . Scroll up by one page . -.It Aq Alt+Down +.It Aq Alt+Down Bq scroll_down_page . Scroll down by one page . -.It Ao keypad begin Ac Bq render +.It R, Ao keypad begin Ac Bq render . -Antialias the image +Anti-alias the image. +Opens the currently selected image in thumbnail mode. . .It Ao keypad + Ac , Ao Up Ac Bq zoom_in . @@ -1112,19 +1850,26 @@ Zoom in . Zoom out . -.It Ao keypad * Ac Bq zoom_default +.It *, Ao keypad * Ac Bq zoom_default . Zoom to 100% . -.It Ao keypad / Ac Bq zoom_fit +.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 feh menu: +The following keys bindings are used for the +.Nm +menu: . .Bl -tag -width indent . @@ -1148,30 +1893,129 @@ Highlight parent menu item . Highlight child menu item . -.It Ao Return Ac , Ao Space Ac Bq menu_select +.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 0 Ao cursor movement while not panning, zooming, or similar Ac +. +Does not have a default binding. +By binding it to +.Cm quit , +you can turn feh into a simple screensaver. +. +.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 . -When viewing an image, by default mouse button 1 pans -.Pq moves the image around +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 ; -button 2 zooms +.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 ; +.Pc and mouse button 3 opens the menu. . .Pp . -CTRL+Button 1 blurs or sharpens the image +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. +Ctrl+Button 2 rotates the image around the center point. . .Pp . @@ -1184,16 +2028,17 @@ 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. +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, +In slideshow and multiwindow mode, .Nm handles the following signals: . @@ -1201,146 +2046,204 @@ handles the following signals: . .It Dv SIGUSR1 . -Switch to next image +Slideshow mode: switch to next image; +reload current image if the slideshow consists of a single file. +Multiwindow mode: reload all images. . .It Dv SIGUSR2 . -Switch to previous image +Slideshow mode: switch to previous image; +reload current image if the slideshow consists of a single file. +Multiwindow mode: reload all images. . .El . . .Sh USAGE EXAMPLES . -Here are some examples of useful option combinations +Here are some examples of useful option combinations. +See also: +.Aq https://feh.finalrewind.org/examples/ . .Bl -tag -width indent . -.It feh /opt/images +.It feh ~/Pictures . -Show all images in /opt/images +Show all images in ~/Pictures . -.It feh -r /opt/images +.It feh -r ~/Pictures . -Recursively show all images found in /opt/images and subdirectories +Recursively show all images found in ~/Pictures and subdirectories . -.It feh -rSfilename /opt/images +.It feh -rSfilename --version-sort ~/Pictures . -Same as above, but sort by filename. By default, feh will show files in the -order it finds them on the hard disk, which is usually somewhat random. +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 /opt/images +.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 /opt/images +.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. +Same as above, but enable thumbnail caching and use a smaller font. . -.It feh -irFarial/14 -O index.jpg /opt/images +.It feh -irFarial/14 -O index.jpg ~/Pictures . -Make an index print of /opt/images 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 +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 /opt/images +.It feh --unloadable -r ~/Pictures . -Print all unloadable images in /opt/images, recursively +Print all unloadable images in ~/Pictures, recursively . -.It feh -w /opt/images/holidays +.It feh -f by_width -S width --reverse --list \&. . -Open each image in /opt/images/holidays in its own window +Write a list of all images in the directory to by_width, sorted by width +.Pq widest images first . -.It feh -FD5 -Sname /opt/images/presentation +.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 /opt/images +.It feh -rSwidth -A Qo mv %F ~/images/\&%N Qc ~/Pictures . -View all images in /opt/images and below, sorted by width, move an image to +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 \&. +.It feh --start-at ~/Pictures/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 +View all images in ~/Pictures, starting with foo.jpg. +All other images are still in the slideshow and can be viewed normally . -.It feh --start-at foo.jpg * +.It feh --start-at ~/Pictures/foo.jpg ~/Pictures . -Same as above +Same as above. . -.It feh --info \&"exifgrep '\&(Model\&|DateTimeOriginal\&|FNumber\&|ISO\&|Flash\&)' '%f' \&| cut -d \&. -f 4-\&" \&. +.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-dimension 1000x800 +. +Recursively remove all images with dimensions below or equal to 1000x800 pixels +from the current directory. +. +.It feh -L '%w %h %f' \&| awk '{ if \&($1 > $2\&) { print $0 } }' \&| cut -d ' ' -f 3- \&| feh -f - +. +Show landscape pictures +.Pq image width greater than height +in the current directory. +. .El . . .Sh DEPENDENCIES . +When +.Cm --edit +is used, .Nm -requires the +needs the .Cm jpegtran -binary +and +.Cm jpegexiforient +binaries .Pq usually distributed in Qo libjpeg-progs Qc or similar -for lossless rotation. +for lossless JPEG rotation. . .Pp . -To view images from URLs such as http://, you need +To view images from URLs such as "http://", .Nm -compiled with libcurl support (enabled by default). See the -.Sx VERSION -section. +must be compiled with libcurl support. +It is $MAN_CURL$ in this build. +. . +.Sh KNOWN BUGS . -.Sh BUGS +Imlib2 releases prior to 1.7.4 are unable to load gif, tiff, and webp images +if the filename does not end with gif, tiff, or webp, respectively. +Notably, this means that feh is unable to show gif, tiff, and webp images from +stdin or network URLs on systems using an Imlib2 version older than 1.7.4. +. +.Pp . -Xinerama support does not really work on Xinerama screens != 0. Set -.Ev XINERAMA_SCREEN -to the correct number as a workaround. +Imlib2 releases 1.7.5+ automatically rotate images based on their EXIF tags. +When combined with the +.Cm --auto-rotate +option, this causes images to be rotated twice and end up in an incorrect orientation. +As a workaround, do not use +.Cm --auto-rotate +on systems with Imlib2 version 1.7.5 or later. +.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 --conversion-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 +. +While loading images using libcurl, +.Nm +will not react to key or mouse actions. . .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. . .Ss REPORTING BUGS . If you find a bug, please report it to -.Aq derf@finalrewind.org +.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. +.Aq https://github.com/derf/feh/issues . . .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 +steps to reproduce the bug and, if necessary, images to reproduce it. +Note that +.Nm +is a hobby project, so bug reports may be addressed with significant delays. . . .Sh LICENSE . -Copyright (C) 1999, 2000 by Tom Gilbert (and various contributors). -Copyright (C) 2010 by Daniel Friesel (and even more contributors). +Copyright (C) 1999, 2000 by Paul Duncan. +Copyright (C) 1999, 2000 by Tom Gilbert and contributors. +Copyright (C) 2010-2025 by Birte Kristina Friesel and contributors. . .Pp . @@ -1362,14 +2265,15 @@ used. . 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. +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 +Current developer: Birte Friesel .Aq derf@finalrewind.org . .Pp @@ -1381,5 +2285,5 @@ Tom Gilbert . .Pp . -See also: -http://feh.finalrewind.org +Website: +https://feh.finalrewind.org |