1RANGER(1) ranger manual RANGER(1)
2
6 ranger - visual file manager
7
9 ranger [--version] [--help] [--debug] [--clean] [--cachedir=directory]
10 [--confdir=directory] [--datadir=directory] [--copy-config=which]
11 [--choosefile=target] [--choosefiles=target] [--choosedir=target]
12 [--selectfile=filepath] [--show-only-dirs] [--list-unused-keys]
13 [--list-tagged-files=tag] [--profile] [--cmd=command] [path ...]
14
16 ranger is a console file manager with VI key bindings.
17
19 This manual contains instructions on how to use and configure ranger.
20 Inside ranger, you can press ? for a list of key bindings, commands or
22 settings.
23 The README contains install instructions.
25 The file HACKING.md contains guidelines for code modification.
27 The directory doc/configs contains configuration files. They are
29 usually installed to /usr/share/doc/ranger/config and can be obtained
30 with ranger's --copy-config option.
31 The directory examples contains reference implementations for ranger
33 plugins, sample configuration files and some programs for integrating
34 ranger with other software. They are usually installed to
35 /usr/share/doc/ranger/examples.
36 The man page of rifle(1) describes the functions of the file opener
38 The section LINKS of this man page contains further resources.
40
42 path ... Each path will be opened in a tab and if the path is a
43 file it will be selected. Omitting this is equivalent to
44 providing the current directory.
45
47 -d, --debug Activate the debug mode: Whenever an error occurs, ranger
48 will exit and print a full traceback. The default
49 behavior is to merely print the name of the exception in
50 the statusbar/log and try to keep running.
51 -c, --clean Activate the clean mode: ranger will not access or
53 create any configuration files nor will it leave any
54 traces on your system. This is useful when your
55 configuration is broken, when you want to avoid clutter,
56 etc.
57 --cachedir=dir
59 Change the cache directory of ranger from $XDG_CACHE_HOME
60 or ~/.cache/ranger to "dir".
61 -r dir, --confdir=dir
63 Change the configuration directory of ranger from
64 $XDG_CONFIG_HOME or ~/.config/ranger to "dir".
65 --datadir=dir Change the data directory of ranger from $XDG_DATA_HOME
67 or ~/.local/share/ranger to "dir".
68 --copy-config=file
70 Create copies of the default configuration files in your
71 local configuration directory. Existing ones will not be
72 overwritten. Possible values: all, commands,
73 commands_full, rc, rifle, scope.
74 Note: You may want to disable loading of the global
76 configuration files by exporting
77 RANGER_LOAD_DEFAULT_RC=FALSE in your environment. See
78 also: FILES, ENVIRONMENT
79 --copy-config=commands will copy only a small sample
81 configuration file with a thoroughly commented example.
82 It is recommended to keep this file tidy to avoid getting
83 defunct commands on ranger upgrades. The full default
84 commands.py can be copied with
85 --copy-config=commands_full, but that file will be
86 ignored by ranger and serves only as a reference for
87 making your own commands.
88 --choosefile=targetfile
90 Allows you to pick a file with ranger. This changes the
91 behavior so that when you open a file, ranger will exit
92 and write the absolute path of that file into targetfile.
93 --choosefiles=targetfile
95 Allows you to pick multiple files with ranger. This
96 changes the behavior so that when you open a file, ranger
97 will exit and write the absolute paths of all selected
98 files into targetfile, adding one newline after each
99 filename.
100 --choosedir=targetfile
102 Allows you to pick a directory with ranger. When you
103 exit ranger, it will write the last visited directory
104 into targetfile.
105 --selectfile=targetfile
107 Open ranger with targetfile selected. This is a legacy
108 option, superseded by the behavior for the POSITIONAL
109 ARGUMENTS.
110 --show-only-dirs
112 Display only the directories. May be used in conjunction
113 with --choosedir=targetfile.
114 --list-unused-keys
116 List common keys which are not bound to any action in the
117 "browser" context. This list is not complete, you can
118 bind any key that is supported by curses: use the key
119 code returned by "getch()".
120 --list-tagged-files=tag
122 List all files which are tagged with the given tag.
123 Note: Tags are single characters. The default tag is "*"
124 --profile Print statistics of CPU usage on exit.
126 --cmd=command Execute the command after the configuration has been
128 read. Use this option multiple times to run multiple
129 commands.
130 --version Print the version and exit.
132 -h, --help Print a list of options and exit.
134
136 This part explains how certain parts of ranger work and how they can be
137 used efficiently.
138 TAGS
140 Tags are single characters which are displayed left of a filename. You
141 can use tags however you want. Press "t" to toggle tags and "ut" to
142 remove any tags of the selection. The default tag is an Asterisk ("*"),
143 but you can use any tag by typing "<tagname>.
144 PREVIEWS
146 By default, only text files are previewed, but you can enable external
147 preview scripts by setting the option "use_preview_script" and
148 "preview_files" to true.
149 This default script is %rangerdir/data/scope.sh. It contains more
151 documentation and calls to the programs lynx and elinks for html,
152 highlight for text/code, img2txt for images, atool for archives,
153 pdftotext or mutool for PDFs and mediainfo for video and audio files.
154 Install these programs (just the ones you need) and scope.sh will
156 automatically use them.
157 Independently of the preview script, there is a feature to preview
159 images by drawing them directly into the terminal. To enable this
160 feature, set the option "preview_images" to true and enable one of the
161 image preview modes:
162 w3m
164 This does not work over ssh, requires certain terminals (tested on
166 "xterm" and "urxvt") and is incompatible with tmux, although it works
167 with screen.
168 To enable this feature, install the program "w3m" and set the option
170 "preview_images_method" to w3m.
171 iTerm2
173 This only works in iTerm2 compiled with image preview support, but
175 works over ssh.
176 To enable this feature, set the option "preview_images_method" to
178 iterm2.
179 This feature relies on the dimensions of the terminal's font. By
181 default, a width of 8 and height of 11 are used. To use other values,
182 set the options "iterm2_font_width" and "iterm2_font_height" to the
183 desired values.
184 terminology
186 This only works in terminology. It can render vector graphics, but
188 works only locally.
189 To enable this feature, set the option "preview_images_method" to
191 terminology.
192 urxvt
194 This only works in urxvt compiled with pixbuf support. Does not work
196 over ssh.
197 Essentially this mode sets an image as a terminal background
199 temporarily, so it will break any previously set image background.
200 To enable this feature, set the option "preview_images_method" to
202 urxvt.
203 urxvt-full
205 The same as urxvt but utilizing not only the preview pane but the whole
207 terminal window.
208 To enable this feature, set the option "preview_images_method" to
210 urxvt-full.
211 kitty
213 This only works on Kitty. It requires PIL (or pillow) to work. Allows
215 remote image previews, for example in an ssh session.
216 To enable this feature, set the option "preview_images_method" to
218 kitty.
219 SELECTION
221 The selection is defined as "All marked files IF THERE ARE ANY,
222 otherwise the current file." Be aware of this when using the :delete
223 command, which deletes all files in the selection.
224 You can mark files by pressing <Space>, v, etc. A yellow Mrk symbol at
226 the bottom right indicates that there are marked files in this
227 directory.
228 MACROS
230 Macros can be used in commands to abbreviate things.
231 %f the highlighted file
233 %d the path of the current directory
234 %s the selected files in the current directory
235 %t all tagged files in the current directory
236 %c the full paths of the currently copied/cut files
237 %p the full paths of selected files
238 The macros %f, %d, %p, and %s also have upper case variants, %F, %D,
240 %P, and %S, which refer to the next tab. To refer to specific tabs,
241 add a number in between. (%7s = selection of the seventh tab.)
242 %c is the only macro which ranges out of the current directory. So you
244 may "abuse" the copying function for other purposes, like diffing two
245 files which are in different directories:
246 Yank the file A (type yy), move to the file B, then type
248 @diff %c %f
249 Macros for file paths are generally shell-escaped so they can be used
251 in the "shell" command.
252 Additionally, if you create a key binding that uses <any>, a special
254 statement which accepts any key, then the macro %any (or %any0, %any1,
255 %any2, ...) can be used in the command to get the key that was pressed.
256 The macro %rangerdir expands to the directory of ranger's python
258 library, you can use it for something like this command:
259 alias show_commands shell less %rangerdir/config/commands.py
260 %confdir expands to the directory given by --confdir.
262 %datadir expands to the directory given by --datadir.
264 The macro %space expands to a space character. You can use it to add
266 spaces to the end of a command when needed, while preventing editors to
267 strip spaces off the end of the line automatically.
268 To write a literal %, you need to escape it by writing %%.
270 BOOKMARKS
272 Type m<key> to bookmark the current directory. You can re-enter this
273 directory by typing `<key>. <key> can be any letter or digit. Unlike
274 vim, both lowercase and uppercase bookmarks are persistent.
275 Each time you jump to a bookmark, the special bookmark at key ` will be
277 set to the last directory. So typing "``" gets you back to where you
278 were before.
279 Bookmarks are selectable when tabbing in the :cd command.
281 Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same.
283 RIFLE
285 Rifle is the file opener of ranger. It can be used as a standalone
286 program or a python module. It is located at ranger/ext/rifle.py. In
287 contrast to other, more simple file openers, rifle can automatically
288 find installed programs so it can be used effectively out of the box on
289 a variety of systems.
290 It's configured in rifle.conf through a list of conditions and
292 commands. For each line the conditions are checked and if they are
293 met, the respective command is taken into consideration. By default,
294 simply the first matching rule is used. In ranger, you can list and
295 choose rules by typing "r" or simply by typing "<rulenumber><enter>".
296 If you use rifle standalone, you can list all rules with the "-l"
297 option and pick a rule with "-p <number>".
298 The rules, along with further documentation, are contained in
300 ranger/config/rifle.conf.
301 FLAGS
303 Flags give you a way to modify the behavior of the spawned process.
304 They are used in the commands ":open_with" (key "r") and ":shell" (key
305 "!").
306 f Fork the process. (Run in background)
308 c Run the current file only, instead of the selection
309 r Run application with root privilege (requires sudo)
310 t Run application in a new terminal window
311 There are some additional flags that can currently be used only in the
313 "shell" command: (for example ":shell -w df")
314 p Redirect output to the pager
316 s Silent mode. Output will be discarded.
317 w Wait for an Enter-press when the process is done
318 By default, all the flags are off unless specified otherwise in the
320 rifle.conf configuration file. You can specify as many flags as you
321 want. An uppercase flag negates the effect: "ffcccFsf" is equivalent
322 to "cs".
323 The terminal program name for the "t" flag is taken from the
325 environment variable $TERMCMD. If it doesn't exist, it tries to
326 extract it from $TERM, uses "x-terminal-emulator" as a fallback, and
327 then "xterm" if that fails.
328 Examples: ":open_with c" will open the file that you currently point
330 at, even if you have selected other files. ":shell -w df" will run
331 "df" and wait for you to press Enter before switching back to ranger.
332 PLUGINS
334 ranger's plugin system consists of python files which are located in
335 ~/.config/ranger/plugins/ and are imported in alphabetical order when
336 starting ranger. A plugin changes rangers behavior by overwriting or
337 extending a function that ranger uses. This allows you to change
338 pretty much every part of ranger, but there is no guarantee that things
339 will continue to work in future versions as the source code evolves.
340 Adding new commands via a plugin as simple as specifying them like you
342 would do in the commands.py.
343 There are some hooks that are specifically made for the use in plugins.
345 They are functions that start with hook_ and can be found throughout
346 the code.
347 grep 'def hook_' -r /path/to/rangers/source
349 Also try:
351 pydoc ranger.api
353 Note that you should NOT simply overwrite a function unless you know
355 what you're doing. Instead, save the existing function and call it
356 from your new one. This way, multiple plugins can use the same hook.
357 There are several sample plugins in the /usr/share/doc/ranger/examples/
358 directory, including a hello-world plugin that describes this
359 procedure.
360
362 Key bindings are defined in the file %rangerdir/config/rc.conf. Check
363 this file for a list of all key bindings. You can copy it to your
364 local configuration directory with the --copy-config=rc option.
365 Many key bindings take an additional numeric argument. Type 5j to move
367 down 5 lines, 2l to open a file in mode 2, 10<Space> to mark 10 files.
368 This list contains the most useful bindings:
370 MAIN BINDINGS
372 h, j, k, l Move left, down, up or right
373 ^D or J, ^U or K
375 Move a half page down, up
376 H, L Move back and forward in the history
378 gg Move to the top
380 G Move to the bottom
382 [, ] Move up and down in the parent directory.
384 ^R Reload everything
386 F Toggle freeze_files setting. When active (indicated by a
388 cyan FROZEN message in the status bar), directories and
389 files will not be loaded, improving performance when all
390 the files you need are already loaded. This does not
391 affect file previews, which can be toggled with zI. Also
392 try disabling the preview of directories with zP.
393 ^L Redraw the screen
395 i Inspect the current file in a bigger window.
397 E Edit the current file in $VISUAL otherwise $EDITOR
399 otherwise "vim"
400 S Open a shell in the current directory
402 ? Opens this man page
404 W Opens the log window where you can review messages that
406 pop up at the bottom.
407 w Opens the task window where you can view and modify
409 background processes that currently run in ranger. In
410 there, you can type "dd" to abort a process and "J" or
411 "K" to change the priority of a process. Only one
412 process is run at a time.
413 ^C Stop the currently running background process that ranger
415 has started, like copying files, loading directories or
416 file previews.
417 <octal>=, +<who><what>, -<who><what>
419 Change the permissions of the selection. For example,
420 "777=" is equivalent to "chmod 777 %s", "+ar" does "chmod
421 a+r %s", "-ow" does "chmod o-w %s" etc.
422 yy Copy (yank) the selection, like pressing Ctrl+C in modern
424 GUI programs. (You can also type "ya" to add files to
425 the copy buffer, "yr" to remove files again, or "yt" for
426 toggling.)
427 dd Cut the selection, like pressing Ctrl+X in modern GUI
429 programs. (There are also "da", "dr" and "dt" shortcuts
430 equivalent to "ya", "yr" and "yt".)
431 pp Paste the files which were previously copied or cut, like
433 pressing Ctrl+V in modern GUI programs.
434 po Paste the copied/cut files, overwriting existing files.
436 pP, pO Like pp and po, but queues the operation so that it will
438 be executed after any other operations. Reminder: type
439 "w" to open the task window.
440 pl, pL Create symlinks (absolute or relative) to the copied
442 files
443 phl Create hardlinks to the copied files
445 pht Duplicate the subdirectory tree of the copied directory,
447 then create hardlinks for each contained file into the
448 new directory tree.
449 mX Create a bookmark with the name X
451 `X Move to the bookmark with the name X
453 n Find the next file. By default, this gets you to the
455 newest file in the directory, but if you search something
456 using the keys /, cm, ct, ..., it will get you to the
457 next found entry.
458 N Find the previous file.
460 oX Change the sort method (like in mutt)
462 zX Change settings. See the settings section for a list of
464 settings and their hotkey.
465 u? Universal undo-key. Depending on the key that you press
467 after "u", it either restores closed tabs (uq), removes
468 tags (ut), clears the copy/cut buffer (ud), starts the
469 reversed visual mode (uV) or clears the selection (uv).
470 f Quickly navigate by entering a part of the filename.
472 Space Mark a file.
474 v Toggle the mark-status of all files
476 V Starts the visual mode, which selects all files between
478 the starting point and the cursor until you press ESC.
479 To unselect files in the same way, use "uV".
480 / Search for files in the current directory.
482 : Open the console.
484 ! Open the console with the content "shell " so you can
486 quickly run commands
487 @ Open the console with the content "shell %s", placing
489 the cursor before the " %s" so you can quickly run
490 commands with the current selection as the argument.
491 r Open the console with the content "open with " so you can
493 decide which program to use to open the current file
494 selection.
495 cd Open the console with the content "cd "
497 ^P Open the console with the most recent command.
499 Alt-N Open a tab. N has to be a number from 0 to 9. If the tab
501 doesn't exist yet, it will be created.
502 gn, ^N Create a new tab.
504 gt, gT Go to the next or previous tab. You can also use TAB and
506 SHIFT+TAB instead.
507 gc, ^W Close the current tab. The last tab cannot be closed
509 this way.
510 M A key chain that allows you to quickly change the line
512 mode of all the files of the current directory. For a
513 more permanent solution, use the command
514 "default_linemode" in your rc.conf.
515 .n Apply a new filename filter.
517 .m Apply a new mimetype filter.
519 .d Apply the typefilter "directory".
521 .f Apply the typefilter "file".
523 .l Apply the typefilter "symlink".
525 .| Combine the two topmost filters from the filter stack in
527 the "OR" relationship, instead of the "AND" used
528 implicitly.
529 .& Explicitly combine the two topmost filters in the "AND"
531 relationship. Usually not needed though might be useful
532 in more complicated scenarios.
533 .! Negate the topmost filter.
535 .r Rotate the filter stack by N elements. Just confirm with
537 enter to rotate by 1, i.e. move the topmost element to
538 the bottom of the stack.
539 .c Clear the filter stack.
541 .* Decompose the topmost filter combinator (e.g. ".!",
543 ".|").
544 .p Pop the topmost filter from the filter stack.
546 .. Show the current filter stack state.
548 READLINE-LIKE BINDINGS IN THE CONSOLE
550 ^B, ^F Move left and right (B for back, F for forward)
551 ^P, ^N Move up and down (P for previous, N for Next)
553 ^A, ^E Move to the start or to the end
555 Alt-B, Alt-LEFT
557 Move backwards by words.
558 Alt-F, Alt-RIGHT
560 Move forwards by words.
561 ^D Delete the current character.
563 ^H Backspace.
565
567 Left Mouse Button
568 Click on something and you'll move there. To run a file, "enter"
569 it, like a directory, by clicking on the preview.
570 Right Mouse Button
572 Enter a directory or run a file.
573 Scroll Wheel
575 Scrolls up or down. You can point at the column of the parent
576 directory while scrolling to switch directories.
577
579 This section lists all built-in settings of ranger. The valid types
580 for the value are in [brackets]. The hotkey to toggle the setting is
581 in <brakets>, if a hotkey exists.
582 Settings can be changed in the file ~/.config/ranger/rc.conf or on the
584 fly with the command :set option value. Examples:
585 set column_ratios 1,2,3
587 set show_hidden true
588 Toggling options can be done with:
590 set show_hidden!
592 The different types of settings and an example for each type:
594 setting type | example values
596 ---------------+----------------------------
597 bool | true, false
598 integer | 1, 23, 1337
599 string | foo, hello world
600 list | 1,2,3,4
601 none | none
602 You can view a list of all settings and their current values by
604 pressing "3?" in ranger.
605 automatically_count_files [bool]
607 Should ranger count and display the number of files in each
608 directory as soon as it's visible? This gets slow with remote file
609 systems. Turning it off will still allow you to see the number of
610 files after entering the directory.
611 autosave_bookmarks [bool]
613 Save bookmarks (used with mX and `X) instantly? This helps to
614 synchronize bookmarks between multiple ranger instances but leads
615 to *slight* performance loss. When false, bookmarks are saved when
616 ranger is exited.
617 autoupdate_cumulative_size [bool]
619 You can display the "real" cumulative size of directories by using
620 the command :get_cumulative_size or typing "dc". The size is
621 expensive to calculate and will not be updated automatically. You
622 can choose to update it automatically though by turning on this
623 option.
624 cd_bookmarks [bool]
626 Specify whether bookmarks should be included in the tab completion
627 of the "cd" command.
628 cd_tab_case [string]
630 Changes case sensitivity for the "cd" command tab completion.
631 Possible values are:
632 sensitive
634 insensitive
635 smart
636 cd_tab_fuzzy [bool]
638 Use fuzzy tab completion with the "cd" command. For example, :cd
639 /u/lo/b<TAB> expands to :cd /usr/local/bin.
640 clear_filters_on_dir_change [bool]
642 If set to 'true', persistent filters would be cleared upon leaving
643 the directory
644 collapse_preview [bool] <zc>
646 When no preview is visible, should the last column be squeezed to
647 make use of the whitespace?
648 colorscheme [string]
650 Which colorscheme to use? These colorschemes are available by
651 default: default, jungle, snow. Snow is a monochrome scheme,
652 jungle replaces blue directories with green ones for better
653 visibility on certain terminals.
654 column_ratios [list]
656 How many columns are there, and what are their relative widths?
657 For example, a value of 1,1,1 would mean 3 evenly sized columns.
658 1,1,1,1,4 means 5 columns with the preview column being as large as
659 the other columns combined.
660 confirm_on_delete [string]
662 Ask for a confirmation when running the "delete" command? Valid
663 values are "always" (default), "never", "multiple". With
664 "multiple", ranger will ask only if you delete multiple files at
665 once.
666 dirname_in_tabs [bool]
668 Display the directory name in tabs?
669 display_size_in_main_column [bool]
671 Display the file size in the main column?
672 display_size_in_status_bar [bool]
674 Display the file size in the status bar?
675 display_free_space_in_status_bar [bool]
677 Display the free disk space in the status bar?
678 display_tags_in_all_columns [bool]
680 Display tags in all columns?
681 draw_borders [string]
683 Draw borders around or between the columns? Possible values are:
684 none no borders of any sort
686 outline draw an outline around all the columns
687 separators draw only vertical lines between columns
688 both both of the above
689 draw_progress_bar_in_status_bar [bool]
691 Draw a progress bar in the status bar which displays the average
692 state of all currently running tasks which support progress bars?
693 flushinput [bool] <zi>
695 Flush the input after each key hit? One advantage is that when
696 scrolling down with "j", ranger stops scrolling instantly when you
697 release the key. One disadvantage is that when you type commands
698 blindly, some keys might get lost.
699 freeze_files [bool] <F>
701 When active, directories and files will not be loaded, improving
702 performance when all the files you need are already loaded. This
703 does not affect file previews.
704 global_inode_type_filter [string]
706 Like filter_inode_type, but globally for all directories. Useful
707 in combination with --choosedir:
708 ranger --choosedir=/tmp/x --cmd='set global_inode_type_filter d'
710 hidden_filter [string]
712 A regular expression pattern for files which should be hidden. For
713 example, this pattern will hide all files that start with a dot or
714 end with a tilde.
715 set hidden_filter ^\.|~$
717 hint_collapse_threshold [int]
719 The key hint lists up to this size have their sublists expanded.
720 Otherwise the submaps are replaced with "...".
721 hostname_in_titlebar [bool]
723 Show hostname in titlebar?
724 idle_delay [integer]
726 The delay that ranger idly waits for user input, in milliseconds,
727 with a resolution of 100ms. Lower delay reduces lag between
728 directory updates but increases CPU load.
729 iterm2_font_height [integer]
731 Change the assumed font height in iTerm2, which may help with iTerm
732 image previews
733 iterm2_font_width [integer]
735 Change the assumed font width in iTerm2, which may help with iTerm
736 image previews
737 line_numbers [string]
739 Show line numbers in main column. Possible values are:
740 false turn the feature off
742 absolute absolute line numbers for use with "<N>gg"
743 relative relative line numbers for "<N>k" or "<N>j"
744 max_console_history_size [integer, none]
746 How many console commands should be kept in history? "none" will
747 disable the limit.
748 max_history_size [integer, none]
750 How many directory changes should be kept in history?
751 metadata_deep_search [bool]
753 When the metadata manager module looks for metadata, should it only
754 look for a ".metadata.json" file in the current directory, or do a
755 deep search and check all directories above the current one as
756 well?
757 mouse_enabled [bool] <zm>
759 Enable mouse input?
760 one_indexed [bool]
762 Start line numbers from 1. Possible values are:
763 false start line numbers from 0
765 true start line numbers from 1
766 open_all_images [bool]
768 Open all images in this directory when running certain image
769 viewers like feh or sxiv? You can still open selected files by
770 marking them.
771 padding_right [bool]
773 When collapse_preview is on and there is no preview, should there
774 remain a little padding on the right? This allows you to click
775 into that space to run the file.
776 preview_directories [bool] <zP>
778 Preview directories in the preview column?
779 preview_files [bool] <zp>
781 Preview files in the preview column?
782 preview_images [bool]
784 Draw images inside the console with the external program
785 w3mimgpreview?
786 preview_images_method [string]
788 Set the preview image method. Supported methods: w3m, iterm2,
789 urxvt, urxvt-full, terminology. See PREVIEWS section.
790 preview_max_size [int]
792 Avoid previewing files that exceed a certain size, in bytes. Use a
793 value of 0 to disable this feature.
794 preview_script [string, none]
796 Which script should handle generating previews? If the file
797 doesn't exist, or use_preview_script is off, ranger will handle
798 previews itself by just printing the content.
799 relative_current_zero [bool]
801 When line_numbers is set to relative, show 0 on the current line if
802 true or show the absolute number of the current line when false.
803 save_backtick_bookmark [bool]
805 Save the "`" bookmark to disk. This bookmark is used to switch to
806 the last directory by typing "``".
807 save_console_history [bool]
809 Should the console history be saved on exit? If disabled, the
810 console history is reset when you restart ranger.
811 save_tabs_on_exit [bool]
813 Save all tabs, except the active, on exit? The last saved tabs are
814 restored once when starting the next session. Multiple sessions are
815 stored in a stack and the oldest saved tabs are restored first.
816 scroll_offset [integer]
818 Try to keep this much space between the top/bottom border when
819 scrolling.
820 shorten_title [integer]
822 Trim the title of the window if it gets long? The number defines
823 how many directories are displayed at once. A value of 0 turns off
824 this feature.
825 show_cursor [bool]
827 Always show the terminal cursor?
828 show_hidden_bookmarks [bool]
830 Show dotfiles in the bookmark preview window? (Type ')
831 show_hidden [bool] <zh>, <^H>
833 Show hidden files?
834 show_selection_in_titlebar [bool]
836 Add the highlighted file to the path in the titlebar
837 sort_case_insensitive [bool] <zc>
839 Sort case-insensitively? If true, "a" will be listed before "B"
840 even though its ASCII value is higher.
841 sort_directories_first [bool] <zd>
843 Sort directories first?
844 sort_reverse [bool] <or>
846 Reverse the order of files?
847 sort_unicode [bool]
849 When sorting according to some string, should the unicode
850 characters be compared, instead of looking at the raw character
851 values to save time?
852 sort [string] <oa>, <ob>, <oc>, <oe>, <om>, <on>, <ot>, <os>, <oz>
854 Which sorting mechanism should be used? Choose one of atime,
855 basename, ctime, extension, mtime, natural, type, size, random
856 Note: You can reverse the order by typing an uppercase second
858 letter in the key combination, e.g. "oN" to sort from Z to A.
859 status_bar_on_top [bool]
861 Put the status bar at the top of the window?
862 tilde_in_titlebar [bool]
864 Abbreviate $HOME with ~ in the titlebar (first line) of ranger?
865 unicode_ellipsis [bool]
867 Use a unicode "..." character instead of "~" to mark cut-off
868 filenames?
869 bidi_support [bool]
871 Try to properly display file names in RTL languages (Hebrew,
872 Arabic) by using a BIDI algorithm to reverse the relevant parts of
873 the text. Requires the python-bidi pip package.
874 update_title [bool]
876 Set a window title?
877 update_tmux_title [bool]
879 Set the title to "ranger" in the tmux program?
880 use_preview_script [bool] <zv>
882 Use the preview script defined in the setting preview_script?
883 vcs_aware [bool]
885 Gather and display data about version control systems. Supported
886 vcs: git, hg.
887 vcs_backend_git, vcs_backend_hg, vcs_backend_bzr, vcs_backend_svn
889 [string]
890 Sets the state for the version control backend. The possible values
891 are:
892 disabled don't display any information.
894 local display only local state.
895 enabled display both, local and remote state. May be slow for hg and bzr.
896 viewmode [string]
898 Sets the view mode, which can be miller to display the files in the
899 traditional miller column view that shows multiple levels of the
900 hierarchy, or multipane to use multiple panes (one per tab) similar
901 to midnight-commander.
902 w3m_delay [float]
904 Delay in seconds before displaying an image with the w3m method.
905 Increase it in case of experiencing display corruption.
906 wrap_scroll [bool]
908 Enable scroll wrapping - moving down while on the last item will
909 wrap around to the top and vice versa.
910 xterm_alt_key [bool]
912 Enable this if key combinations with the Alt Key don't work for
913 you. (Especially on xterm)
914
916 You can enter the commands in the console which is opened by pressing
917 ":".
918 You can always get a list of the currently existing commands by typing
920 "2?" in ranger. For your convenience, this is a list of the "public"
921 commands including their parameters, excluding descriptions:
922 alias [newcommand] [oldcommand]
924 bulkrename
925 cd [path]
926 chain command1[; command2[; command3...]]
927 chmod octal_number
928 cmap key command
929 console [-pSTARTPOSITION] command
930 copycmap key newkey [newkey2...]
931 copymap key newkey [newkey2...]
932 copypmap key newkey [newkey2...]
933 copytmap key newkey [newkey2...]
934 cunmap keys...
935 default_linemode [path=regexp | tag=tags] linemodename
936 delete
937 echo [text]
938 edit [filename]
939 eval [-q] python_code
940 filter [string]
941 filter_inode_type [dfl]
942 find pattern
943 flat level
944 grep pattern
945 help
946 jump_non [-FLAGS...]
947 linemode linemodename
948 load_copy_buffer
949 map key command
950 mark pattern
951 mark_tag [tags]
952 meta key value
953 mkdir dirname
954 open_with [application] [flags] [mode]
955 pmap key command
956 prompt_metadata [key1 [key2 [...]]]
957 punmap keys...
958 quit
959 quit!
960 quitall
961 quitall!
962 relink newpath
963 rename_append [-FLAGS...]
964 rename newname
965 save_copy_buffer
966 scout [-FLAGS...] pattern
967 search pattern
968 search_inc pattern
969 set option value
970 setintag tags option value
971 setlocal [path=<path>] option value
972 shell [-FLAGS...] command
973 source filename
974 terminal
975 tmap key command
976 touch filename
977 travel pattern
978 tunmap keys...
979 unmap keys...
980 unmark pattern
981 unmark_tag [tags]
982 There are additional commands which are directly translated to python
984 functions, one for every method in the ranger.core.actions.Actions
985 class. They are not documented here, since they are mostly for key
986 bindings, not to be typed in by a user. Read the source if you are
987 interested in them.
988 These are the public commands including their descriptions:
990 alias [newcommand] [oldcommand]
992 Copies the oldcommand as newcommand.
993 bulkrename
995 This command opens a list of selected files in an external editor.
996 After you edit and save the file, it will generate a shell script
997 which does bulk renaming according to the changes you did in the
998 file.
999 This shell script is opened in an editor for you to review. After
1001 you close it, it will be executed.
1002 cd [path]
1004 The cd command changes the directory. If path is a file, selects
1005 that file. The command ":cd -" is equivalent to typing ``.
1006 chain command1[; command2[; command3...]]
1008 Combines multiple commands into one, separated by semicolons.
1009 chmod octal_number
1011 Sets the permissions of the selection to the octal number.
1012 The octal number is between 000 and 777. The digits specify the
1014 permissions for the user, the group and others. A 1 permits
1015 execution, a 2 permits writing, a 4 permits reading. Add those
1016 numbers to combine them. So a 7 permits everything.
1017 Key bindings in the form of [-+]<who><what> and <octal>= also exist.
1019 For example, +ar allows reading for everyone, -ow forbids others to
1020 write and 777= allows everything.
1021 See also: man 1 chmod
1023 cmap key command
1025 Binds keys for the console. Works like the "map" command.
1026 console [-pN] command
1028 Opens the console with the command already typed in. The cursor is
1029 placed at N.
1030 copycmap key newkey [newkey2 ...]
1032 See "copymap"
1033 copymap key newkey [newkey2 ...]
1035 Copies the keybinding key to newkey in the "browser" context. This
1036 is a deep copy, so if you change the new binding (or parts of it)
1037 later, the old one is not modified.
1038 To copy key bindings of the console, taskview, or pager use
1040 "copycmap", "copytmap" or "copypmap".
1041 copypmap key newkey [newkey2 ...]
1043 See "copymap"
1044 copytmap key newkey [newkey2 ...]
1046 See "copymap"
1047 cunmap [keys...]
1049 Removes key mappings of the console. Works like the "unmap" command.
1050 default_linemode [path=regexp | tag=tags] linemodename
1052 Sets the default linemode. See linemode command.
1053 Examples:
1055 Set the global default linemode to "permissions":
1057 :default_linemode permissions
1058 Set the default linemode to "permissions" for all files tagged with
1060 "p" or "P":
1061 :default_linemode tag=pP permissions
1062 Set the default linemode for all files in ~/books/ to "metatitle":
1064 :default_linemode path=/home/.*?/books/.* metatitle
1065 delete
1067 Destroy all files in the selection with a roundhouse kick. ranger
1068 will ask for a confirmation if you attempt to delete multiple
1069 (marked) files or non-empty directories. This can be changed by
1070 modifying the setting "confirm_on_delete".
1071 echo text
1073 Display the text in the statusbar.
1074 edit [filename]
1076 Edit the current file or the file in the argument.
1077 eval [-q] python_code
1079 Evaluates the python code. `fm' is a reference to the FM instance.
1080 To display text, use the function `p'. The result is displayed on
1081 the screen unless you use the "-q" option.
1082 Examples:
1084 :eval fm
1085 :eval len(fm.tabs)
1086 :eval p("Hello World!")
1087 filter [string]
1089 Displays only the files which contain the string in their basename.
1090 Running this command without any parameter will reset the filter.
1091 This command is based on the scout command and supports all of its
1093 options.
1094 filter_inode_type [dfl]
1096 Displays only the files of specified inode type. To display only
1097 directories, use the 'd' parameter. To display only files, use the
1098 'f' parameter. To display only links, use the 'l' parameter.
1099 Parameters can be combined. To remove this filter, use no parameter.
1100 find pattern
1102 Search files in the current directory that contain the given (case-
1103 insensitive) string in their name as you type. Once there is an
1104 unambiguous result, it will be run immediately. (Or entered, if it's
1105 a directory.)
1106 This command is based on the scout command and supports all of its
1108 options.
1109 flat level
1111 Flattens the directory view up to the specified level. Level -1 means
1112 infinite level. Level 0 means standard view without flattened
1113 directory view. Level values -2 and less are invalid.
1114 grep pattern
1116 Looks for a string in all marked files or directories.
1117 help
1119 Provides a quick way to view ranger documentations.
1120 jump_non [-flags...]
1122 Jumps to first non-directory if highlighted file is a directory and
1123 vice versa.
1124 Flags:
1126 -r Jump in reverse order
1127 -w Wrap around if reaching end of filelist
1128 linemode linemodename
1130 Sets the linemode of all files in the current directory. The
1131 linemode may be:
1132 "filename": display each line as "<basename>...<size>"
1134 "fileinfo": display each line as "<basename>...<file(1) output>"
1135 "permissions": display each line as "<permissions> <owner> <group> <basename>"
1136 "metatitle": display metadata from .metadata.json files if
1137 available, fall back to the "filename" linemode if no
1138 metadata was found. See :meta command.
1139 The custom linemodes may be added by subclassing the LinemodeBase
1141 class. See the ranger.core.linemode module for some examples.
1142 load_copy_buffer
1144 Load the copy buffer from ~/.config/ranger/copy_buffer. This can be
1145 used to pass the list of copied files to another ranger instance.
1146 map key command
1148 Assign the key combination to the given command. Whenever you type
1149 the key/keys, the command will be executed. Additionally, if you use
1150 a quantifier when typing the key, like 5j, it will be passed to the
1151 command as the attribute "self.quantifier".
1152 The keys you bind with this command are accessible in the file
1154 browser only, not in the console, task view or pager. To bind keys
1155 there, use the commands "cmap", "tmap" or "pmap".
1156 mark pattern
1158 Mark all files matching the regular expression pattern.
1159 This command is based on the scout command and supports all of its
1161 options.
1162 mark_tag [tags]
1164 Mark all tags that are tagged with either of the given tags. When
1165 leaving out the tag argument, all tagged files are marked.
1166 meta key value
1168 Set the metadata of the currently highlighted file. Example:
1169 :meta title The Hitchhiker's Guide to the Galaxy
1171 :meta year 1979
1172 This metadata can be displayed by, for example, using the "metatitle"
1174 line mode by typing Mt.
1175 mkdir dirname
1177 Creates a directory with the name dirname.
1178 open_with [application] [flags] [mode]
1180 Open the selected files with the given application, unless it is
1181 omitted, in which case the default application is used. flags change
1182 the way the application is executed and are described in their own
1183 section in this man page. The mode is a number that specifies which
1184 application to use. The list of applications is generated by the
1185 external file opener "rifle" and can be displayed when pressing "r"
1186 in ranger.
1187 Note that if you specify an application, the mode is ignored.
1189 pmap key command
1191 Binds keys for the pager. Works like the "map" command.
1192 prompt_metadata [keys ...]
1194 Prompt the user to input metadata with the "meta" command for
1195 multiple keys in a row.
1196 punmap [keys ...]
1198 Removes key mappings of the pager. Works like the "unmap" command.
1199 quit
1201 Closes the current tab, if there's only one tab. Otherwise quits if
1202 there are no tasks in progress. The current directory will be
1203 bookmarked as ' so you can re-enter it by typing `` or '' the next
1204 time you start ranger.
1205 quit!
1207 Like "quit", except will force quit even if tasks are in progress.
1208 quitall
1210 Like "quit", except will quit even if multiple tabs are open.
1211 quitall!
1213 Like "quitall", except will force quit even if tasks are in progress.
1214 relink newpath
1216 Change the link destination of the current symlink file to <newpath>.
1217 First <tab> will load the original link.
1218 rename newname
1220 Rename the current file. If a file with that name already exists,
1221 the renaming will fail. Also try the key binding A for appending
1222 something to a file name.
1223 rename_append [-flags...]
1225 Opens the console with ":rename <current file>" with the cursor
1226 positioned before the file extension.
1227 Flags:
1229 -a Position before all extensions
1230 -r Remove everything before extensions
1231 save_copy_buffer
1233 Save the copy buffer to ~/.config/ranger/copy_buffer. This can be
1234 used to pass the list of copied files to another ranger instance.
1235 scout [-flags...] [--] pattern
1237 Swiss army knife command for searching, traveling and filtering
1238 files.
1239 Flags:
1241 -a Automatically open a file on unambiguous match
1242 -e Open the selected file when pressing enter
1243 -f Filter files that match the current search pattern
1244 -g Interpret pattern as a glob pattern
1245 -i Ignore the letter case of the files
1246 -k Keep the console open when changing a directory with the
1247 command
1248 -l Letter skipping; e.g. allow "rdme" to match the file "readme"
1249 -m Mark the matching files after pressing enter
1250 -M Unmark the matching files after pressing enter
1251 -p Permanent filter: hide non-matching files after pressing enter
1252 -r Interpret pattern as a regular expression pattern
1253 -s Smart case; like -i unless pattern contains upper case letters
1254 -t Apply filter and search pattern as you type
1255 -v Inverts the match
1256 Multiple flags can be combined. For example, ":scout -gpt" would
1258 create a :filter-like command using globbing.
1259 search pattern
1261 Search files in the current directory that match the given (case
1262 insensitive) regular expression pattern.
1263 This command is based on the scout command and supports all of its
1265 options.
1266 search_inc pattern
1268 Search files in the current directory that match the given (case
1269 insensitive) regular expression pattern. This command gets you to
1270 matching files as you type.
1271 This command is based on the scout command and supports all of its
1273 options.
1274 set option value
1276 Assigns a new value to an option. Valid options are listed in the
1277 settings section. Use tab completion to get the current value of an
1278 option, though this doesn't work for functions and regular
1279 expressions. Valid values are:
1280 setting type | example values
1282 ---------------+----------------------------
1283 bool | true, false
1284 integer | 1, 23, 1337
1285 string | foo, hello world
1286 list | 1,2,3,4
1287 none | none
1288 setintag tags option value
1290 Assigns a new value to an option, but locally for the directories
1291 that are marked with tag. This means, that this option only takes
1292 effect when visiting that directory.
1293 For example, to change the sorting order in your downloads directory,
1295 tag it with the v tag by typing "v, then use this command:
1296 setintag v sort ctime
1298 setlocal [path=path] option value
1300 Assigns a new value to an option, but locally for the directory given
1301 by path. This means, that this option only takes effect when visiting
1302 that directory. If no path is given, uses the current directory.
1303 path is a regular expression. This means that "path=~/dl" applies to
1305 all paths that start with ~/dl, e.g. ~/dl2 and ~/dl/foo. To avoid
1306 this, use "path=~/dl$".
1307 path can be quoted with either single or double quotes to prevent
1309 unwanted splitting. path='~/dl dl$' or path="~/dl dl$"
1310 shell [-flags] command
1312 Run a shell command. flags are discussed in their own section.
1313 source filename
1315 Reads commands from a file and executes them in the ranger console.
1316 This can be used to re-evaluate the rc.conf file after changing it:
1318 map X chain shell vim -p %confdir/rc.conf %rangerdir/config/rc.conf; source %confdir/rc.conf
1320 terminal
1322 Spawns the x-terminal-emulator starting in the current directory.
1323 tmap key command
1325 Binds keys for the taskview. Works like the "map" command.
1326 touch filename
1328 Creates an empty file with the name filename, unless it already
1329 exists.
1330 travel pattern
1332 Filters the current directory for files containing the letters in the
1333 string, possibly with other letters in between. The filter is
1334 applied as you type. When only one directory is left, it is entered
1335 and the console is automatically reopened, allowing for fast travel.
1336 To close the console, press ESC or execute a file.
1337 This command is based on the scout command and supports all of its
1339 options.
1340 tunmap [keys ...]
1342 Removes key mappings of the taskview. Works like the "unmap" command.
1343 unmap [keys ...]
1345 Removes the given key mappings in the "browser" context. To unmap
1346 key bindings in the console, taskview, or pager use "cunmap",
1347 "tunmap" or "punmap".
1348 unmark pattern
1350 Unmark all files matching a regular expression pattern.
1351 This command is based on the scout command and supports all of its
1353 options.
1354 unmark_tag [tags]
1356 Unmark all tags that are tagged with either of the given tags. When
1357 leaving out the tag argument, all tagged files are unmarked.
1358
1360 ranger reads several configuration files which are located in
1361 $HOME/.config/ranger or $XDG_CONFIG_HOME/ranger if $XDG_CONFIG_HOME is
1362 defined. You can use the --copy-config option to obtain the default
1363 configuration files. The files contain further documentation.
1364 rc.conf, commands.py and colorschemes do not need to be copied fully as
1366 they will only be adding to the default configuration files except if
1367 explicitly overridden. This may lead to some confusing situations, for
1368 example when a key is being bound despite the corresponding line being
1369 removed from the user's copy of the configuration file. This behavior
1370 may be disabled with an environment variable (see also: ENVIRONMENT).
1371 Note: All other configuration files only read from one source; i.e.
1372 default OR user, not both. rc.conf and commands.py are additionally
1373 read from /etc/ranger if they exist for system-wide configuration, user
1374 configuration overrides system configuration which overrides the
1375 default configuration.
1376 When starting ranger with the --clean option, it will not access or
1378 create any of these files.
1379 CONFIGURATION
1381 rc.conf Contains a list of commands which are executed on startup.
1382 Mostly key bindings and settings are defined here.
1383 commands.py
1385 A python module that defines commands which can be used in
1386 ranger's console by typing ":" or in the rc.conf file. Note
1387 that you can define commands in the same manner within
1388 plugins.
1389 commands_full.py
1391 This file is copied by --copy-config=commands_full and serves
1392 as a reference for custom commands. It is entirely ignored
1393 by ranger.
1394 rifle.conf
1396 This is the configuration file for the built-in file launcher
1397 called "rifle".
1398 scope.sh This is a script that handles file previews. When the
1400 options use_preview_script and preview_files are set, the
1401 program specified in the option preview_script is run and its
1402 output and/or exit code determines rangers reaction.
1403 colorschemes/
1405 Colorschemes can be placed here.
1406 plugins/ Plugins can be placed here.
1408 STORAGE
1410 bookmarks This file contains a list of bookmarks. The syntax is
1411 /^(.):(.*)$/. The first character is the bookmark key and the
1412 rest after the colon is the path to the file. In ranger,
1413 bookmarks can be set by typing m<key>, accessed by typing
1414 '<key> and deleted by typing um<key>.
1415 copy_buffer
1417 When running the command :save_copy_buffer, the paths of all
1418 currently copied files are saved in this file. You can later
1419 run :load_copy_buffer to copy the same files again, pass them
1420 to another ranger instance or process them in a script.
1421 history Contains a list of commands that have been previously typed
1423 in.
1424 tagged Contains a list of tagged files. The syntax is /^(.:)?(.*)$/
1426 where the first letter is the optional name of the tag and
1427 the rest after the optional colon is the path to the file.
1428 In ranger, tags can be set by pressing t and removed with T.
1429 To assign a named tag, type "<tagname>.
1430
1432 These environment variables have an effect on ranger:
1433 RANGER_LEVEL
1435 ranger sets this environment variable to "1" or increments it
1436 if it already exists. External programs can determine whether
1437 they were spawned from ranger by checking for this variable.
1438 RANGER_LOAD_DEFAULT_RC
1440 If this variable is set to FALSE, ranger will not load the
1441 default rc.conf. This can save time if you copied the whole
1442 rc.conf to ~/.config/ranger/ and don't need the default one at
1443 all.
1444 VISUAL Defines the editor to be used for the "E" key. Falls back to
1446 EDITOR if undefined or empty.
1447 EDITOR Defines the editor to be used for the "E" key if VISUAL is
1449 undefined or empty. Defaults to "vim".
1450 SHELL Defines the shell that ranger is going to use with the :shell
1452 command and the "S" key. Defaults to "/bin/sh".
1453 TERMCMD Defines the terminal emulator command that ranger is going to
1455 use with the :terminal command and the "t" run flag. Defaults
1456 to "xterm".
1457 XDG_CONFIG_HOME
1459 Specifies the directory for configuration files. Defaults to
1460 $HOME/.config.
1461 PYTHONOPTIMIZE
1463 This variable determines the optimize level of python.
1464 Using PYTHONOPTIMIZE=1 (like python -O) will make python
1466 discard assertion statements. You will gain efficiency at the
1467 cost of losing some debug info.
1468 Using PYTHONOPTIMIZE=2 (like python -OO) will additionally
1470 discard any docstrings. Using this will disable the <F1> key
1471 on commands.
1472 W3MIMGDISPLAY_PATH
1474 By changing this variable, you can change the path of the
1475 executable file for image previews. By default, it is set to
1476 /usr/lib/w3m/w3mimgdisplay.
1477
1479 There are various examples on how to extend ranger with plugins or
1480 combine ranger with other programs. These can be found in the
1481 /usr/share/doc/ranger/examples/ directory, or the doc/ranger/ that is
1482 provided along with the source code.
1483
1485 GNU General Public License 3 or (at your option) any later version.
1486
1488 Download: <https://ranger.github.io/ranger-stable.tar.gz>
1489 The project page: <https://ranger.github.io/>
1490 The mailing list: <https://savannah.nongnu.org/mail/?group=ranger>
1491 IRC channel: #ranger on freenode.net
1492 ranger is maintained with the git version control system. To fetch a
1494 fresh copy, run:
1495 git clone git://git.savannah.nongnu.org/ranger.git
1497
1499 rifle(1)
1500
1502 Report bugs here: <https://github.com/ranger/ranger/issues>
1503 Please include as much relevant information as possible. For the most
1505 diagnostic output, run ranger like this: "PYTHONOPTIMIZE= ranger
1506 --debug"
15072018-09-09 ranger-1.9.2 RANGER(1)