3 ranger - visual file manager
10 B<ranger> [B<--version>] [B<--help>] [B<--debug>] [B<--clean>]
11 [B<--confdir>=I<directory>] [B<--copy-config>=I<which>]
12 [B<--choosefile>=I<target>] [B<--choosefiles>=I<target>]
13 [B<--choosedir>=I<target>] [B<--selectfile>=I<filepath>]
14 [B<--list-unused-keys>] [B<--list-tagged-files>=I<tag>]
15 [B<--profile>] [B<--cmd>=I<command>] [I<path>]
22 ranger is a console file manager with VI key bindings.
29 I<This manual> contains instructions on how to use and configure ranger.
31 I<Inside ranger>, you can press I<1?> for a list of key bindings, I<2?> for
32 commands and I<3?> for settings.
34 The F<README> contains install instructions.
36 The file F<HACKING.md> contains guidelines for code modification.
38 The directory F<doc/configs> contains configuration files. They are usually
39 installed to F</usr/lib/python*/site-packages/ranger/config> and can be
40 obtained with ranger's --copy-config option.
42 The man page of rifle(1) describes the functions of the file opener
44 The section I<LINKS> of this man page contains further resources.
53 =item B<-d>, B<--debug>
55 Activate the debug mode: Whenever an error occurs, ranger will exit and print a
56 full traceback. The default behavior is to merely print the name of the
57 exception in the statusbar/log and try to keep running.
59 =item B<-c>, B<--clean>
61 Activate the clean mode: ranger will not access or create any configuration
62 files nor will it leave any traces on your system. This is useful when your
63 configuration is broken, when you want to avoid clutter, etc.
65 =item B<-r> I<dir>, B<--confdir>=I<dir>
67 Change the configuration directory of ranger from ~/.config/ranger to "dir".
69 =item B<--copy-config>=I<file>
71 Create copies of the default configuration files in your local configuration
72 directory. Existing ones will not be overwritten. Possible values: I<all>,
73 I<commands>, I<rc>, I<rifle>, I<scope>.
75 Note: You may want to disable loading of the global configuration files by
76 exporting I<RANGER_LOAD_DEFAULT_RC=FALSE> in your environment. See also:
77 B<FILES>, B<ENVIRONMENT>
79 =item B<--choosefile>=I<targetfile>
81 Allows you to pick a file with ranger. This changes the behavior so that when
82 you open a file, ranger will exit and write the absolute path of that file into
85 =item B<--choosefiles>=I<targetfile>
87 Allows you to pick multiple files with ranger. This changes the behavior so
88 that when you open a file, ranger will exit and write the absolute paths of all
89 selected files into I<targetfile>, adding one newline after each filename.
91 =item B<--choosedir>=I<targetfile>
93 Allows you to pick a directory with ranger. When you exit ranger, it will
94 write the last visited directory into I<targetfile>.
96 =item B<--selectfile>=I<targetfile>
98 Open ranger with I<targetfile> selected.
100 =item B<--list-unused-keys>
102 List common keys which are not bound to any action in the "browser" context.
103 This list is not complete, you can bind any key that is supported by curses:
104 use the key code returned by C<getch()>.
106 =item B<--list-tagged-files>=I<tag>
108 List all files which are tagged with the given tag. Note: Tags are single
109 characters. The default tag is "*"
113 Print statistics of CPU usage on exit.
115 =item B<--cmd>=I<command>
117 Execute the command after the configuration has been read. Use this option
118 multiple times to run multiple commands.
122 Print the version and exit.
124 =item B<-h>, B<--help>
126 Print a list of options and exit.
135 This part explains how certain parts of ranger work and how they can be used
140 Tags are single characters which are displayed left of a filename. You can use
141 tags however you want. Press "t" to toggle tags and "ut" to remove any tags of
142 the selection. The default tag is an Asterisk ("*"), but you can use any tag by
143 typing I<"<tagnameE<gt>>.
147 By default, only text files are previewed, but you can enable external preview
148 scripts by setting the option C<use_preview_script> and C<preview_files> to true.
150 This default script is F<~/.config/ranger/scope.sh>. It contains more
151 documentation and calls to the programs I<lynx> and I<elinks> for html,
152 I<highlight> for text/code, I<img2txt> for images, I<atool> for archives,
153 I<pdftotext> for PDFs and I<mediainfo> for video and audio files.
155 Install these programs (just the ones you need) and scope.sh will automatically
158 Independently of the preview script, there is a feature to preview images
159 by drawing them directly into the terminal. This does not work over ssh,
160 requires certain terminals (tested on "xterm" and "urxvt") and is incompatible
161 with tmux, although it works with screen.
163 To enable this feature, install the program "w3m" and set the option
164 C<preview_images> to true.
168 The I<selection> is defined as "All marked files IF THERE ARE ANY, otherwise
169 the current file." Be aware of this when using the :delete command, which
170 deletes all files in the selection.
172 You can mark files by pressing <Space>, v, etc. A yellow B<Mrk> symbol at the
173 bottom right indicates that there are marked files in this directory.
177 Macros can be used in commands to abbreviate things.
179 %f the highlighted file
180 %d the path of the current directory
181 %s the selected files in the current directory.
182 %t all tagged files in the current directory
183 %c the full paths of the currently copied/cut files
185 The macros %f, %d and %s also have upper case variants, %F, %D and %S,
186 which refer to the next tab. To refer to specific tabs, add a number in
187 between. (%7s = selection of the seventh tab.)
189 %c is the only macro which ranges out of the current directory. So you may
190 "abuse" the copying function for other purposes, like diffing two files which
191 are in different directories:
193 Yank the file A (type yy), move to the file B, then type
196 Macros for file paths are generally shell-escaped so they can be used in the
199 Additionally, if you create a key binding that uses <any>, a special statement
200 which accepts any key, then the macro %any (or %any0, %any1, %any2, ...) can be
201 used in the command to get the key that was pressed.
205 Type B<m<keyE<gt>> to bookmark the current directory. You can re-enter this
206 directory by typing B<`<keyE<gt>>. <key> can be any letter or digit. Unlike vim,
207 both lowercase and uppercase bookmarks are persistent.
209 Each time you jump to a bookmark, the special bookmark at key ` will be set
210 to the last directory. So typing "``" gets you back to where you were before.
212 Bookmarks are selectable when tabbing in the :cd command.
214 Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same.
218 Rifle is the file opener of ranger. It can be used as a standalone program or
219 a python module. It is located at F<ranger/ext/rifle.py>. In contrast to
220 other, more simple file openers, rifle can automatically find installed
221 programs so it can be used effectively out of the box on a variety of systems.
223 It's configured in F<rifle.conf> through a list of conditions and commands.
224 For each line the conditions are checked and if they are met, the respective
225 command is taken into consideration. By default, simply the first matching
226 rule is used. In ranger, you can list and choose rules by typing "r" or simply
227 by typing "<rulenumber><enter>". If you use rifle standalone, you can list all
228 rules with the "-l" option and pick a rule with "-p <number>".
230 The rules, along with further documentation, are contained in
231 F<ranger/config/rifle.conf>.
235 Flags give you a way to modify the behavior of the spawned process. They are
236 used in the commands C<:open_with> (key "r") and C<:shell> (key "!").
238 f Fork the process. (Run in background)
239 c Run the current file only, instead of the selection
240 r Run application with root privilege (requires sudo)
241 t Run application in a new terminal window
243 There are some additional flags that can currently be used only in the C<shell>
244 command: (for example C<:shell -w df>)
246 p Redirect output to the pager
247 s Silent mode. Output will be discarded.
248 w Wait for an Enter-press when the process is done
250 By default, all the flags are off unless specified otherwise in the
251 F<rifle.conf> configuration file. You can specify as many flags as you want.
252 An uppercase flag negates the effect: "ffcccFsf" is equivalent to "cs".
254 The terminal program name for the "t" flag is taken from the environment
255 variable $TERMCMD. If it doesn't exist, it tries to extract it from $TERM and
256 uses "xterm" as a fallback if that fails.
258 Examples: C<:open_with c> will open the file that you currently point at, even
259 if you have selected other files. C<:shell -w df> will run "df" and wait for
260 you to press Enter before switching back to ranger.
264 ranger's plugin system consists of python files which are located in
265 F<~/.config/ranger/plugins/> and are imported in alphabetical order when
266 starting ranger. A plugin changes rangers behavior by overwriting or extending
267 a function that ranger uses. This allows you to change pretty much every part
268 of ranger, but there is no guarantee that things will continue to work in
269 future versions as the source code evolves.
271 There are some hooks that are specifically made for the use in plugins. They
272 are functions that start with hook_ and can be found throughout the code.
274 grep 'def hook_' -r /path/to/rangers/source
280 Note that you should NOT simply overwrite a function unless you know what
281 you're doing. Instead, save the existing function and call it from your new
282 one. This way, multiple plugins can use the same hook. There are several
283 sample plugins in the F</usr/share/doc/ranger/examples/> directory, including a
284 hello-world plugin that describes this procedure.
291 Key bindings are defined in the file F<ranger/config/rc.conf>. Check this
292 file for a list of all key bindings. You can copy it to your local
293 configuration directory with the --copy-config=rc option.
295 Many key bindings take an additional numeric argument. Type I<5j> to move
296 down 5 lines, I<2l> to open a file in mode 2, I<10<SpaceE<gt>> to mark 10 files.
298 This list contains the most useful bindings:
306 Move left, down, up or right
308 =item ^D or J, ^U or K
310 Move a half page down, up
314 Move back and forward in the history
326 Move up and down in the parent directory.
338 Inspect the current file in a bigger window.
342 Edit the current file in $EDITOR ("nano" by default)
346 Open a shell in the current directory
354 Opens the log window where you can review messages that pop up at the bottom.
358 Opens the task window where you can view and modify background processes that
359 currently run in ranger. In there, you can type "dd" to abort a process and
360 "J" or "K" to change the priority of a process. Only one process is run at a
365 Stop the currently running background process that ranger has started, like
366 copying files, loading directories or file previews.
368 =item <octal>=, +<who><what>, -<who><what>
370 Change the permissions of the selection. For example, C<777=> is equivalent to
371 C<chmod 777 %s>, C<+ar> does C<chmod a+r %s>, C<-ow> does C<chmod o-w %s> etc.
375 Copy (yank) the selection, like pressing Ctrl+C in modern GUI programs.
379 Cut the selection, like pressing Ctrl+X in modern GUI programs.
383 Paste the files which were previously copied or cut, like pressing Ctrl+V in
388 Paste the copied/cut files, overwriting existing files.
392 Create symlinks (absolute or relative) to the copied files
396 Create hardlinks to the copied files
400 Duplicate the subdirectory tree of the copied directory, then create
401 hardlinks for each contained file into the new directory tree.
405 Create a bookmark with the name I<X>
409 Move to the bookmark with the name I<X>
413 Find the next file. By default, this gets you to the newest file in the
414 directory, but if you search something using the keys /, cm, ct, ..., it will
415 get you to the next found entry.
419 Find the previous file.
423 Change the sort method (like in mutt)
427 Change settings. See the settings section for a list of settings and their
432 Universal undo-key. Depending on the key that you press after "u", it either
433 restores closed tabs (uq), removes tags (ut), clears the copy/cut buffer (ud),
434 starts the reversed visual mode (uV) or clears the selection (uv).
438 Quickly navigate by entering a part of the filename.
446 Toggle the mark-status of all files
450 Starts the visual mode, which selects all files between the starting point and
451 the cursor until you press ESC. To unselect files in the same way, use "uV".
455 Search for files in the current directory.
463 Open the console with the content "shell " so you can quickly run commands
467 Open the console with the content "shell %s", placing the cursor before the
468 " %s" so you can quickly run commands with the current selection as the
473 Open the console with the content "open with " so you can decide which program
474 to use to open the current file selection.
478 Open the console with the content "cd "
482 Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it
491 Go to the next or previous tab. You can also use TAB and SHIFT+TAB instead.
495 Close the current tab. The last tab cannot be closed this way.
499 A key chain that allows you to quickly change the line mode of all the files of
500 the current directory. For a more permanent solution, use the command
501 "default_linemode" in your rc.conf.
505 =head2 READLINE-LIKE BINDINGS IN THE CONSOLE
511 Move left and right (B for back, F for forward)
515 Move up and down (P for previous, N for Next)
519 Move to the start or to the end
523 Delete the current character.
536 =item Left Mouse Button
538 Click on something and you'll move there. To run a file, "enter" it, like a
539 directory, by clicking on the preview.
541 =item Right Mouse Button
543 Enter a directory or run a file.
547 Scrolls up or down. You can point at the column of the parent directory while
548 scrolling to switch directories.
557 This section lists all built-in settings of ranger. The valid types for the
558 value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if
561 Settings can be changed in the file F<~/.config/ranger/rc.conf> or on the
562 fly with the command B<:set option value>. Examples:
564 set column_ratios 1,2,3
567 The different types of settings and an example for each type:
569 setting type | example values
570 ---------------+----------------------------
572 integer | 1, 23, 1337
573 string | foo, hello world
577 You can view a list of all settings and their current values by pressing "3?"
582 =item automatically_count_files [bool]
584 Should ranger count and display the number of files in each directory
585 as soon as it's visible? This gets slow with remote file sytems. Turning it
586 off will still allow you to see the number of files after entering the
589 =item autosave_bookmarks [bool]
591 Save bookmarks (used with mX and `X) instantly? This helps to synchronize
592 bookmarks between multiple ranger instances but leads to *slight* performance
593 loss. When false, bookmarks are saved when ranger is exited.
595 =item autoupdate_cumulative_size [bool]
597 You can display the "real" cumulative size of directories by using the command
598 :get_cumulative_size or typing "dc". The size is expensive to calculate and
599 will not be updated automatically. You can choose to update it automatically
600 though by turning on this option.
602 =item cd_bookmarks [bool]
604 Specify whether bookmarks should be included in the tab completion of the "cd"
607 =item collapse_preview [bool] <zc>
609 When no preview is visible, should the last column be squeezed to make use of
612 =item colorscheme [string]
614 Which colorscheme to use? These colorschemes are available by default:
615 B<default>, B<jungle>, B<snow>. Snow is a monochrome scheme, jungle replaces
616 blue directories with green ones for better visibility on certain terminals.
618 =item column_ratios [list]
620 How many columns are there, and what are their relative widths? For example, a
621 value of 1,1,1 would mean 3 evenly sized columns. 1,1,1,1,4 means 5 columns
622 with the preview column being as large as the other columns combined.
624 =item confirm_on_delete [string]
626 Ask for a confirmation when running the "delete" command? Valid values are
627 "always" (default), "never", "multiple". With "multiple", ranger will ask only
628 if you delete multiple files at once.
630 =item dirname_in_tabs [bool]
632 Display the directory name in tabs?
634 =item display_size_in_main_column [bool]
636 Display the file size in the main column?
638 =item display_size_in_status_bar [bool]
640 Display the file size in the status bar?
642 =item display_tags_in_all_columns [bool]
644 Display tags in all columns?
646 =item draw_borders [bool]
648 Draw borders around columns?
650 =item draw_progress_bar_in_statusbar [bool]
652 Draw a progress bar in the status bar which displays the average state of all
653 currently running tasks which support progress bars?
655 =item flushinput [bool] <zi>
657 Flush the input after each key hit? One advantage is that when scrolling down
658 with "j", ranger stops scrolling instantly when you release the key. One
659 disadvantage is that when you type commands blindly, some keys might get lost.
661 =item hidden_filter [string]
663 A regular expression pattern for files which should be hidden. For example,
664 this pattern will hide all files that start with a dot or end with a tilde.
666 set hidden_filter ^\.|~$
668 =item idle_delay [integer]
670 The delay that ranger idly waits for user input, in milliseconds, with a
671 resolution of 100ms. Lower delay reduces lag between directory updates but
674 =item max_console_history_size [integer, none]
676 How many console commands should be kept in history? "none" will disable the
679 =item max_history_size [integer, none]
681 How many directory changes should be kept in history?
683 =item metadata_deep_search [bool]
685 When the metadata manager module looks for metadata, should it only look for a
686 ".metadata.json" file in the current directory, or do a deep search and check
687 all directories above the current one as well?
689 =item mouse_enabled [bool] <zm>
693 =item padding_right [bool]
695 When collapse_preview is on and there is no preview, should there remain a
696 little padding on the right? This allows you to click into that space to run
699 =item preview_directories [bool] <zP>
701 Preview directories in the preview column?
703 =item preview_files [bool] <zp>
705 Preview files in the preview column?
707 =item preview_images [bool]
709 Draw images inside the console with the external program w3mimgpreview?
711 =item preview_max_size [int]
713 Avoid previewing files that exceed a certain size, in bytes. Use a value of 0
714 to disable this feature.
716 =item preview_script [string, none]
718 Which script should handle generating previews? If the file doesn't exist, or
719 use_preview_script is off, ranger will handle previews itself by just printing
722 =item save_console_history [bool]
724 Should the console history be saved on exit? If disabled, the console history
725 is reset when you restart ranger.
727 =item scroll_offset [integer]
729 Try to keep this much space between the top/bottom border when scrolling.
731 =item shorten_title [integer]
733 Trim the title of the window if it gets long? The number defines how many
734 directories are displayed at once. A value of 0 turns off this feature.
736 =item show_cursor [bool]
738 Always show the terminal cursor?
740 =item show_hidden_bookmarks [bool]
742 Show dotfiles in the bookmark preview window? (Type ')
744 =item show_hidden [bool] <zh>, <^H>
748 =item sort_case_insensitive [bool] <zc>
750 Sort case-insensitively? If true, "a" will be listed before "B" even though
751 its ASCII value is higher.
753 =item sort_directories_first [bool] <zd>
755 Sort directories first?
757 =item sort_reverse [bool] <or>
759 Reverse the order of files?
761 =item sort [string] <oa>, <ob>, <oc>, <oe>, <om>, <on>, <ot>, <os>, <oz>
763 Which sorting mechanism should be used? Choose one of B<atime>, B<basename>,
764 B<ctime>, B<extension>, B<mtime>, B<natural>, B<type>, B<size>, B<random>
766 Note: You can reverse the order by typing an uppercase second letter in the key
767 combination, e.g. "oN" to sort from Z to A.
769 =item status_bar_on_top [bool]
771 Put the status bar at the top of the window?
773 =item tilde_in_titlebar [bool]
775 Abbreviate $HOME with ~ in the title bar (first line) of ranger?
777 =item unicode_ellipsis [bool]
779 Use a unicode "..." character instead of "~" to mark cut-off filenames?
781 =item update_title [bool]
785 =item update_tmux_title [bool]
787 Set the title to "ranger" in the tmux program?
789 =item use_preview_script [bool] <zv>
791 Use the preview script defined in the setting I<preview_script>?
793 =item vcs_aware [bool]
795 Gather and display data about version control systems. Supported vcs: git, hg.
797 =item vcs_backend_git, vcs_backend_hg, vcs_backend_bzr [string]
799 Sets the state for the version control backend. The possible values are:
801 disabled don't display any information.
802 local display only local state.
803 enabled display both, local and remote state. May be slow for hg and bzr.
805 =item xterm_alt_key [bool]
807 Enable this if key combinations with the Alt Key don't work for you.
808 (Especially on xterm)
815 You can enter the commands in the console which is opened by pressing ":".
817 You can always get a list of the currently existing commands by typing "2?" in
818 ranger. For your convenience, this is a list of the "public" commands including their parameters, excluding descriptions:
820 alias [newcommand] [oldcommand]
823 chain command1[; command2[; command3...]]
826 console [-pSTARTPOSITION] command
827 copycmap key newkey [newkey2...]
828 copymap key newkey [newkey2...]
829 copypmap key newkey [newkey2...]
830 copytmap key newkey [newkey2...]
832 default_linemode [path=regexp | tag=tags] linemodename
835 eval [-q] python_code
837 filter_inode_type [dfl]
841 linemode linemodename
848 open_with [application] [flags] [mode]
850 prompt_metadata [key1 [key2 [...]]]
858 scout [-FLAGS] pattern
862 setlocal [path=<path>] option value
863 shell [-FLAGS] command
873 There are additional commands which are directly translated to python
874 functions, one for every method in the ranger.core.actions.Actions class.
875 They are not documented here, since they are mostly for key bindings, not to be
876 typed in by a user. Read the source if you are interested in them.
878 These are the public commands including their descriptions:
882 =item alias [I<newcommand>] [I<oldcommand>]
884 Copies the oldcommand as newcommand.
888 This command opens a list of selected files in an external editor. After you
889 edit and save the file, it will generate a shell script which does bulk
890 renaming according to the changes you did in the file.
892 This shell script is opened in an editor for you to review. After you close
893 it, it will be executed.
895 =item cd [I<directory>]
897 The cd command changes the directory. The command C<:cd -> is equivalent to
900 =item chain I<command1>[; I<command2>[; I<command3>...]]
902 Combines multiple commands into one, separated by semicolons.
904 =item chmod I<octal_number>
906 Sets the permissions of the selection to the octal number.
908 The octal number is between 000 and 777. The digits specify the permissions for
909 the user, the group and others. A 1 permits execution, a 2 permits writing, a
910 4 permits reading. Add those numbers to combine them. So a 7 permits
913 Key bindings in the form of [-+]<who><what> and <octal>= also exist. For
914 example, B<+ar> allows reading for everyone, -ow forbids others to write and
915 777= allows everything.
917 See also: man 1 chmod
919 =item cmap I<key> I<command>
921 Binds keys for the console. Works like the C<map> command.
923 =item console [-pI<N>] I<command>
925 Opens the console with the command already typed in. The cursor is placed at
928 =item copycmap I<key> I<newkey> [I<newkey2> ...]
932 =item copymap I<key> I<newkey> [I<newkey2> ...]
934 Copies the keybinding I<key> to I<newkey> in the "browser" context. This is a
935 deep copy, so if you change the new binding (or parts of it) later, the old one
938 To copy key bindings of the console, taskview, or pager use "copycmap",
939 "copytmap" or "copypmap".
941 =item copypmap I<key> I<newkey> [I<newkey2> ...]
945 =item copytmap I<key> I<newkey> [I<newkey2> ...]
949 =item cunmap [I<keys...>]
951 Removes key mappings of the console. Works like the C<unmap> command.
953 =item default_linemode [I<path=regexp> | I<tag=tags>] I<linemodename>
955 Sets the default linemode. See I<linemode> command.
959 Set the global default linemode to "permissions":
960 :default_linemode permissions
962 Set the default linemode to "permissions" for all files tagged with "p" or "P":
963 :default_linemode tag=pP permissions
965 Set the default linemode for all files in ~/books/ to "metatitle":
966 :default_linemode path=/home/.*?/books/.* metatitle
970 Destroy all files in the selection with a roundhouse kick. ranger will ask for
971 a confirmation if you attempt to delete multiple (marked) files or non-empty
972 directories. This can be changed by modifying the setting "confirm_on_delete".
974 =item edit [I<filename>]
976 Edit the current file or the file in the argument.
978 =item eval [I<-q>] I<python_code>
980 Evaluates the python code. `fm' is a reference to the FM instance. To display
981 text, use the function `p'. The result is displayed on the screen unless you
987 :eval p("Hello World!")
989 =item filter [I<string>]
991 Displays only the files which contain the I<string> in their basename. Running
992 this command without any parameter will reset the fitler.
994 This command is based on the I<scout> command and supports all of its options.
996 =item filter_inode_type [dfl]
998 Displays only the files of specified inode type. To display only directories,
999 use the 'd' parameter. To display only files, use the 'f' parameter. To display
1000 only links, use the 'l' parameter. Parameters can be combined. To remove this
1001 filter, use no parameter.
1003 =item find I<pattern>
1005 Search files in the current directory that contain the given (case-insensitive)
1006 string in their name as you type. Once there is an unambiguous result, it will
1007 be run immediately. (Or entered, if it's a directory.)
1009 This command is based on the I<scout> command and supports all of its options.
1013 Flattens the directory view up to the specified level. Level -1 means infinite
1014 level. Level 0 means standard view without flattened directory view. Level
1015 values -2 and less are invalid.
1017 =item grep I<pattern>
1019 Looks for a string in all marked files or directories.
1021 =item linemode I<linemodename>
1023 Sets the linemode of all files in the current directory. The linemode may be:
1025 "filename": display each line as "<basename>...<size>"
1026 "permissions": display each line as "<permissions> <owner> <group> <basename>"
1027 "metatitle": display metadata from .metadata.json files if
1028 available, fall back to the "filename" linemode if no
1029 metadata was found. See :meta command.
1031 =item load_copy_buffer
1033 Load the copy buffer from F<~/.config/ranger/copy_buffer>. This can be used to
1034 pass the list of copied files to another ranger instance.
1036 =item map I<key> I<command>
1038 Assign the key combination to the given command. Whenever you type the
1039 key/keys, the command will be executed. Additionally, if you use a quantifier
1040 when typing the key, like 5j, it will be passed to the command as the attribute
1043 The keys you bind with this command are accessible in the file browser only,
1044 not in the console, task view or pager. To bind keys there, use the commands
1045 "cmap", "tmap" or "pmap".
1047 =item mark I<pattern>
1049 Mark all files matching the regular expression pattern.
1051 This command is based on the I<scout> command and supports all of its options.
1053 =item mark_tag [I<tags>]
1055 Mark all tags that are tagged with either of the given tags. When leaving out
1056 the tag argument, all tagged files are marked.
1058 =item meta I<key> I<value>
1060 Set the metadata of the currently highlighted file. Example:
1062 :meta title The Hitchhiker's Guide to the Galaxy
1065 This metadata can be displayed by, for example, using the "metatitle" line mode
1068 =item mkdir I<dirname>
1070 Creates a directory with the name I<dirname>.
1072 =item open_with [I<application>] [I<flags>] [I<mode>]
1074 Open the selected files with the given application, unless it is omitted, in
1075 which case the default application is used. I<flags> change the way the
1076 application is executed and are described in their own section in this man
1077 page. The I<mode> is a number that specifies which application to use. The list
1078 of applications is generated by the external file opener "rifle" and can be
1079 displayed when pressing "r" in ranger.
1081 Note that if you specify an application, the mode is ignored.
1083 =item pmap I<key> I<command>
1085 Binds keys for the pager. Works like the C<map> command.
1087 =item prompt_metadata [I<keys ...>]
1089 Prompt the user to input metadata with the C<meta> command for multiple keys in
1092 =item punmap [I<keys ...>]
1094 Removes key mappings of the pager. Works like the C<unmap> command.
1098 Like quit!, but closes only this tab if multiple tabs are open.
1102 Quit ranger. The current directory will be bookmarked as ' so you can re-enter
1103 it by typing `` or '' the next time you start ranger.
1105 =item relink I<newpath>
1107 Change the link destination of the current symlink file to <newpath>. First
1108 <tab> will load the original link.
1112 Opens the console with ":rename <current file>" with the cursor automatically
1113 placed before the file extension
1115 =item rename I<newname>
1117 Rename the current file. If a file with that name already exists, the renaming
1118 will fail. Also try the key binding A for appending something to a file name.
1120 =item save_copy_buffer
1122 Save the copy buffer to I<~/.config/ranger/copy_buffer>. This can be used to
1123 pass the list of copied files to another ranger instance.
1125 =item scout [-I<flags>...] [--] I<pattern>
1127 Swiss army knife command for searching, traveling and filtering files.
1128 The command takes various flags as arguments which can be used to
1129 influence its behaviour:
1131 -a = automatically open a file on unambiguous match
1132 -e = open the selected file when pressing enter
1133 -f = filter files that match the current search pattern
1134 -g = interpret pattern as a glob pattern
1135 -i = ignore the letter case of the files
1136 -k = keep the console open when changing a directory with the command
1137 -l = letter skipping; e.g. allow "rdme" to match the file "readme"
1138 -m = mark the matching files after pressing enter
1139 -M = unmark the matching files after pressing enter
1140 -p = permanent filter: hide non-matching files after pressing enter
1141 -s = smart case; like -i unless pattern contains upper case letters
1142 -t = apply filter and search pattern as you type
1143 -v = inverts the match
1145 Multiple flags can be combined. For example, ":scout -gpt" would create
1146 a :filter-like command using globbing.
1148 =item search I<pattern>
1150 Search files in the current directory that match the given (case insensitive)
1151 regular expression pattern.
1153 This command is based on the I<scout> command and supports all of its options.
1155 =item search_inc I<pattern>
1157 Search files in the current directory that match the given (case insensitive)
1158 regular expression pattern. This command gets you to matching files as you
1161 This command is based on the I<scout> command and supports all of its options.
1163 =item set I<option> I<value>
1165 Assigns a new value to an option. Valid options are listed in the settings
1166 section. Use tab completion to get the current value of an option, though this
1167 doesn't work for functions and regular expressions. Valid values are:
1169 setting type | example values
1170 ---------------+----------------------------
1172 integer | 1, 23, 1337
1173 string | foo, hello world
1177 =item setlocal [path=I<path>] I<option> I<value>
1179 Assigns a new value to an option, but locally for the directory given by
1180 I<path>. This means, that this option only takes effect when visiting that
1181 directory. If no path is given, uses the current directory.
1183 =item shell [-I<flags>] I<command>
1185 Run a shell command. I<flags> are discussed in their own section.
1189 Spawns the I<x-terminal-emulator> starting in the current directory.
1191 =item tmap I<key> I<command>
1193 Binds keys for the taskview. Works like the C<map> command.
1195 =item touch I<filename>
1197 Creates an empty file with the name I<filename>, unless it already exists.
1199 =item travel I<pattern>
1201 Filters the current directory for files containing the letters in the
1202 string, possibly with other letters in between. The filter is applied as
1203 you type. When only one directory is left, it is entered and the console
1204 is automatically reopened, allowing for fast travel.
1205 To close the console, press ESC or execute a file.
1207 This command is based on the I<scout> command and supports all of its options.
1209 =item tunmap [I<keys ...>]
1211 Removes key mappings of the taskview. Works like the C<unmap> command.
1213 =item unmap [I<keys> ...]
1215 Removes the given key mappings in the "browser" context. To unmap key bindings
1216 in the console, taskview, or pager use "cunmap", "tunmap" or "punmap".
1218 =item unmark I<pattern>
1220 Unmark all files matching a regular expression pattern.
1222 This command is based on the I<scout> command and supports all of its options.
1224 =item unmark_tag [I<tags>]
1226 Unmark all tags that are tagged with either of the given tags. When leaving
1227 out the tag argument, all tagged files are unmarked.
1236 ranger reads several configuration files which are located in
1237 F<$HOME/.config/ranger> or F<$XDG_CONFIG_HOME/ranger> if $XDG_CONFIG_HOME is
1238 defined. You can use the --copy-config option to obtain the default
1239 configuration files. Each of the files contains further documentation.
1241 You don't need to copy the whole file though, most configuration files are
1242 overlaid on top of the defaults (F<commands.py>, F<rc.conf>) or can be
1243 sub-classed (F<colorschemes>).
1245 That being said, the user configuration files F<rc.conf> and F<commands.py> are
1246 loaded only after ranger loads the default configuration files. This may lead
1247 to some confusing situations, for example when a key is being bound despite the
1248 corresponding line being removed from the user's copy of the configuration
1249 file. This behavior may be disabled with an environment variable (see also:
1252 When starting ranger with the B<--clean> option, it will not access or create
1255 =head2 CONFIGURATION
1261 Contains a list of commands which are executed on startup. Mostly key bindings
1262 and settings are defined here.
1266 A python module that defines commands which can be used in ranger's console by
1267 typing ":" or in the rc.conf file.
1271 This is the configuration file for the built-in file launcher called "rifle".
1275 This is a script that handles file previews. When the options
1276 I<use_preview_script> and I<preview_files> are set, the program specified in
1277 the option I<preview_script> is run and its output and/or exit code determines
1282 Colorschemes can be placed here.
1286 Plugins can be placed here.
1296 This file contains a list of bookmarks. The syntax is /^(.):(.*)$/. The first
1297 character is the bookmark key and the rest after the colon is the path to the
1298 file. In ranger, bookmarks can be set by typing m<key>, accessed by typing
1299 '<key> and deleted by typing um<key>.
1303 When running the command :save_copy_buffer, the paths of all currently copied
1304 files are saved in this file. You can later run :load_copy_buffer to copy the
1305 same files again, pass them to another ranger instance or process them in a
1310 Contains a list of commands that have been previously typed in.
1314 Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first
1315 letter is the optional name of the tag and the rest after the optional colon is
1316 the path to the file. In ranger, tags can be set by pressing t and removed
1317 with T. To assign a named tag, type "<tagname>.
1326 These environment variables have an effect on ranger:
1332 ranger sets this environment variable to "1" or increments it if it already
1333 exists. External programs can determine whether they were spawned from ranger
1334 by checking for this variable.
1336 =item RANGER_LOAD_DEFAULT_RC
1338 If this variable is set to FALSE, ranger will not load the default rc.conf.
1339 This can save time if you copied the whole rc.conf to ~/.config/ranger/ and
1340 don't need the default one at all.
1344 Defines the editor to be used for the "E" key. Defaults to "nano".
1348 Defines the shell that ranger is going to use with the :shell command and
1349 the "S" key. Defaults to "/bin/sh".
1353 Defines the terminal emulator command that ranger is going to use with the
1354 :terminal command and the "t" run flag. Defaults to "xterm".
1357 =item XDG_CONFIG_HOME
1359 Specifies the directory for configuration files. Defaults to F<$HOME/.config>.
1361 =item PYTHONOPTIMIZE
1363 This variable determines the optimize level of python.
1365 Using PYTHONOPTIMIZE=1 (like python -O) will make python discard assertion
1366 statements. You will gain efficiency at the cost of losing some debug info.
1368 Using PYTHONOPTIMIZE=2 (like python -OO) will additionally discard any
1369 docstrings. Using this will disable the <F1> key on commands.
1371 =item W3MIMGDISPLAY_PATH
1373 By changing this variable, you can change the path of the executable file for
1374 image previews. By default, it is set to F</usr/lib/w3m/w3mimgdisplay>.
1383 There are various examples on how to extend ranger with plugins or combine
1384 ranger with other programs. These can be found in the
1385 F</usr/share/doc/ranger/examples/> directory, or the F<doc/ranger/> that is
1386 provided along with the source code.
1393 GNU General Public License 3 or (at your option) any later version.
1402 =item Download: L<http://ranger.nongnu.org/ranger-stable.tar.gz>
1404 =item The project page: L<http://ranger.nongnu.org/>
1406 =item The mailing list: L<http://savannah.nongnu.org/mail/?group=ranger>
1408 =item IRC channel: #ranger on freenode.net
1412 ranger is maintained with the git version control system. To fetch a fresh
1415 git clone git://git.savannah.nongnu.org/ranger.git
1429 Report bugs here: L<https://github.com/hut/ranger/issues>
1431 Please include as much relevant information as possible. For the most
1432 diagnostic output, run ranger like this: C<PYTHONOPTIMIZE= ranger --debug>