diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING | 28 | ||||
| -rw-r--r-- | doc/TODO | 119 | ||||
| l--------- | doc/help | 1 | ||||
| -rw-r--r-- | doc/ranger.1 | 1139 | ||||
| -rw-r--r-- | doc/ranger.pod | 1034 |
5 files changed, 1959 insertions, 362 deletions
diff --git a/doc/HACKING b/doc/HACKING index dd384758..f6d5d064 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -10,7 +10,7 @@ Coding Style http://www.python.org/dev/peps/pep-0008/ * Although this guide suggests otherwise, tabs are used for indentation of code and docstrings. In other documents (readme, etc), use spaces. -* Test the code with unit tests where it makes sense +* Test the code with "doctest" where it makes sense Patches @@ -35,29 +35,25 @@ ranger/fsobject/fsobject.py About the UI: ranger/gui/widgets/browsercolumn.py ranger/gui/widgets/browserview.py -ranger/gui/defaultui.py +ranger/gui/ui.py Common Changes -------------- * Change which files are previewed in the auto preview: -In ranger/gui/widget/browsercolumn.py +In ranger/fsobject/file.py the constant PREVIEW_BLACKLIST * Adding options: In ranger/defaults/options.py add the default value, like: my_option = True -In ranger/shared/settings.py +In ranger/container/settingobject.py add the name of your option to the constant ALLOWED_SETTINGS The setting is now accessible at self.settings.my_option, assuming <self> is a "SettingsAware" object. -* Changing commands, adding aliases: -ranger/defaults/commands.py -or ~/.config/ranger/commands.py - * Adding colorschemes: Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py and modify it according to your needs. Alternatively, mimic the jungle @@ -66,15 +62,6 @@ In ranger/defaults/options.py (or ~/.config/ranger/options.py), change colorscheme = 'default' to: colorscheme = 'myscheme' -* Change which files are considered to be "hidden": -In ranger/defaults/options.py -change the hidden_filter regular expression. - -* Change the key map: -Modify ranger/defaults/keys.py. This should be self-explanatory. -Check out ranger/core/actions.py for the most common actions, of course -you can also use your own functions. - * Change the file type => application associations: In ranger/defaults/apps.py modify the method app_default. @@ -88,8 +75,5 @@ Modify ranger/data/mime.types Version Numbering ----------------- -X.Y.Z, where: - -* X: Major version, milestone -* Y: Minor version, even number => stable version -* Z: Revision, may be omitted if zero +Three numbers; The first changes on a rewrite, the second changes when major +configuration incompatibilities occur and the third changes with each release. diff --git a/doc/TODO b/doc/TODO deleted file mode 100644 index 1577f97a..00000000 --- a/doc/TODO +++ /dev/null @@ -1,119 +0,0 @@ -Console - - (X) #0 09/12/06 console commands - (X) #1 09/12/06 quick find - (X) #2 09/12/06 open with - (X) #4 09/12/06 history for console - (X) #13 09/12/27 display docstring of a command - - -General - - (X) #5 09/12/06 move code from fm into objects - (X) #6 09/12/06 move main to __init__ - (X) #7 09/12/06 cooler titlebar - (X) #8 09/12/17 Add operations to modify files/directories - (X) #9 09/12/24 add a widget for managing running operations - (X) #10 09/12/24 sorting - (X) #11 09/12/27 filter - (X) #12 09/12/27 jump through the list in a specific order - (X) #14 09/12/29 make filelists inherit from pagers - (X) #15 09/12/29 better way of running processes!!~ - (X) #16 10/01/01 list of bookmarks - (X) #21 10/01/01 write help! - (X) #22 10/01/03 add getopt options to change flags/mode - (X) #29 10/01/06 add chmod command - (X) #30 10/01/06 add a way to create symlinks - (X) #32 10/01/08 place the (hidden) cursor to a meaningful position - (X) #34 10/01/09 display free disk space - (X) #35 10/01/09 display disk usage of files in current directory - ( ) #36 10/01/11 help coloring is terribly inefficient - (X) #37 10/01/13 better tab completion for OpenConsole - ( ) #38 10/01/16 searching in pager - (X) #39 10/01/17 flushinput not always good - (X) #42 10/01/17 memorize directory for `` when using :cd - (X) #43 10/01/18 internally treat the bookmarks ` and ' the same - ( ) #44 10/01/18 more error messages :P - (X) #47 10/01/19 less restricive auto preview - (X) #48 10/01/19 abbreviate commands with first unambiguous substring - ( ) #50 10/01/19 add more unit tests - ( ) #51 10/01/21 remove directory.marked_items ? - (X) #55 10/01/24 allow change of filename when pasting - you're given the choice between overwriting or appending a "_" - ( ) #56 10/01/30 warn before deleting mount points - ( ) #57 10/01/30 warn before deleting unseen marked files - (X) #58 10/02/04 change the title of the terminal - (X) #61 10/02/09 show sum of size of marked files - (X) #63 10/02/15 limit filesize in previews - ( ) #64 10/02/25 scroll in previews - (X) #66 10/02/28 explain how colorschemes work - (X) #70 10/03/14 mouse handler for titlebar - (X) #71 10/03/21 previews: black/whitelist + read file - (X) #79 10/04/08 tab number zero - ( ) #80 10/04/08 when closing tabs, avoid gaps? - (X) #81 10/04/15 system crash when previewing /proc/kcore with root permissions - (X) #83 10/04/19 better ways to mark files. eg by regexp, filetype,.. - ( ) #86 10/04/21 narg for move_parent - ( ) #60 10/02/05 utf support improvable - ( ) #91 10/05/12 in keys.py, fm.move(right=N) should run with mode=N - ( ) #92 10/05/14 allow to enter the realpath of a directory - ( ) #93 10/05/15 pause after running program - - -Bugs - - (X) #17 10/01/01 why do bookmarks disappear sometimes? - (X) #18 10/01/01 fix notify widget (by adding a LogView?) - (X) #19 10/01/01 resizing after pressing g - (X) #23 10/01/04 stop dir loading with ^C -> wont load anymore - (X) #25 10/01/06 directories sometimes dont reload correctly - (X) #26 10/01/06 :delete on symlinks of directories fails - (X) #31 10/01/06 ^C breaks cd-after-exit by stopping sourced shell script - (X) #40 10/01/17 freeze with unavailable sshfs - Not rangers fault (?) - (X) #41 10/01/17 capital file extensions are not recognized - (X) #46 10/01/19 old username displayed after using su - (X) #49 10/01/19 fix unit tests :'( - (X) #52 10/01/23 special characters in tab completion - (X) #54 10/01/23 max_dirsize_for_autopreview not working - (X) #62 10/02/15 curs_set can raise an exception - (X) #65 10/02/16 "source ranger ranger some/file.txt" shouldn't cd after exit - (X) #67 10/03/08 terminal title in tty - (X) #69 10/03/11 tab-completion breaks with Apps subclass - (X) #73 10/03/21 when clicking on the first column, it goes 1x down - (X) #74 10/03/21 console doesn't scroll - (X) #78 10/03/31 broken preview when deleting all files in a directory - (X) #85 10/04/26 no automatic reload of directory after using :filter - (X) #87 10/05/10 files are not properly closed after previewing - ( ) #88 10/05/10 race conditions for data loading from FS - (X) #90 10/05/11 no link target for broken links - ( ) #94 10/05/26 "pressed keys" text cut off when chaining ctrl-XYZ keys - - -Ideas - - ( ) #20 10/01/01 use inotify to monitor filesystem changes - ( ) #24 10/01/06 progress bar - (X) #27 10/01/06 hide bookmarks in list which contain hidden dir - (X) #28 10/01/06 use regexp instead of string for searching - (X) #33 10/01/08 accelerate mousewheel speed - won't do this - (X) #45 10/01/18 hooks for events like setting changes - (X) #53 10/01/23 merge fm and environment - won't do this - (X) #68 10/03/10 threads, to seperate ui and loading - won't do this - ( ) #72 10/03/21 ranger daemon which does the slow io tasks - ( ) #75 10/03/28 navigate in history - (X) #76 10/03/28 save history between sessions - (X) #77 10/03/28 colorscheme overlay in options.py - ( ) #82 10/04/19 :s command for batch renaming - ( ) #84 10/04/25 use pygments for syntax highlighting - ( ) #89 10/05/10 branch view - - -Blocking - - ( ) #60 10/02/05 utf support improvable - (X) #81 10/04/15 system crash when previewing /proc/kcore with root permissions - diff --git a/doc/help b/doc/help deleted file mode 120000 index 09ad0c73..00000000 --- a/doc/help +++ /dev/null @@ -1 +0,0 @@ -../ranger/help \ No newline at end of file diff --git a/doc/ranger.1 b/doc/ranger.1 index 08776fc7..da98f718 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -1,235 +1,934 @@ -.TH RANGER 1 ranger-1.4.4 -.SH NAME -ranger - visual file manager -.\"----------------------------------------- -.SH SYNOPSIS -.B ranger -.R [OPTIONS] [FILE] -.\"----------------------------------------- -.SH DESCRIPTION -Ranger is a file manager with an ncurses frontend written in Python. -.P -It is designed to give you a broader overview of the file system by displaying -previews and backviews, dividing the screen into several columns. -The keybindings are similar to those of other console programs like -.BR vim ", " mutt " or " ncmpcpp -so the usage will be intuitive and efficient. -.\"----------------------------------------- -.SH OPTIONS -.TP ---version -Print the version and exit. -.TP --h, --help -Print a list of options and exit. -.TP --d, --debug -Activate the debug mode: Whenever an error occurs, ranger will exit and -print a full backtrace. The default behaviour is to merely print the -name of the exception in the statusbar/log and to try to keep running. -.TP --c, --clean -Activate the clean mode: Ranger will not access or create any configuration -files nor will it leave any traces on your system. This is useful when -your configuration is broken, when you want to avoid clutter, etc. -.TP ---choosefile=\fItargetfile\fR +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RANGER 1" +.TH RANGER 1 "ranger-1.5.0" "10/11/2011" "ranger manual" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ranger \- visual file manager +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBranger\fR [\fB\-\-help\fR] [\fB\-\-version\fR] [\fB\-\-debug\fR] [\fB\-\-clean\fR] +[\fB\-\-list\-unused\-keys\fR] [\fB\-\-fail\-unless\-cd\fR] [\fB\-\-choosedir\fR=\fItargetfile\fR] +[\fB\-\-choosefile\fR=\fItargetfile\fR] [\fB\-\-copy\-config\fR=\fIfile\fR] [\fB\-\-mode\fR=\fImode\fR] +[\fB\-\-flags\fR=\fIflags\fR] [\fIpath/filename\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +ranger is a console file manager with \s-1VI\s0 key bindings. It provides a +minimalistic and nice curses interface with a view on the directory hierarchy. +The secondary task of ranger is to figure out which program you want to use to +open your files with. +.PP +This manual mainly contains information on the usage of ranger. Refer to the +\&\fI\s-1README\s0\fR for install instructions and to \fIdoc/HACKING\fR for development +specific information. For configuration, see the files in \fIranger/defaults\fR. +They are usually installed to \fI/usr/lib/python*/site\-packages/ranger/defaults\fR +and can be obtained with ranger's \-\-copy\-config option. +.PP +Inside ranger, you can press \fI1?\fR for a list of key bindings, \fI2?\fR for a list +of commands and \fI3?\fR for a list of settings. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-d\fR, \fB\-\-debug\fR" 14 +.IX Item "-d, --debug" +Activate the debug mode: Whenever an error occurs, ranger will exit and print a +full traceback. The default behavior is to merely print the name of the +exception in the statusbar/log and try to keep running. +.IP "\fB\-c\fR, \fB\-\-clean\fR" 14 +.IX Item "-c, --clean" +Activate the clean mode: ranger will not access or create any configuration +files nor will it leave any traces on your system. This is useful when your +configuration is broken, when you want to avoid clutter, etc. +.IP "\fB\-\-choosefile\fR=\fItargetfile\fR" 14 +.IX Item "--choosefile=targetfile" Allows you to pick a file with ranger. This changes the behavior so that when you open a file, ranger will exit and write the name of that file into -\fItargetfile\fR -.TP ---choosedir=\fItargetfile\fR +\&\fItargetfile\fR. +.IP "\fB\-\-choosedir\fR=\fItargetfile\fR" 14 +.IX Item "--choosedir=targetfile" Allows you to pick a directory with ranger. When you exit ranger, it will -write the last visited directory into \fItargetfile\fR -.TP ---copy-config=\fIwhich\fR +write the last visited directory into \fItargetfile\fR. +.IP "\fB\-\-copy\-config\fR=\fIfile\fR" 14 +.IX Item "--copy-config=file" Create copies of the default configuration files in your local configuration -directory. Existing ones will not be overwritten. Possible values: -all, apps, commands, keys, options, scope. -.TP ---fail-unless-cd -Return the exit code 1 if ranger is used to run a file, for example with -`ranger --fail-unless-cd filename`. This can be useful for scripts. -.TP --r \fIdir\fR, --confdir=\fIdir\fR -Define a different configuration directory. The default is -$XDG_CONFIG_HOME/ranger (which defaults to ~/.config/ranger) -.TP --m \fIn\fR, --mode=\fIn\fR -When a filename is supplied, make it run in mode \fIn\fR. Check the -documentation for more information on modes. -.TP --f \fIflags\fR, --flags=\fIflags\fR -When a filename is supplied, make it run with the flags \fIflags\fR. Check the -documentation for more information on flags. -.\"----------------------------------------- -.SH USAGE -.\"----------------------------------------- -.SS General Keybindings -Many keybindings take an additional numeric argument. Type \fI5j\fR to move -down 5 lines, \fI10<Space>\fR to mark 10 files or \fI3?\fR to read the -third chapter of the documentation. -.TP -h, j, k, l -Move left, down, up, right -.TP -^D or J, ^U or K +directory. Existing ones will not be overwritten. Possible values: \fIall\fR, +\&\fIrc\fR, \fIapps\fR, \fIcommands\fR, \fIoptions\fR, \fIscope\fR. +.IP "\fB\-\-list\-unused\-keys\fR" 14 +.IX Item "--list-unused-keys" +List common keys which are not bound to any action in the \*(L"browser\*(R" context. +This list is not complete, you can bind any key that is supported by curses: +use the key code returned by \f(CW\*(C`getch()\*(C'\fR. +.IP "\fB\-\-fail\-unless\-cd\fR" 14 +.IX Item "--fail-unless-cd" +Return the exit code 1 if ranger is used to run a file instead of used for file +browsing. (For example, \*(L"ranger \-\-fail\-unless\-cd test.txt\*(R" returns 1.) +.IP "\fB\-m\fR \fIn\fR, \fB\-\-mode\fR=\fIn\fR" 14 +.IX Item "-m n, --mode=n" +When a filename is supplied, run it in mode \fIn\fR. This has no effect unless +the execution of this file type is explicitly handled in the configuration. +.IP "\fB\-f\fR \fIflags\fR, \fB\-\-flags\fR=\fIflags\fR" 14 +.IX Item "-f flags, --flags=flags" +When a filename is supplied, run it with the given \fIflags\fR to modify +behavior. The execution of this file type is explicitly handled in the +configuration. +.IP "\fB\-\-version\fR" 14 +.IX Item "--version" +Print the version and exit. +.IP "\fB\-h\fR, \fB\-\-help\fR" 14 +.IX Item "-h, --help" +Print a list of options and exit. +.SH "CONCEPTS" +.IX Header "CONCEPTS" +.SS "\s-1TAGS\s0" +.IX Subsection "TAGS" +Tags are single characters which are displayed left of a filename. You can use +tags however you want. Press \*(L"t\*(R" to toggle tags and \*(L"T\*(R" to remove any tags of +the selection. The default tag is an Asterisk (\*(L"*\*(R"), but you can use any tag by +typing \fI"<tagname>\fR. +.SS "\s-1PREVIEWS\s0" +.IX Subsection "PREVIEWS" +By default, only text files are previewed, but you can enable external preview +scripts by setting the option \f(CW\*(C`use_preview_script\*(C'\fR and \f(CW\*(C`preview_files\*(C'\fR to True. +.PP +This default script is \fI~/.config/ranger/scope.sh\fR. It contains more +documentation and calls to the programs \fIlynx\fR and \fIelinks\fR for html, +\&\fIhighlight\fR for text/code, \fIimg2txt\fR for images, \fIatool\fR for archives, +\&\fIpdftotext\fR for PDFs and \fImediainfo\fR for video and audio files. +.PP +Install these programs (just the ones you need) and scope.sh will automatically +use them. +.SS "\s-1SELECTION\s0" +.IX Subsection "SELECTION" +The \fIselection\fR is defined as \*(L"All marked files \s-1IF\s0 \s-1THERE\s0 \s-1ARE\s0 \s-1ANY\s0, otherwise +the current file.\*(R" Be aware of this when using the :delete command, which +deletes all files in the selection. +.PP +You can mark files by pressing <Space>, v, etc. A yellow \fBMrk\fR symbol at the +bottom right indicates that there are marked files in this directory. +.SS "\s-1MACROS\s0" +.IX Subsection "MACROS" +Macros can be used in commands to abbreviate things. +.PP +.Vb 5 +\& %f the highlighted file +\& %d the path of the current directory +\& %s the selected files in the current directory. +\& %t all tagged files in the current directory +\& %c the full paths of the currently copied/cut files +.Ve +.PP +The macros \f(CW%f\fR, \f(CW%d\fR and \f(CW%s\fR also have upper case variants, \f(CW%F\fR, \f(CW%D\fR and \f(CW%S\fR, +which refer to the next tab. To refer to specific tabs, add a number in +between. (%7s = selection of the seventh tab.) +.PP +\&\f(CW%c\fR is the only macro which ranges out of the current directory. So you may +\&\*(L"abuse\*(R" the copying function for other purposes, like diffing two files which +are in different directories: +.PP +.Vb 2 +\& Yank the file A (type yy), move to the file B, then type +\& @diff %c %f +.Ve +.PP +Macros for file paths are generally shell-escaped so they can be used in the +:shell command. +.SS "\s-1BOOKMARKS\s0" +.IX Subsection "BOOKMARKS" +Type \fBm<key>\fR to bookmark the current directory. You can re-enter this +directory by typing \fB`<key>\fR. <key> can be any letter or digit. Unlike vim, +both lowercase and uppercase bookmarks are persistent. +.PP +Each time you jump to a bookmark, the special bookmark at key ` will be set +to the last directory. So typing \*(L"``\*(R" gets you back to where you were before. +.PP +Bookmarks are selectable when tabbing in the :cd command. +.PP +Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. +.SS "\s-1FLAGS\s0" +.IX Subsection "FLAGS" +Flags give you a way to modify the behavior of the spawned process. They are +used in the commands :open_with (key \*(L"r\*(R") and :shell (key \*(L"!\*(R"). +.PP +.Vb 5 +\& s Silent mode. Output will be discarded. +\& d Detach the process. (Run in background) +\& p Redirect output to the pager +\& w Wait for an Enter\-press when the process is done +\& c Run the current file only, instead of the selection +.Ve +.PP +By default, all the flags are off unless specified otherwise in the \fIapps.py\fR +configuration file. You can specify as many flags as you want. An uppercase +flag negates the effect: \*(L"ddcccDs\*(R" is equivalent to \*(L"cs\*(R". +.PP +Examples: \f(CW\*(C`:open_with p\*(C'\fR will pipe the output of that process into +the pager. \f(CW\*(C`:shell \-w df\*(C'\fR will run \*(L"df\*(R" and wait for you to press Enter before +switching back to ranger. +.SS "\s-1MODES\s0" +.IX Subsection "MODES" +By specifying a mode (a positive integer), you can tell ranger what to do with +a file when running it. You can specify which mode to use by typing <mode>l or +<mode><Enter> or :open_with <mode>. The default mode is 0. +.PP +Examples: \f(CW\*(C`l\*(C'\fR (mode zero) to list the contents of an archive, \f(CW\*(C`1l\*(C'\fR (mode one) +to extract an archive. See the \fIapps.py\fR configuration file for all programs +and modes. +.SH "KEY BINDINGS" +.IX Header "KEY BINDINGS" +Key bindings are defined in the file \fIranger/defaults/rc.conf\fR. Check this +file for a list of all key bindings. You can copy it to your local +configuration directory with the \-\-copy\-config=rc option. +.PP +Many key bindings take an additional numeric argument. Type \fI5j\fR to move +down 5 lines, \fI2l\fR to open a file in mode 2, \fI10<Space>\fR to mark 10 files. +.PP +This list contains the most useful bindings: +.SS "\s-1MAIN\s0 \s-1BINDINGS\s0" +.IX Subsection "MAIN BINDINGS" +.IP "h, j, k, l" 14 +.IX Item "h, j, k, l" +Move left, down, up or right +.IP "^D or J, ^U or K" 14 +.IX Item "^D or J, ^U or K" Move a half page down, up -.TP -H, L +.IP "H, L" 14 +.IX Item "H, L" Move back and forward in the history -.TP -gg +.IP "gg" 14 +.IX Item "gg" Move to the top -.TP -G +.IP "G" 14 +.IX Item "G" Move to the bottom -.TP -^R +.IP "^R" 14 +.IX Item "^R" Reload everything -.TP -^L +.IP "^L" 14 +.IX Item "^L" Redraw the screen -.TP -S +.IP "S" 14 +.IX Item "S" Open a shell in the current directory -.TP -yy -Yank the selection to the "copy" buffer and mark them as to be copied -.TP -dd -Cut the selection to the "copy" buffer and mark them as to be moved -.TP -pp -Paste the files from the "copy" buffer here (by moving or copying, depending -on how they are marked.) By default, this will not overwrite existing files. -To overwrite them, use \fBpo\fR. -.TP -m\fIX\fR +.IP "?" 14 +Opens this man page +.IP "yy" 14 +.IX Item "yy" +Yank the selection to the \*(L"copy\*(R" buffer and mark them as to be copied +.IP "dd" 14 +.IX Item "dd" +Cut the selection to the \*(L"copy\*(R" buffer and mark them as to be moved +.IP "pp" 14 +.IX Item "pp" +Paste the files from the \*(L"copy\*(R" buffer here (by moving or copying, depending on +how they are marked.) By default, this will not overwrite existing files. To +overwrite them, use \fIpo\fR. +.IP "m\fIX\fR" 14 +.IX Item "mX" Create a bookmark with the name \fIX\fR -.TP -`\fIX\fR +.IP "`\fIX\fR" 14 +.IX Item "`X" Move to the bookmark with the name \fIX\fR -.TP -n, N -Find the next file, the previous file. You can define what to look for -by typing c\fIX\fR. If nothing is specified, pressing n will get you to -the newest file in the directory. -.TP -o\fIX\fR +.IP "n, N" 14 +.IX Item "n, N" +Find the next file. By default, this gets you to the newest file in the +directory, but if you search something using the keys /, cm, ct, ..., it will +get you to the next found entry. +.IP "N" 14 +.IX Item "N" +Find the previous file. +.IP "o\fIX\fR" 14 +.IX Item "oX" Change the sort method (like in mutt) -.TP -z\fIX\fR -Change settings -.TP -f -Quickly navigate by entering a part of the filename -.TP -Space -Mark a file -.TP -v, V -Toggle the mark-status of all files, unmark all files -.TP -/ -Open the search console -.TP -: -Open the command console -.TP -? -Opens the help screen with more keybindings and documentation -.\"----------------------------------------- -.SS Keybindings for using Tabs -Tabs are used to work in different directories in the same Ranger instance. -.TP -g\fIN\fR -Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, -it will be created. -.TP -gn, ^N +.IP "z\fIX\fR" 14 +.IX Item "zX" +Change settings. See the settings section for a list of settings and their +hotkey. +.IP "f" 14 +.IX Item "f" +Quickly navigate by entering a part of the filename. +.IP "Space" 14 +.IX Item "Space" +Mark a file. +.IP "v" 14 +.IX Item "v" +Toggle the mark-status of all files, unmark all files. +.IP "V, uv" 14 +.IX Item "V, uv" +Unmark all files +.IP "/" 14 +Search for files in the current directory. +.IP ":" 14 +Open the console. +.IP "Alt\-\fIN\fR" 14 +.IX Item "Alt-N" +Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it +will be created. +.IP "gn, ^N" 14 +.IX Item "gn, ^N" Create a new tab. -.TP -gt, gT -Go to the next or previous tab. You can also use TAB and SHIFT+TAB. -.TP -gc, ^W -Close the current tab. The last tab cannot be closed. -.P -.\"----------------------------------------- -.SS Mouse Usage -.TP -Left Mouse Button -Click on something and you'll move there. -To run a file, "enter" it, like a directory, by clicking on the preview. -.TP -Right Mouse Button -Enter a directory -.TP -Scroll Wheel -Scroll -.\"----------------------------------------- -.SS Commands -.TP -:delete -Destroy all files in the selection with a roundhouse kick. Ranger will -ask for a confirmation if you attempt to delete multiple (marked) files or -non-empty directories. -.TP -:rename \fInewname\fR -Rename the current file. Also try the keybinding A for appending something -to a file name. -.TP -:quit -Quit ranger. The current directory will be bookmarked as ' so you can -re-enter it by typing `` or '' the next time you start ranger. -.\"----------------------------------------- -.SH TIPS -.SS -Change the directory after exit -A script like this in your bashrc would make you change the directory -of your parent shell after exiting ranger: -.nf - -ranger() { - command ranger --fail-unless-cd $@ && - cd "$(grep \\^\\' ~/.config/ranger/bookmarks | cut -b3-)" -} -.\"----------------------------------------- -.SH CONFIGURATION -The files in -.B ranger/defaults/ -can be copied into your configuration directory (by default, this is -~/.config/ranger) and customized according to your wishes. -Most files don't have to be copied completely though: Just define those -settings you want to add or change and they will override the defauls. -Colorschemes can be placed in ~/.config/ranger/colorschemes. -.P -All configuration is done in Python. -Each configuration file should contain sufficient documentation. -.\"----------------------------------------- -.SH COPYRIGHT -Copyright \(co -2009, 2010 -Roman Zimbelmann -.P -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -There is NO warranty; -not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -.\"----------------------------------------- -.SH SEE ALSO -The project page: -.RB < http://ranger.nongnu.org/ > -.P -The mailing list: -.RB < http://savannah.nongnu.org/mail/?group=ranger > -.\"----------------------------------------- -.SH BUGS -Please report them here and include as much relevant information -as possible: -.P -.RB < http://savannah.nongnu.org/bugs/?group=ranger > +.IP "gt, gT" 14 +.IX Item "gt, gT" +Go to the next or previous tab. You can also use \s-1TAB\s0 and \s-1SHIFT+TAB\s0 instead. +.IP "gc, ^W" 14 +.IX Item "gc, ^W" +Close the current tab. The last tab cannot be closed this way. +.SS "\s-1MIDNIGHT\s0 COMMANDER-LIKE \s-1BINDINGS\s0" +.IX Subsection "MIDNIGHT COMMANDER-LIKE BINDINGS" +.IP "<F1>" 14 +.IX Item "<F1>" +Display Help. +.IP "<F3>" 14 +.IX Item "<F3>" +Display the file. +.IP "<F4>" 14 +.IX Item "<F4>" +Edit the file. +.IP "<F5>" 14 +.IX Item "<F5>" +Copy the file. +.IP "<F6>" 14 +.IX Item "<F6>" +Cut the file. +.IP "<F7>" 14 +.IX Item "<F7>" +Open the console with \*(L":mkdir \*(R". +.IP "<F8>" 14 +.IX Item "<F8>" +Prompt for deletion of the selected files. +.IP "<F10>" 14 +.IX Item "<F10>" +Exit ranger. +.SS "READLINE-LIKE \s-1BINDINGS\s0 \s-1IN\s0 \s-1THE\s0 \s-1CONSOLE\s0" +.IX Subsection "READLINE-LIKE BINDINGS IN THE CONSOLE" +.IP "^B, ^F" 14 +.IX Item "^B, ^F" +Move left and right (B for back, F for forward) +.IP "^P, ^N" 14 +.IX Item "^P, ^N" +Move up and down (P for previous, N for Next) +.IP "^A, ^E" 14 +.IX Item "^A, ^E" +Move to the start or to the end +.IP "^D" 14 +.IX Item "^D" +Delete the current character. +.IP "^H" 14 +.IX Item "^H" +Backspace. +.SH "MOUSE BUTTONS" +.IX Header "MOUSE BUTTONS" +.IP "Left Mouse Button" 4 +.IX Item "Left Mouse Button" +Click on something and you'll move there. To run a file, \*(L"enter\*(R" it, like a +directory, by clicking on the preview. +.IP "Right Mouse Button" 4 +.IX Item "Right Mouse Button" +Enter a directory or run a file. +.IP "Scroll Wheel" 4 +.IX Item "Scroll Wheel" +Scrolls up or down. You can point at the column of the parent directory to +switch directories. +.SH "SETTINGS" +.IX Header "SETTINGS" +This section lists all built-in settings of ranger. The valid types for the +value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if +a hotkey exists. +.PP +Settings can be changed in the file \fI~/.config/ranger/options.py\fR or on the +fly with the command \fB:set option value\fR. Examples: + :set column_ratios (1,2,3) + :set show_hidden=True +.IP "autosave_bookmarks [bool]" 4 +.IX Item "autosave_bookmarks [bool]" +Save bookmarks (used with mX and `X) instantly? This helps to synchronize +bookmarks between multiple ranger instances but leads to *slight* performance +loss. When false, bookmarks are saved when ranger is exited. +.IP "collapse_preview [bool] <zc>" 4 +.IX Item "collapse_preview [bool] <zc>" +When no preview is visible, should the last column be squeezed to make use of +the whitespace? +.IP "colorscheme_overlay [function, None]" 4 +.IX Item "colorscheme_overlay [function, None]" +An overlay function for colorschemes. See the default options.py for an +explanation and an example. +.IP "colorscheme [string]" 4 +.IX Item "colorscheme [string]" +Which colorscheme to use? These colorschemes are available by default: +\&\fBdefault\fR, \fBdefault88\fR, \fBtexas\fR, \fBjungle\fR, \fBsnow\fR. Snow is monochrome, +texas and default88 use 88 colors. +.IP "column_ratios [tuple, list]" 4 +.IX Item "column_ratios [tuple, list]" +How many columns are there, and what are their relative widths? For example, a +value of (1, 1, 1) would mean 3 even sized columns. (1, 1, 1, 1, 4) means 5 columns +with the preview column being as large as the other columns combined. +.IP "dirname_in_tabs [bool]" 4 +.IX Item "dirname_in_tabs [bool]" +Display the directory name in tabs? +.IP "display_size_in_main_column [bool]" 4 +.IX Item "display_size_in_main_column [bool]" +Display the file size in the main column? +.IP "display_size_in_status_bar [bool]" 4 +.IX Item "display_size_in_status_bar [bool]" +Display the file size in the status bar? +.IP "display_tags_in_all_columns [bool]" 4 +.IX Item "display_tags_in_all_columns [bool]" +Display tags in all columns? +.IP "draw_bookmark_borders [bool]" 4 +.IX Item "draw_bookmark_borders [bool]" +Draw borders around the bookmark window? +.IP "draw_borders [bool]" 4 +.IX Item "draw_borders [bool]" +Draw borders around columns? +.IP "flushinput [bool] <zi>" 4 +.IX Item "flushinput [bool] <zi>" +Flush the input after each key hit? One advantage is that when scrolling down +with \*(L"j\*(R", ranger stops scrolling instantly when you release the key. One +disadvantage is that when you type commands blindly, some keys might get lost. +.IP "hidden_filter [regexp]" 4 +.IX Item "hidden_filter [regexp]" +A regular expression pattern for files which should be hidden. +.IP "max_console_history_size [integer, None]" 4 +.IX Item "max_console_history_size [integer, None]" +How many console commands should be kept in history? +.IP "max_history_size [integer, None]" 4 +.IX Item "max_history_size [integer, None]" +How many directory changes should be kept in history? +.IP "mouse_enabled [bool] <zm>" 4 +.IX Item "mouse_enabled [bool] <zm>" +Enable mouse input? +.IP "padding_right [bool]" 4 +.IX Item "padding_right [bool]" +When collapse_preview is on and there is no preview, should there remain a +little padding on the right? This allows you to click into that space to run +the file. +.IP "preview_directories [bool] <zP>" 4 +.IX Item "preview_directories [bool] <zP>" +Preview directories in the preview column? +.IP "preview_files [bool] <zp>" 4 +.IX Item "preview_files [bool] <zp>" +Preview files in the preview column? +.IP "preview_script [string, None]" 4 +.IX Item "preview_script [string, None]" +Which script should handle generating previews? If the file doesn't exist, or +use_preview_script is off, ranger will handle previews itself by just printing +the content. +.IP "save_console_history [bool]" 4 +.IX Item "save_console_history [bool]" +Should the console history be saved on exit? If disabled, the console history +is reset when you restart ranger. +.IP "scroll_offset [integer]" 4 +.IX Item "scroll_offset [integer]" +Try to keep this much space between the top/bottom border when scrolling. +.IP "shorten_title [integer, bool]" 4 +.IX Item "shorten_title [integer, bool]" +Trim the title of the window if it gets long? The number defines how many +directories are displayed at once, False turns off this feature. +.IP "show_cursor [bool]" 4 +.IX Item "show_cursor [bool]" +Always show the terminal cursor? +.IP "show_hidden_bookmarks [bool]" 4 +.IX Item "show_hidden_bookmarks [bool]" +Show dotfiles in the bookmark preview window? (Type ') +.IP "show_hidden [bool] <zh>, <^H>" 4 +.IX Item "show_hidden [bool] <zh>, <^H>" +Show hidden files? +.IP "sort_case_insensitive [bool] <zc>" 4 +.IX Item "sort_case_insensitive [bool] <zc>" +Sort case-insensitively? If true, \*(L"a\*(R" will be listed before \*(L"B\*(R" even though +its \s-1ASCII\s0 value is higher. +.IP "sort_directories_first [bool] <zd>" 4 +.IX Item "sort_directories_first [bool] <zd>" +Sort directories first? +.IP "sort_reverse [bool] <or>" 4 +.IX Item "sort_reverse [bool] <or>" +Sort reversed? +.IP "sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>" 4 +.IX Item "sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>" +Which sorting mechanism should be used? Choose one of \fBatime\fR, \fBbasename\fR, +\&\fBctime\fR, \fBmtime\fR, \fBnatural\fR, \fBtype\fR, \fBsize\fR +.Sp +Note: You can reverse the order by using an uppercase O in the key combination. +.IP "tilde_in_titlebar [bool]" 4 +.IX Item "tilde_in_titlebar [bool]" +Abbreviate \f(CW$HOME\fR with ~ in the title bar (first line) of ranger? +.IP "unicode_ellipsis [bool]" 4 +.IX Item "unicode_ellipsis [bool]" +Use a unicode \*(L"...\*(R" character instead of \*(L"~\*(R" to mark cut-off filenames? +.IP "update_title [bool]" 4 +.IX Item "update_title [bool]" +Set a window title? +.IP "use_preview_script [bool] <zv>" 4 +.IX Item "use_preview_script [bool] <zv>" +Use the preview script defined in the setting \fIpreview_script\fR? +.IP "xterm_alt_key [bool]" 4 +.IX Item "xterm_alt_key [bool]" +Enable this if key combinations with the Alt Key don't work for you. +(Especially on xterm) +.SH "COMMANDS" +.IX Header "COMMANDS" +You can enter the commands in the console which is opened by pressing \*(L":\*(R". +.PP +There are additional commands which are directly translated to python +functions, one for every method in the ranger.core.actions.Actions class. +They are not documented here, since they are mostly for key bindings, not to be +typed in by a user. Read the source if you are interested in them. +.IP "bulkrename" 2 +.IX Item "bulkrename" +This command opens a list of selected files in an external editor. After you +edit and save the file, it will generate a shell script which does bulk +renaming according to the changes you did in the file. +.Sp +This shell script is opened in an editor for you to review. After you close +it, it will be executed. +.IP "cd [\fIdirectory\fR]" 2 +.IX Item "cd [directory]" +The cd command changes the directory. The command \f(CW\*(C`:cd \-\*(C'\fR is equivalent to +typing ``. +.IP "chain \fIcommand1\fR[; \fIcommand2\fR[; \fIcommand3\fR...]]" 2 +.IX Item "chain command1[; command2[; command3...]]" +Combines multiple commands into one, separated by columns. +.IP "chmod \fIoctal_number\fR" 2 +.IX Item "chmod octal_number" +Sets the permissions of the selection to the octal number. +.Sp +The octal number is between 000 and 777. The digits specify the permissions for +the user, the group and others. A 1 permits execution, a 2 permits writing, a +4 permits reading. Add those numbers to combine them. So a 7 permits +everything. +.Sp +Key bindings in the form of [\-+]<who><what> and =<octal> also exist. For +example, \fB+ar\fR allows reading for everyone, \-ow forbids others to write and +=777 allows everything. +.Sp +See also: man 1 chmod +.IP "cmap \fIkey\fR \fIcommand\fR" 2 +.IX Item "cmap key command" +Binds keys for the console. Works like the \f(CW\*(C`map\*(C'\fR command. +.IP "console [\-p\fIN\fR] \fIcommand\fR" 2 +.IX Item "console [-pN] command" +Opens the console with the command already typed in. The cursor is placed at +\&\fIN\fR. +.IP "copycmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2 +.IX Item "copycmap key newkey [newkey2 ...]" +See \f(CW\*(C`copymap\*(C'\fR +.IP "copymap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2 +.IX Item "copymap key newkey [newkey2 ...]" +Copies the keybinding \fIkey\fR to \fInewkey\fR in the \*(L"browser\*(R" context. This is a +deep copy, so if you change the new binding (or parts of it) later, the old one +is not modified. +.Sp +To copy key bindings of the console, taskview, or pager use \*(L"copycmap\*(R", +\&\*(L"copytmap\*(R" or \*(L"copypmap\*(R". +.IP "copypmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2 +.IX Item "copypmap key newkey [newkey2 ...]" +See \f(CW\*(C`copymap\*(C'\fR +.IP "copytmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2 +.IX Item "copytmap key newkey [newkey2 ...]" +See \f(CW\*(C`copymap\*(C'\fR +.IP "cunmap \fIkey\fR \fIcommand\fR" 2 +.IX Item "cunmap key command" +Removes key mappings of the console. Works like the \f(CW\*(C`unmap\*(C'\fR command. +.IP "delete [\fIconfirmation\fR]" 2 +.IX Item "delete [confirmation]" +Destroy all files in the selection with a roundhouse kick. ranger will ask for +a confirmation if you attempt to delete multiple (marked) files or non-empty +directories. +.Sp +When asking for confirmation, this command will only proceed if the last given +word starts with a `y'. +.IP "edit [\fIfilename\fR]" 2 +.IX Item "edit [filename]" +Edit the current file or the file in the argument. +.IP "eval [\fI\-q\fR] \fIpython_code\fR" 2 +.IX Item "eval [-q] python_code" +Evaluates the python code. `fm' is a reference to the \s-1FM\s0 instance. To display +text, use the function `p'. The result is displayed on the screen unless you +use the \*(L"\-q\*(R" option. +.Sp +Examples: + :eval fm + :eval len(fm.env.directories) + :eval p(\*(L"Hello World!\*(R") +.IP "filter [\fIstring\fR]" 2 +.IX Item "filter [string]" +Displays only the files which contain the \fIstring\fR in their basename. +.IP "find \fIpattern\fR" 2 +.IX Item "find pattern" +Search files in the current directory that match the given (case-insensitive) +regular expression pattern as you type. Once there is an unambiguous result, +it will be run immediately. (Or entered, if it's a directory.) +.IP "grep \fIpattern\fR" 2 +.IX Item "grep pattern" +Looks for a string in all marked files or directories. +.IP "load_copy_buffer" 2 +.IX Item "load_copy_buffer" +Load the copy buffer from \fI~/.config/ranger/copy_buffer\fR. This can be used to +pass the list of copied files to another ranger instance. +.IP "map \fIkey\fR \fIcommand\fR" 2 +.IX Item "map key command" +Assign the key combination to the given command. Whenever you type the +key/keys, the command will be executed. Additionally, if you use a quantifier +when typing the key, like 5j, it will be passed to the command as the attribute +\&\*(L"self.quantifier\*(R". +.Sp +The keys you bind with this command are accessible in the file browser only, +not in the console, task view or pager. To bind keys there, use the commands +\&\*(L"cmap\*(R", \*(L"tmap\*(R" or \*(L"pmap\*(R". +.IP "mark \fIpattern\fR" 2 +.IX Item "mark pattern" +Mark all files matching the regular expression pattern. +.IP "mkdir \fIdirname\fR" 2 +.IX Item "mkdir dirname" +Creates a directory with the name \fIdirname\fR. +.IP "open_with [\fIapplication\fR] [\fIflags\fR] [\fImode\fR]" 2 +.IX Item "open_with [application] [flags] [mode]" +Open the selected files with the given application, unless it is omitted, in +which case the default application is used. \fIflags\fR are characters out of +\&\*(L"sdpcwSDPCW\*(R" and \fImode\fR is any positive integer. Their meanings are discussed +in their own sections. +.IP "pmap \fIkey\fR \fIcommand\fR" 2 +.IX Item "pmap key command" +Binds keys for the pager. Works like the \f(CW\*(C`map\*(C'\fR command. +.IP "punmap \fIkey\fR \fIcommand\fR" 2 +.IX Item "punmap key command" +Removes key mappings of the pager. Works like the \f(CW\*(C`unmap\*(C'\fR command. +.IP "quit" 2 +.IX Item "quit" +Like quit!, but closes only this tab if multiple tabs are open. +.IP "quit!" 2 +.IX Item "quit!" +Quit ranger. The current directory will be bookmarked as ' so you can re-enter +it by typing `` or '' the next time you start ranger. +.IP "rename \fInewname\fR" 2 +.IX Item "rename newname" +Rename the current file. If a file with that name already exists, the renaming +will fail. Also try the key binding A for appending something to a file name. +.IP "save_copy_buffer" 2 +.IX Item "save_copy_buffer" +Save the copy buffer from \fI~/.config/ranger/copy_buffer\fR. This can be used to +pass the list of copied files to another ranger instance. +.IP "search \fIpattern\fR" 2 +.IX Item "search pattern" +Search files in the current directory that match the given (case insensitive) +regular expression pattern. +.IP "search_inc \fIpattern\fR" 2 +.IX Item "search_inc pattern" +Search files in the current directory that match the given (case insensitive) +regular expression pattern. This command gets you to matching files as you +type. +.IP "set \fIoption\fR=\fIvalue\fR" 2 +.IX Item "set option=value" +Assigns a new value to an option. Valid options are listed in the settings +section. Use tab completion to get the current value of an option, though this +doesn't work for functions and regular expressions. Valid values are: +.Sp +.Vb 8 +\& None None +\& bool True or False +\& integer 0 or 1 or \-1 or 2 etc. +\& list [1, 2, 3] +\& tuple 1, 2, 3 or (1, 2, 3) +\& function lambda <arguments>: <expression> +\& regexp regexp(\*(Aq<pattern>\*(Aq) +\& string Anything +.Ve +.IP "shell [\-\fIflags\fR] \fIcommand\fR" 2 +.IX Item "shell [-flags] command" +Run a shell command. \fIflags\fR are discussed in their own section. +.IP "terminal" 2 +.IX Item "terminal" +Spawns the \fIx\-terminal-emulator\fR starting in the current directory. +.IP "touch \fIfilename\fR" 2 +.IX Item "touch filename" +Creates an empty file with the name \fIfilename\fR, unless it already exists. +.IP "tmap \fIkey\fR \fIcommand\fR" 2 +.IX Item "tmap key command" +Binds keys for the taskview. Works like the \f(CW\*(C`map\*(C'\fR command. +.IP "tunmap \fIkey\fR \fIcommand\fR" 2 +.IX Item "tunmap key command" +Removes key mappings of the taskview. Works like the \f(CW\*(C`unmap\*(C'\fR command. +.IP "unmap [\fIkeys\fR ...]" 2 +.IX Item "unmap [keys ...]" +Removes the given key mappings in the \*(L"browser\*(R" context. To unmap key bindings +in the console, taskview, or pager use \*(L"cunmap\*(R", \*(L"tunmap\*(R" or \*(L"punmap\*(R". +.IP "unmark \fIpattern\fR" 2 +.IX Item "unmark pattern" +Unmark all files matching a regular expression pattern. +.SH "FILES" +.IX Header "FILES" +ranger reads several configuration files which are located in +\&\fI\f(CI$HOME\fI/.config/ranger\fR or \fI\f(CI$XDG_CONFIG_HOME\fI/ranger\fR if \f(CW$XDG_CONFIG_HOME\fR is +defined. The configuration is done mostly in python. When removing a +configuration file, remove its compiled version too. (Python automatically +compiles modules. Since python3 they are saved in the _\|_pycache_\|_ directory, +earlier versions store them with the .pyc extension in the same directory.) +.PP +Use the \-\-copy\-config option to obtain the default configuration files. They +include further documentation and it's too much to put here. +.PP +You don't need to copy the whole file though, most configuration files are +overlaid on top of the defaults (\fIoptions.py\fR, \fIcommand.py\fR, \fIrc.conf\fR) or +can be sub-classed (\fIapps.py\fR, \fIcolorschemes\fR). +.PP +When starting ranger with the \fB\-\-clean\fR option, it will not access or create +any of these files. +.SS "\s-1CONFIGURATION\s0" +.IX Subsection "CONFIGURATION" +.IP "apps.py" 10 +.IX Item "apps.py" +Controls which applications are used to open files. +.IP "commands.py" 10 +.IX Item "commands.py" +Defines commands which can be used by typing \*(L":\*(R". +.IP "rc.conf" 10 +.IX Item "rc.conf" +Contains a list of commands which are executed on startup. Mostly key bindings +are defined here. +.IP "options.py" 10 +.IX Item "options.py" +Sets a handful of basic options. +.IP "scope.sh" 10 +.IX Item "scope.sh" +This is a script that handles file previews. When the options +\&\fIuse_preview_script\fR and \fIpreview_files\fR or, respectively, +\&\fIpreview_directories\fR are set, the program specified in the option +\&\fIpreview_script\fR is run and its output and/or exit code determines rangers +reaction. +.IP "colorschemes/" 10 +.IX Item "colorschemes/" +Colorschemes can be placed here. +.SS "\s-1STORAGE\s0" +.IX Subsection "STORAGE" +.IP "bookmarks" 10 +.IX Item "bookmarks" +This file contains a list of bookmarks. The syntax is /^(.):(.*)$/. The first +character is the bookmark key and the rest after the colon is the path to the +file. In ranger, bookmarks can be set by typing m<key>, accessed by typing +\&'<key> and deleted by typing um<key>. +.IP "copy_buffer" 10 +.IX Item "copy_buffer" +When running the command :save_copy_buffer, the paths of all currently copied +files are saved in this file. You can later run :load_copy_buffer to copy the +same files again, pass them to another ranger instance or process them in a +script. +.IP "history" 10 +.IX Item "history" +Contains a list of commands that have been previously typed in. +.IP "tagged" 10 +.IX Item "tagged" +Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first +letter is the optional name of the tag and the rest after the optional colon is +the path to the file. In ranger, tags can be set by pressing t and removed +with T. To assign a named tag, type "<tagname>. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +These environment variables have an effect on ranger: +.IP "\s-1EDITOR\s0" 8 +.IX Item "EDITOR" +Defines the editor to be used for the \*(L"E\*(R" key. Defaults to the first installed +program out of \*(L"vim\*(R", \*(L"emacs\*(R" and \*(L"nano\*(R". +.IP "\s-1SHELL\s0" 8 +.IX Item "SHELL" +Defines the shell that ranger is going to use with the :shell command and +the \*(L"S\*(R" key. Defaults to \*(L"bash\*(R". +.IP "\s-1XDG_CONFIG_HOME\s0" 8 +.IX Item "XDG_CONFIG_HOME" +Specifies the directory for configuration files. Defaults to \fI\f(CI$HOME\fI/.config\fR. +.IP "\s-1PYTHONOPTIMIZE\s0" 8 +.IX Item "PYTHONOPTIMIZE" +This variable determines the optimize level of python. +.Sp +Using PYTHONOPTIMIZE=1 (like python \-O) will make python discard assertion +statements. You will gain efficiency at the cost of losing some debug info. +.Sp +Using PYTHONOPTIMIZE=2 (like python \-OO) will additionally discard any +docstrings. Using this will disable the <F1> key on commands. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +.SS "\s-1VIM:\s0 File Chooser" +.IX Subsection "VIM: File Chooser" +This is a vim function which allows you to use ranger to select a file for +opening in your current vim session. +.PP +.Vb 9 +\& fun! RangerChooser() +\& silent !ranger \-\-choosefile=/tmp/chosenfile \`[ \-z \*(Aq%\*(Aq ] && echo \-n . || dirname %\` +\& if filereadable(\*(Aq/tmp/chosenfile\*(Aq) +\& exec \*(Aqedit \*(Aq . system(\*(Aqcat /tmp/chosenfile\*(Aq) +\& call system(\*(Aqrm /tmp/chosenfile\*(Aq) +\& endif +\& redraw! +\& endfun +\& map ,r :call RangerChooser()<CR> +.Ve +.SS "Bash: cd to last path after exit" +.IX Subsection "Bash: cd to last path after exit" +This is a bash function (for \fI~/.bashrc\fR) to change the directory to the last +visited one after ranger quits. You can always type \f(CW\*(C`cd \-\*(C'\fR to go back to the +original one. +.PP +.Vb 9 +\& function ranger\-cd { +\& tempfile=\*(Aq/tmp/chosendir\*(Aq +\& /usr/bin/ranger \-\-choosedir="$tempfile" "${@:\-$(pwd)}" +\& test \-f "$tempfile" && +\& if [ "$(cat \-\- "$tempfile")" != "$(echo \-n \`pwd\`)" ]; then +\& cd \-\- "$(cat "$tempfile")" +\& fi +\& rm \-f \-\- "$tempfile" +\& } +\& +\& # This binds Ctrl\-O to ranger\-cd: +\& bind \*(Aq"\eC\-o":"ranger\-cd\eC\-m"\*(Aq +.Ve +.SH "LICENSE" +.IX Header "LICENSE" +\&\s-1GNU\s0 General Public License 3 or (at your option) any later version. +.SH "LINKS" +.IX Header "LINKS" +.IP "Download: http://ranger.nongnu.org/ranger\-stable.tar.gz <http://ranger.nongnu.org/ranger-stable.tar.gz>" 4 +.IX Item "Download: http://ranger.nongnu.org/ranger-stable.tar.gz <http://ranger.nongnu.org/ranger-stable.tar.gz>" +.PD 0 +.IP "The project page: <http://ranger.nongnu.org/>" 4 +.IX Item "The project page: <http://ranger.nongnu.org/>" +.IP "The mailing list: <http://savannah.nongnu.org/mail/?group=ranger>" 4 +.IX Item "The mailing list: <http://savannah.nongnu.org/mail/?group=ranger>" +.PD +.PP +ranger is maintained with the git version control system. To fetch a fresh +copy, run: +.PP +.Vb 1 +\& git clone git://git.savannah.nongnu.org/ranger.git +.Ve +.SH "BUGS" +.IX Header "BUGS" +Report bugs here: <http://savannah.nongnu.org/bugs/?group=ranger> +.PP +Please include as much relevant information as possible. For the most +diagnostic output, run ranger like this: \f(CW\*(C`PYTHONOPTIMIZE= ranger \-\-debug\*(C'\fR diff --git a/doc/ranger.pod b/doc/ranger.pod new file mode 100644 index 00000000..ec272de1 --- /dev/null +++ b/doc/ranger.pod @@ -0,0 +1,1034 @@ +=head1 NAME + +ranger - visual file manager + + + + +=head1 SYNOPSIS + +B<ranger> [B<--help>] [B<--version>] [B<--debug>] [B<--clean>] +[B<--list-unused-keys>] [B<--fail-unless-cd>] [B<--choosedir>=I<targetfile>] +[B<--choosefile>=I<targetfile>] [B<--copy-config>=I<file>] [B<--mode>=I<mode>] +[B<--flags>=I<flags>] [I<path/filename>] + + + + +=head1 DESCRIPTION + +ranger is a console file manager with VI key bindings. It provides a +minimalistic and nice curses interface with a view on the directory hierarchy. +The secondary task of ranger is to figure out which program you want to use to +open your files with. + +This manual mainly contains information on the usage of ranger. Refer to the +F<README> for install instructions and to F<doc/HACKING> for development +specific information. For configuration, see the files in F<ranger/defaults>. +They are usually installed to F</usr/lib/python*/site-packages/ranger/defaults> +and can be obtained with ranger's --copy-config option. + +Inside ranger, you can press I<1?> for a list of key bindings, I<2?> for a list +of commands and I<3?> for a list of settings. + + + + +=head1 OPTIONS + +=over 14 + +=item B<-d>, B<--debug> + +Activate the debug mode: Whenever an error occurs, ranger will exit and print a +full traceback. The default behavior is to merely print the name of the +exception in the statusbar/log and try to keep running. + +=item B<-c>, B<--clean> + +Activate the clean mode: ranger will not access or create any configuration +files nor will it leave any traces on your system. This is useful when your +configuration is broken, when you want to avoid clutter, etc. + +=item B<--choosefile>=I<targetfile> + +Allows you to pick a file with ranger. This changes the behavior so that when +you open a file, ranger will exit and write the name of that file into +I<targetfile>. + +=item B<--choosedir>=I<targetfile> + +Allows you to pick a directory with ranger. When you exit ranger, it will +write the last visited directory into I<targetfile>. + +=item B<--copy-config>=I<file> + +Create copies of the default configuration files in your local configuration +directory. Existing ones will not be overwritten. Possible values: I<all>, +I<rc>, I<apps>, I<commands>, I<options>, I<scope>. + +=item B<--list-unused-keys> + +List common keys which are not bound to any action in the "browser" context. +This list is not complete, you can bind any key that is supported by curses: +use the key code returned by C<getch()>. + +=item B<--fail-unless-cd> + +Return the exit code 1 if ranger is used to run a file instead of used for file +browsing. (For example, "ranger --fail-unless-cd test.txt" returns 1.) + +=item B<-m> I<n>, B<--mode>=I<n> + +When a filename is supplied, run it in mode I<n>. This has no effect unless +the execution of this file type is explicitly handled in the configuration. + +=item B<-f> I<flags>, B<--flags>=I<flags> + +When a filename is supplied, run it with the given I<flags> to modify +behavior. The execution of this file type is explicitly handled in the +configuration. + +=item B<--version> + +Print the version and exit. + +=item B<-h>, B<--help> + +Print a list of options and exit. + +=back + + + + +=head1 CONCEPTS + +=head2 TAGS + +Tags are single characters which are displayed left of a filename. You can use +tags however you want. Press "t" to toggle tags and "T" to remove any tags of +the selection. The default tag is an Asterisk ("*"), but you can use any tag by +typing I<"<tagnameE<gt>>. + +=head2 PREVIEWS + +By default, only text files are previewed, but you can enable external preview +scripts by setting the option C<use_preview_script> and C<preview_files> to True. + +This default script is F<~/.config/ranger/scope.sh>. It contains more +documentation and calls to the programs I<lynx> and I<elinks> for html, +I<highlight> for text/code, I<img2txt> for images, I<atool> for archives, +I<pdftotext> for PDFs and I<mediainfo> for video and audio files. + +Install these programs (just the ones you need) and scope.sh will automatically +use them. + +=head2 SELECTION + +The I<selection> is defined as "All marked files IF THERE ARE ANY, otherwise +the current file." Be aware of this when using the :delete command, which +deletes all files in the selection. + +You can mark files by pressing <Space>, v, etc. A yellow B<Mrk> symbol at the +bottom right indicates that there are marked files in this directory. + +=head2 MACROS + +Macros can be used in commands to abbreviate things. + + %f the highlighted file + %d the path of the current directory + %s the selected files in the current directory. + %t all tagged files in the current directory + %c the full paths of the currently copied/cut files + +The macros %f, %d and %s also have upper case variants, %F, %D and %S, +which refer to the next tab. To refer to specific tabs, add a number in +between. (%7s = selection of the seventh tab.) + +%c is the only macro which ranges out of the current directory. So you may +"abuse" the copying function for other purposes, like diffing two files which +are in different directories: + + Yank the file A (type yy), move to the file B, then type + @diff %c %f + +Macros for file paths are generally shell-escaped so they can be used in the +:shell command. + +=head2 BOOKMARKS + +Type B<m<keyE<gt>> to bookmark the current directory. You can re-enter this +directory by typing B<`<keyE<gt>>. <key> can be any letter or digit. Unlike vim, +both lowercase and uppercase bookmarks are persistent. + +Each time you jump to a bookmark, the special bookmark at key ` will be set +to the last directory. So typing "``" gets you back to where you were before. + +Bookmarks are selectable when tabbing in the :cd command. + +Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. + +=head2 FLAGS + +Flags give you a way to modify the behavior of the spawned process. They are +used in the commands :open_with (key "r") and :shell (key "!"). + + s Silent mode. Output will be discarded. + d Detach the process. (Run in background) + p Redirect output to the pager + w Wait for an Enter-press when the process is done + c Run the current file only, instead of the selection + +By default, all the flags are off unless specified otherwise in the F<apps.py> +configuration file. You can specify as many flags as you want. An uppercase +flag negates the effect: "ddcccDs" is equivalent to "cs". + +Examples: C<:open_with p> will pipe the output of that process into +the pager. C<:shell -w df> will run "df" and wait for you to press Enter before +switching back to ranger. + +=head2 MODES + +By specifying a mode (a positive integer), you can tell ranger what to do with +a file when running it. You can specify which mode to use by typing <mode>l or +<mode><Enter> or :open_with <mode>. The default mode is 0. + +Examples: C<l> (mode zero) to list the contents of an archive, C<1l> (mode one) +to extract an archive. See the F<apps.py> configuration file for all programs +and modes. + + + + +=head1 KEY BINDINGS + +Key bindings are defined in the file F<ranger/defaults/rc.conf>. Check this +file for a list of all key bindings. You can copy it to your local +configuration directory with the --copy-config=rc option. + +Many key bindings take an additional numeric argument. Type I<5j> to move +down 5 lines, I<2l> to open a file in mode 2, I<10<SpaceE<gt>> to mark 10 files. + +This list contains the most useful bindings: + +=head2 MAIN BINDINGS + +=over 14 + +=item h, j, k, l + +Move left, down, up or right + +=item ^D or J, ^U or K + +Move a half page down, up + +=item H, L + +Move back and forward in the history + +=item gg + +Move to the top + +=item G + +Move to the bottom + +=item ^R + +Reload everything + +=item ^L + +Redraw the screen + +=item S + +Open a shell in the current directory + +=item ? + +Opens this man page + +=item yy + +Yank the selection to the "copy" buffer and mark them as to be copied + +=item dd + +Cut the selection to the "copy" buffer and mark them as to be moved + +=item pp + +Paste the files from the "copy" buffer here (by moving or copying, depending on +how they are marked.) By default, this will not overwrite existing files. To +overwrite them, use I<po>. + +=item mI<X> + +Create a bookmark with the name I<X> + +=item `I<X> + +Move to the bookmark with the name I<X> + +=item n, N + +Find the next file. By default, this gets you to the newest file in the +directory, but if you search something using the keys /, cm, ct, ..., it will +get you to the next found entry. + +=item N + +Find the previous file. + +=item oI<X> + +Change the sort method (like in mutt) + +=item zI<X> + +Change settings. See the settings section for a list of settings and their +hotkey. + +=item f + +Quickly navigate by entering a part of the filename. + +=item Space + +Mark a file. + +=item v + +Toggle the mark-status of all files, unmark all files. + +=item V, uv + +Unmark all files + +=item / + +Search for files in the current directory. + +=item : + +Open the console. + + +=item Alt-I<N> + +Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it +will be created. + +=item gn, ^N + +Create a new tab. + +=item gt, gT + +Go to the next or previous tab. You can also use TAB and SHIFT+TAB instead. + +=item gc, ^W + +Close the current tab. The last tab cannot be closed this way. + +=back + +=head2 MIDNIGHT COMMANDER-LIKE BINDINGS + +=over 14 + +=item <F1> + +Display Help. + +=item <F3> + +Display the file. + +=item <F4> + +Edit the file. + +=item <F5> + +Copy the file. + +=item <F6> + +Cut the file. + +=item <F7> + +Open the console with ":mkdir ". + +=item <F8> + +Prompt for deletion of the selected files. + +=item <F10> + +Exit ranger. + +=back + +=head2 READLINE-LIKE BINDINGS IN THE CONSOLE + +=over 14 + +=item ^B, ^F + +Move left and right (B for back, F for forward) + +=item ^P, ^N + +Move up and down (P for previous, N for Next) + +=item ^A, ^E + +Move to the start or to the end + +=item ^D + +Delete the current character. + +=item ^H + +Backspace. + +=back + + +=head1 MOUSE BUTTONS + +=over + +=item Left Mouse Button + +Click on something and you'll move there. To run a file, "enter" it, like a +directory, by clicking on the preview. + +=item Right Mouse Button + +Enter a directory or run a file. + +=item Scroll Wheel + +Scrolls up or down. You can point at the column of the parent directory to +switch directories. + +=back + + + + +=head1 SETTINGS + +This section lists all built-in settings of ranger. The valid types for the +value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if +a hotkey exists. + +Settings can be changed in the file F<~/.config/ranger/options.py> or on the +fly with the command B<:set option value>. Examples: + :set column_ratios (1,2,3) + :set show_hidden=True + +=over + +=item autosave_bookmarks [bool] + +Save bookmarks (used with mX and `X) instantly? This helps to synchronize +bookmarks between multiple ranger instances but leads to *slight* performance +loss. When false, bookmarks are saved when ranger is exited. + +=item collapse_preview [bool] <zc> + +When no preview is visible, should the last column be squeezed to make use of +the whitespace? + +=item colorscheme_overlay [function, None] + +An overlay function for colorschemes. See the default options.py for an +explanation and an example. + +=item colorscheme [string] + +Which colorscheme to use? These colorschemes are available by default: +B<default>, B<default88>, B<texas>, B<jungle>, B<snow>. Snow is monochrome, +texas and default88 use 88 colors. + +=item column_ratios [tuple, list] + +How many columns are there, and what are their relative widths? For example, a +value of (1, 1, 1) would mean 3 even sized columns. (1, 1, 1, 1, 4) means 5 columns +with the preview column being as large as the other columns combined. + +=item dirname_in_tabs [bool] + +Display the directory name in tabs? + +=item display_size_in_main_column [bool] + +Display the file size in the main column? + +=item display_size_in_status_bar [bool] + +Display the file size in the status bar? + +=item display_tags_in_all_columns [bool] + +Display tags in all columns? + +=item draw_bookmark_borders [bool] + +Draw borders around the bookmark window? + +=item draw_borders [bool] + +Draw borders around columns? + +=item flushinput [bool] <zi> + +Flush the input after each key hit? One advantage is that when scrolling down +with "j", ranger stops scrolling instantly when you release the key. One +disadvantage is that when you type commands blindly, some keys might get lost. + +=item hidden_filter [regexp] + +A regular expression pattern for files which should be hidden. + +=item max_console_history_size [integer, None] + +How many console commands should be kept in history? + +=item max_history_size [integer, None] + +How many directory changes should be kept in history? + +=item mouse_enabled [bool] <zm> + +Enable mouse input? + +=item padding_right [bool] + +When collapse_preview is on and there is no preview, should there remain a +little padding on the right? This allows you to click into that space to run +the file. + +=item preview_directories [bool] <zP> + +Preview directories in the preview column? + +=item preview_files [bool] <zp> + +Preview files in the preview column? + +=item preview_script [string, None] + +Which script should handle generating previews? If the file doesn't exist, or +use_preview_script is off, ranger will handle previews itself by just printing +the content. + +=item save_console_history [bool] + +Should the console history be saved on exit? If disabled, the console history +is reset when you restart ranger. + +=item scroll_offset [integer] + +Try to keep this much space between the top/bottom border when scrolling. + +=item shorten_title [integer, bool] + +Trim the title of the window if it gets long? The number defines how many +directories are displayed at once, False turns off this feature. + +=item show_cursor [bool] + +Always show the terminal cursor? + +=item show_hidden_bookmarks [bool] + +Show dotfiles in the bookmark preview window? (Type ') + +=item show_hidden [bool] <zh>, <^H> + +Show hidden files? + +=item sort_case_insensitive [bool] <zc> + +Sort case-insensitively? If true, "a" will be listed before "B" even though +its ASCII value is higher. + +=item sort_directories_first [bool] <zd> + +Sort directories first? + +=item sort_reverse [bool] <or> + +Sort reversed? + +=item sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os> + +Which sorting mechanism should be used? Choose one of B<atime>, B<basename>, +B<ctime>, B<mtime>, B<natural>, B<type>, B<size> + +Note: You can reverse the order by using an uppercase O in the key combination. + +=item tilde_in_titlebar [bool] + +Abbreviate $HOME with ~ in the title bar (first line) of ranger? + +=item unicode_ellipsis [bool] + +Use a unicode "..." character instead of "~" to mark cut-off filenames? + +=item update_title [bool] + +Set a window title? + +=item use_preview_script [bool] <zv> + +Use the preview script defined in the setting I<preview_script>? + +=item xterm_alt_key [bool] + +Enable this if key combinations with the Alt Key don't work for you. +(Especially on xterm) + +=back + + +=head1 COMMANDS + +You can enter the commands in the console which is opened by pressing ":". + +There are additional commands which are directly translated to python +functions, one for every method in the ranger.core.actions.Actions class. +They are not documented here, since they are mostly for key bindings, not to be +typed in by a user. Read the source if you are interested in them. + +=over 2 + +=item bulkrename + +This command opens a list of selected files in an external editor. After you +edit and save the file, it will generate a shell script which does bulk +renaming according to the changes you did in the file. + +This shell script is opened in an editor for you to review. After you close +it, it will be executed. + +=item cd [I<directory>] + +The cd command changes the directory. The command C<:cd -> is equivalent to +typing ``. + +=item chain I<command1>[; I<command2>[; I<command3>...]] + +Combines multiple commands into one, separated by columns. + +=item chmod I<octal_number> + +Sets the permissions of the selection to the octal number. + +The octal number is between 000 and 777. The digits specify the permissions for +the user, the group and others. A 1 permits execution, a 2 permits writing, a +4 permits reading. Add those numbers to combine them. So a 7 permits +everything. + +Key bindings in the form of [-+]<who><what> and =<octal> also exist. For +example, B<+ar> allows reading for everyone, -ow forbids others to write and +=777 allows everything. + +See also: man 1 chmod + +=item cmap I<key> I<command> + +Binds keys for the console. Works like the C<map> command. + +=item console [-pI<N>] I<command> + +Opens the console with the command already typed in. The cursor is placed at +I<N>. + +=item copycmap I<key> I<newkey> [I<newkey2> ...] + +See C<copymap> + +=item copymap I<key> I<newkey> [I<newkey2> ...] + +Copies the keybinding I<key> to I<newkey> in the "browser" context. This is a +deep copy, so if you change the new binding (or parts of it) later, the old one +is not modified. + +To copy key bindings of the console, taskview, or pager use "copycmap", +"copytmap" or "copypmap". + +=item copypmap I<key> I<newkey> [I<newkey2> ...] + +See C<copymap> + +=item copytmap I<key> I<newkey> [I<newkey2> ...] + +See C<copymap> + +=item cunmap I<key> I<command> + +Removes key mappings of the console. Works like the C<unmap> command. + +=item delete [I<confirmation>] + +Destroy all files in the selection with a roundhouse kick. ranger will ask for +a confirmation if you attempt to delete multiple (marked) files or non-empty +directories. + +When asking for confirmation, this command will only proceed if the last given +word starts with a `y'. + +=item edit [I<filename>] + +Edit the current file or the file in the argument. + +=item eval [I<-q>] I<python_code> + +Evaluates the python code. `fm' is a reference to the FM instance. To display +text, use the function `p'. The result is displayed on the screen unless you +use the "-q" option. + +Examples: + :eval fm + :eval len(fm.env.directories) + :eval p("Hello World!") + +=item filter [I<string>] + +Displays only the files which contain the I<string> in their basename. + +=item find I<pattern> + +Search files in the current directory that match the given (case-insensitive) +regular expression pattern as you type. Once there is an unambiguous result, +it will be run immediately. (Or entered, if it's a directory.) + +=item grep I<pattern> + +Looks for a string in all marked files or directories. + +=item load_copy_buffer + +Load the copy buffer from F<~/.config/ranger/copy_buffer>. This can be used to +pass the list of copied files to another ranger instance. + +=item map I<key> I<command> + +Assign the key combination to the given command. Whenever you type the +key/keys, the command will be executed. Additionally, if you use a quantifier +when typing the key, like 5j, it will be passed to the command as the attribute +"self.quantifier". + +The keys you bind with this command are accessible in the file browser only, +not in the console, task view or pager. To bind keys there, use the commands +"cmap", "tmap" or "pmap". + +=item mark I<pattern> + +Mark all files matching the regular expression pattern. + +=item mkdir I<dirname> + +Creates a directory with the name I<dirname>. + +=item open_with [I<application>] [I<flags>] [I<mode>] + +Open the selected files with the given application, unless it is omitted, in +which case the default application is used. I<flags> are characters out of +"sdpcwSDPCW" and I<mode> is any positive integer. Their meanings are discussed +in their own sections. + +=item pmap I<key> I<command> + +Binds keys for the pager. Works like the C<map> command. + +=item punmap I<key> I<command> + +Removes key mappings of the pager. Works like the C<unmap> command. + +=item quit + +Like quit!, but closes only this tab if multiple tabs are open. + +=item quit! + +Quit ranger. The current directory will be bookmarked as ' so you can re-enter +it by typing `` or '' the next time you start ranger. + +=item rename I<newname> + +Rename the current file. If a file with that name already exists, the renaming +will fail. Also try the key binding A for appending something to a file name. + +=item save_copy_buffer + +Save the copy buffer from I<~/.config/ranger/copy_buffer>. This can be used to +pass the list of copied files to another ranger instance. + +=item search I<pattern> + +Search files in the current directory that match the given (case insensitive) +regular expression pattern. + +=item search_inc I<pattern> + +Search files in the current directory that match the given (case insensitive) +regular expression pattern. This command gets you to matching files as you +type. + +=item set I<option>=I<value> + +Assigns a new value to an option. Valid options are listed in the settings +section. Use tab completion to get the current value of an option, though this +doesn't work for functions and regular expressions. Valid values are: + + None None + bool True or False + integer 0 or 1 or -1 or 2 etc. + list [1, 2, 3] + tuple 1, 2, 3 or (1, 2, 3) + function lambda <arguments>: <expression> + regexp regexp('<pattern>') + string Anything + +=item shell [-I<flags>] I<command> + +Run a shell command. I<flags> are discussed in their own section. + +=item terminal + +Spawns the I<x-terminal-emulator> starting in the current directory. + +=item touch I<filename> + +Creates an empty file with the name I<filename>, unless it already exists. + +=item tmap I<key> I<command> + +Binds keys for the taskview. Works like the C<map> command. + +=item tunmap I<key> I<command> + +Removes key mappings of the taskview. Works like the C<unmap> command. + +=item unmap [I<keys> ...] + +Removes the given key mappings in the "browser" context. To unmap key bindings +in the console, taskview, or pager use "cunmap", "tunmap" or "punmap". + +=item unmark I<pattern> + +Unmark all files matching a regular expression pattern. + +=back + + + + +=head1 FILES + +ranger reads several configuration files which are located in +F<$HOME/.config/ranger> or F<$XDG_CONFIG_HOME/ranger> if $XDG_CONFIG_HOME is +defined. The configuration is done mostly in python. When removing a +configuration file, remove its compiled version too. (Python automatically +compiles modules. Since python3 they are saved in the __pycache__ directory, +earlier versions store them with the .pyc extension in the same directory.) + +Use the --copy-config option to obtain the default configuration files. They +include further documentation and it's too much to put here. + +You don't need to copy the whole file though, most configuration files are +overlaid on top of the defaults (F<options.py>, F<command.py>, F<rc.conf>) or +can be sub-classed (F<apps.py>, F<colorschemes>). + +When starting ranger with the B<--clean> option, it will not access or create +any of these files. + +=head2 CONFIGURATION + +=over 10 + +=item apps.py + +Controls which applications are used to open files. + +=item commands.py + +Defines commands which can be used by typing ":". + +=item rc.conf + +Contains a list of commands which are executed on startup. Mostly key bindings +are defined here. + +=item options.py + +Sets a handful of basic options. + +=item scope.sh + +This is a script that handles file previews. When the options +I<use_preview_script> and I<preview_files> or, respectively, +I<preview_directories> are set, the program specified in the option +I<preview_script> is run and its output and/or exit code determines rangers +reaction. + +=item colorschemes/ + +Colorschemes can be placed here. + +=back + +=head2 STORAGE + +=over 10 + +=item bookmarks + +This file contains a list of bookmarks. The syntax is /^(.):(.*)$/. The first +character is the bookmark key and the rest after the colon is the path to the +file. In ranger, bookmarks can be set by typing m<key>, accessed by typing +'<key> and deleted by typing um<key>. + +=item copy_buffer + +When running the command :save_copy_buffer, the paths of all currently copied +files are saved in this file. You can later run :load_copy_buffer to copy the +same files again, pass them to another ranger instance or process them in a +script. + +=item history + +Contains a list of commands that have been previously typed in. + +=item tagged + +Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first +letter is the optional name of the tag and the rest after the optional colon is +the path to the file. In ranger, tags can be set by pressing t and removed +with T. To assign a named tag, type "<tagname>. + +=back + + + + +=head1 ENVIRONMENT + +These environment variables have an effect on ranger: + +=over 8 + +=item EDITOR + +Defines the editor to be used for the "E" key. Defaults to the first installed +program out of "vim", "emacs" and "nano". + +=item SHELL + +Defines the shell that ranger is going to use with the :shell command and +the "S" key. Defaults to "bash". + +=item XDG_CONFIG_HOME + +Specifies the directory for configuration files. Defaults to F<$HOME/.config>. + +=item PYTHONOPTIMIZE + +This variable determines the optimize level of python. + +Using PYTHONOPTIMIZE=1 (like python -O) will make python discard assertion +statements. You will gain efficiency at the cost of losing some debug info. + +Using PYTHONOPTIMIZE=2 (like python -OO) will additionally discard any +docstrings. Using this will disable the <F1> key on commands. + +=back + + + + +=head1 EXAMPLES + +=head2 VIM: File Chooser + +This is a vim function which allows you to use ranger to select a file for +opening in your current vim session. + + fun! RangerChooser() + silent !ranger --choosefile=/tmp/chosenfile `[ -z '%' ] && echo -n . || dirname %` + if filereadable('/tmp/chosenfile') + exec 'edit ' . system('cat /tmp/chosenfile') + call system('rm /tmp/chosenfile') + endif + redraw! + endfun + map ,r :call RangerChooser()<CR> + +=head2 Bash: cd to last path after exit + +This is a bash function (for F<~/.bashrc>) to change the directory to the last +visited one after ranger quits. You can always type C<cd -> to go back to the +original one. + + function ranger-cd { + tempfile='/tmp/chosendir' + /usr/bin/ranger --choosedir="$tempfile" "${@:-$(pwd)}" + test -f "$tempfile" && + if [ "$(cat -- "$tempfile")" != "$(echo -n `pwd`)" ]; then + cd -- "$(cat "$tempfile")" + fi + rm -f -- "$tempfile" + } + + # This binds Ctrl-O to ranger-cd: + bind '"\C-o":"ranger-cd\C-m"' + + + + +=head1 LICENSE + +GNU General Public License 3 or (at your option) any later version. + + + + +=head1 LINKS + +=over + +=item Download: L<http://ranger.nongnu.org/ranger-stable.tar.gz> + +=item The project page: L<http://ranger.nongnu.org/> + +=item The mailing list: L<http://savannah.nongnu.org/mail/?group=ranger> + +=back + +ranger is maintained with the git version control system. To fetch a fresh +copy, run: + + git clone git://git.savannah.nongnu.org/ranger.git + + + + +=head1 BUGS + +Report bugs here: L<http://savannah.nongnu.org/bugs/?group=ranger> + +Please include as much relevant information as possible. For the most +diagnostic output, run ranger like this: C<PYTHONOPTIMIZE= ranger --debug> |