1 # Wrappers around print primitives that take a 'screen' object and are thus
  2 # easier to test.
  3 #
  4 # Screen objects are intended to exactly mimic the behavior of traditional
  5 # terminals. Moving a cursor too far right wraps it to the next line,
  6 # scrolling if necessary. The details are subtle:
  7 #
  8 # a) Rows can take unbounded values. When printing, large values for the row
  9 # saturate to the bottom row (because scrolling).
 10 #
 11 # b) If you print to a square (row, right) on the right margin, the cursor
 12 # position depends on whether 'row' is in range. If it is, the new cursor
 13 # position is (row+1, 0). If it isn't, the new cursor position is (row, 0).
 14 # Because scrolling.
 15 
 16 container screen [
 17   num-rows:num
 18   num-columns:num
 19   cursor-row:num
 20   cursor-column:num
 21   data:&:@:screen-cell  # capacity num-rows*num-columns
 22   pending-scroll?:bool
 23   top-idx:num  # index inside data that corresponds to top-left of screen
 24                # modified on scroll, wrapping around to the top of data
 25 ]
 26 
 27 container screen-cell [
 28   contents:char
 29   color:num
 30 ]
 31 
 32 def new-fake-screen w:num, h:num -> result:&:screen [
 33   local-scope
 34   load-inputs
 35   result <- new screen:type
 36   non-zero-width?:bool <- greater-than w, 0
 37   assert non-zero-width?, [screen can't have zero width]
 38   non-zero-height?:bool <- greater-than h, 0
 39   assert non-zero-height?, [screen can't have zero height]
 40   bufsize:num <- multiply w, h
 41   data:&:@:screen-cell <- new screen-cell:type, bufsize
 42   *result <- merge h/num-rows, w/num-columns, 0/cursor-row, 0/cursor-column, data, false/pending-scroll?, 0/top-idx
 43   result <- clear-screen result
 44 ]
 45 
 46 def clear-screen screen:&:screen -> screen:&:screen [
 47   local-scope
 48   load-inputs
 49 #?   stash [clear-screen]
 50   {
 51     break-if screen
 52     # real screen
 53     clear-display
 54     return
 55   }
 56   # fake screen
 57   buf:&:@:screen-cell <- get *screen, data:offset
 58   max:num <- length *buf
 59   i:num <- copy 0
 60   {
 61     done?:bool <- greater-or-equal i, max
 62     break-if done?
 63     curr:screen-cell <- merge 0/empty, 7/white
 64     *buf <- put-index *buf, i, curr
 65     i <- add i, 1
 66     loop
 67   }
 68   # reset cursor
 69   *screen <- put *screen, cursor-row:offset, 0
 70   *screen <- put *screen, cursor-column:offset, 0
 71   *screen <- put *screen, top-idx:offset, 0
 72 ]
 73 
 74 def fake-screen-is-empty? screen:&:screen -> result:bool [
 75   local-scope
 76   load-inputs
 77 #?   stash [fake-screen-is-empty?]
 78   return-unless screen, true  # do nothing for real screens
 79   buf:&:@:screen-cell <- get *screen, data:offset
 80   i:num <- copy 0
 81   len:num <- length *buf
 82   {
 83     done?:bool <- greater-or-equal i, len
 84     break-if done?
 85     curr:screen-cell <- index *buf, i
 86     curr-contents:char <- get curr, contents:offset
 87     i <- add i, 1
 88     loop-unless curr-contents
 89     # not 0
 90     return false
 91   }
 92   return true
 93 ]
 94 
 95 def print screen:&:screen, c:char -> screen:&:screen [
 96   local-scope
 97   load-inputs
 98   color:num, color-found?:bool <- next-input
 99   {
100     # default color to white
101     break-if color-found?
102     color <- copy 7/white
103   }
104   bg-color:num, bg-color-found?:bool <- next-input
105   {
106     # default bg-color to black
107     break-if bg-color-found?
108     bg-color <- copy 0/black
109   }
110   c2:num <- character-to-code c
111   trace 90, [print-character], c2
112   {
113     # real screen
114     break-if screen
115     print-character-to-display c, color, bg-color
116     return
117   }
118   # fake screen
119   # (handle special cases exactly like in the real screen)
120   width:num <- get *screen, num-columns:offset
121   height:num <- get *screen, num-rows:offset
122   capacity:num <- multiply width, height
123   row:num <- get *screen, cursor-row:offset
124   column:num <- get *screen, cursor-column:offset
125   buf:&:@:screen-cell <- get *screen, data:offset
126   # some potentially slow sanity checks for preconditions {
127   # eliminate fractions from column and row
128   row <- round row
129   column <- round column
130   # if cursor is past left margin (error), reset to left margin
131   {
132     too-far-left?:bool <- lesser-than column, 0
133     break-unless too-far-left?
134     column <- copy 0
135     *screen <- put *screen, cursor-column:offset, column
136   }
137   # if cursor is at or past right margin, wrap
138   {
139     at-right?:bool <- greater-or-equal column, width
140     break-unless at-right?
141     column <- copy 0
142     *screen <- put *screen, cursor-column:offset, column
143     row <- add row, 1
144     *screen <- put *screen, cursor-row:offset, row
145   }
146   # }
147   # if there's a pending scroll, perform it
148   {
149     pending-scroll?:bool <- get *screen, pending-scroll?:offset
150     break-unless pending-scroll?
151 #?     stash [scroll]
152     scroll-fake-screen screen
153     *screen <- put *screen, pending-scroll?:offset, false
154   }
155 #?     $print [print-character (], row, [, ], column, [): ], c, 10/newline
156   # special-case: newline
157   {
158     newline?:bool <- equal c, 10/newline
159     break-unless newline?
160     cursor-down-on-fake-screen screen  # doesn't modify column
161     return
162   }
163   # special-case: linefeed
164   {
165     linefeed?:bool <- equal c, 13/linefeed
166     break-unless linefeed?
167     *screen <- put *screen, cursor-column:offset, 0
168     return
169   }
170   # special-case: backspace
171   # moves cursor left but does not erase
172   {
173     backspace?:bool <- equal c, 8/backspace
174     break-unless backspace?
175     {
176       break-unless column
177       column <- subtract column, 1
178       *screen <- put *screen, cursor-column:offset, column
179     }
180     return
181   }
182   # save character in fake screen
183   top-idx:num <- get *screen, top-idx:offset
184   index:num <- data-index row, column, width, height, top-idx
185   cursor:screen-cell <- merge c, color
186   *buf <- put-index *buf, index, cursor
187   # move cursor to next character, wrapping as necessary
188   # however, don't scroll just yet
189   column <- add column, 1
190   {
191     past-right?:bool <- greater-or-equal column, width
192     break-unless past-right?
193     column <- copy 0
194     row <- add row, 1
195     past-bottom?:bool <- greater-or-equal row, height
196     break-unless past-bottom?
197     # queue up a scroll
198 #?     stash [pending scroll]
199     *screen <- put *screen, pending-scroll?:offset, true
200     row <- subtract row, 1  # update cursor as if scroll already happened
201   }
202   *screen <- put *screen, cursor-row:offset, row
203   *screen <- put *screen, cursor-column:offset, column
204 ]
205 
206 def cursor-down-on-fake-screen screen:&:screen -> screen:&:screen [
207   local-scope
208   load-inputs
209 #?   stash [cursor-down]
210   row:num <- get *screen, cursor-row:offset
211   height:num <- get *screen, num-rows:offset
212   bottom:num <- subtract height, 1
213   at-bottom?:bool <- greater-or-equal row, bottom
214   {
215     break-if at-bottom?
216     row <- add row, 1
217     *screen <- put *screen, cursor-row:offset, row
218   }
219   {
220     break-unless at-bottom?
221     scroll-fake-screen screen  # does not modify row
222   }
223 ]
224 
225 def scroll-fake-screen screen:&:screen -> screen:&:screen [
226   local-scope
227   load-inputs
228 #?   stash [scroll-fake-screen]
229   width:num <- get *screen, num-columns:offset
230   height:num <- get *screen, num-rows:offset
231   buf:&:@:screen-cell <- get *screen, data:offset
232   # clear top line and 'rotate' it to the bottom
233   top-idx:num <- get *screen, top-idx:offset  # 0 <= top-idx < len(buf)
234   next-top-idx:num <- add top-idx, width  # 0 <= next-top-idx <= len(buf)
235   empty-cell:screen-cell <- merge 0/empty, 7/white
236   {
237     done?:bool <- greater-or-equal top-idx, next-top-idx
238     break-if done?
239     put-index *buf, top-idx, empty-cell
240     top-idx <- add top-idx, 1
241     # no modulo; top-idx is always a multiple of width,
242     # so it can never wrap around inside this loop
243     loop
244   }
245   # top-idx now same as next-top-idx; wrap around if necessary
246   capacity:num <- multiply width, height
247   _, top-idx <- divide-with-remainder, top-idx, capacity
248   *screen <- put *screen, top-idx:offset, top-idx
249 ]
250 
251 # translate from screen (row, column) coordinates to an index into data
252 # while accounting for scrolling (sliding top-idx)
253 def data-index row:num, column:num, width:num, height:num, top-idx:num -> result:num [
254   local-scope
255   load-inputs
256   {
257     overflow?:bool <- greater-or-equal row, height
258     break-unless overflow?
259     row <- subtract height, 1
260   }
261   result <- multiply width, row
262   result <- add result, column, top-idx
263   capacity:num <- multiply width, height
264   _, result <- divide-with-remainder result, capacity
265 ]
266 
267 scenario print-character-at-top-left [
268   local-scope
269   fake-screen:&:screen <- new-fake-screen 3/width, 2/height
270   run [
271     a:char <- copy 97/a
272     fake-screen <- print fake-screen, a:char
273     cell:&:@:screen-cell <- get *fake-screen, data:offset
274     1:@:screen-cell/raw <- copy *cell
275   ]
276   memory-should-contain [
277     1 <- 6  # width*height
278     2 <- 97  # 'a'
279     3 <- 7  # white
280     # rest of screen is empty
281     4 <- 0
282   ]
283 ]
284 
285 scenario print-character-at-fractional-coordinate [
286   local-scope
287   fake-screen:&:screen <- new-fake-screen 3/width, 2/height
288   a:char <- copy 97/a
289   run [
290     move-cursor fake-screen, 0.5, 0
291     fake-screen <- print fake-screen, a:char
292     cell:&:@:screen-cell <- get *fake-screen, data:offset
293     1:@:screen-cell/raw <- copy *cell
294   ]
295   memory-should-contain [
296     1 <- 6  # width*height
297     2 <- 97  # 'a'
298     3 <- 7  # white
299     # rest of screen is empty
300     4 <- 0
301   ]
302 ]
303 
304 scenario print-character-in-color [
305   local-scope
306   fake-screen:&:screen <- new-fake-screen 3/width, 2/height
307   run [
308     a:char <- copy 97/a
309     fake-screen <- print fake-screen, a:char, 1/red
310     cell:&:@:screen-cell <- get *fake-screen, data:offset
311     1:@:screen-cell/raw <- copy *cell
312   ]
313   memory-should-contain [
314     1 <- 6  # width*height
315     2 <- 97  # 'a'
316     3 <- 1  # red
317     # rest of screen is empty
318     4 <- 0
319   ]
320 ]
321 
322 scenario print-backspace-character [
323   local-scope
324   fake-screen:&:screen <- new-fake-screen 3/width, 2/height
325   a:char <- copy 97/a
326   fake-screen <- print fake-screen, a
327   run [
328     backspace:char <- copy 8/backspace
329     fake-screen <- print fake-screen, backspace
330     10:num/raw <- get *fake-screen, cursor-column:offset
331     cell:&:@:screen-cell <- get *fake-screen, data:offset
332     11:@:screen-cell/raw <- copy *cell
333   ]
<
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" 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.6.0" "03/24/2013" "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\-\-version\fR] [\fB\-\-help\fR] [\fB\-\-debug\fR] [\fB\-\-clean\fR] 
[\fB\-\-confdir\fR=\fIdirectory\fR] [\fB\-\-copy\-config\fR=\fIwhich\fR]
[\fB\-\-choosefile\fR=\fItarget\fR] [\fB\-\-choosefiles\fR=\fItarget\fR]
[\fB\-\-choosedir\fR=\fItarget\fR] [\fB\-\-selectfile\fR=\fIfilepath\fR]
[\fB\-\-list\-unused\-keys\fR] [\fB\-\-list\-tagged\-files\fR=\fItag\fR]
[\fB\-\-profile\fR] [\fB\-\-cmd\fR=\fIcommand\fR] [\fIpath\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/config\fR.
They are usually installed to \fI/usr/lib/python*/site\-packages/ranger/config\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\-r\fR \fIdir\fR, \fB\-\-confdir\fR=\fIdir\fR" 14
.IX Item "-r dir, --confdir=dir"
Change the configuration directory of ranger from ~/.config/ranger to \*(L"dir\*(R".
.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: \fIall\fR,
\&\fIcommands\fR, \fIrc\fR, \fIrifle\fR, \fIscope\fR.
.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 absolute path of that file into
\&\fItargetfile\fR.
.IP "\fB\-\-choosefiles\fR=\fItargetfile\fR" 14
.IX Item "--choosefiles=targetfile"
Allows you to pick multiple files with ranger.  This changes the behavior so
that when you open a file, ranger will exit and write the absolute paths of all
selected files into \fItargetfile\fR, adding one newline after each filename.
.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.
.IP "\fB\-\-selectfile\fR=\fItargetfile\fR" 14
.IX Item "--selectfile=targetfile"
Open ranger with \fItargetfile\fR selected.
.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\-\-list\-tagged\-files\fR=\fItag\fR" 14
.IX Item "--list-tagged-files=tag"
List all files which are tagged with the given tag.  Note: Tags are single
characters.  The default tag is \*(L"*\*(R"
.IP "\fB\-\-profile\fR" 14
.IX Item "--profile"
Print statistics of \s-1CPU\s0 usage on exit.
.IP "\fB\-\-cmd\fR=\fIcommand\fR" 14
.IX Item "--cmd=command"
Execute the command after the configuration has been read.  Use this option
multiple times to run multiple commands.
.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"
This part explains how certain parts of ranger work and how they can be used
efficiently.
.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.
.PP
Independently of the preview script, there is a feature to preview images
by drawing them directly into the terminal.  This does not work over ssh,
requires certain terminals (tested on \*(L"xterm\*(R" and \*(L"urxvt\*(R") and is incompatible
with tmux, although it works with screen.
.PP
To enable this feature, install the program \*(L"w3m\*(R" and set the option
\&\f(CW\*(C`preview_images\*(C'\fR to true.
.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
\&\f(CW\*(C`shell\*(C'\fR command.
.PP
Additionally, if you create a key binding that uses <any>, a special statement
which accepts any key, then the macro \f(CW%any\fR (or \f(CW%any0\fR, \f(CW%any1\fR, \f(CW%any2\fR, ...) can be
used in the command to get the key that was pressed.
.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-1RIFLE\s0"
.IX Subsection "RIFLE"
Rifle is the file opener of ranger.  It can be used as a standalone program or
a python module.  It is located at \fIranger/ext/rifle.py\fR.  In contrast to
other, more simple file openers, rifle can automatically find installed
programs so it can be used effectively out of the box on a variety of systems.
.PP
It's configured in \fIrifle.conf\fR through a list of conditions and commands.
For each line the conditions are checked and if they are met, the respective
command is taken into consideration.  By default, simply the first matching
rule is used.  In ranger, you can list and choose rules by typing \*(L"r\*(R" or simply
by typing \*(L"<rulenumber><enter>\*(R".  If you use rifle standalone, you can list all
rules with the \*(L"\-l\*(R" option and pick a rule with \*(L"\-p <number>\*(R".
.PP
The rules, along with further documentation, are contained in
\&\fIranger/config/rifle.conf\fR.
.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 \f(CW\*(C`:open_with\*(C'\fR (key \*(L"r\*(R") and \f(CW\*(C`:shell\*(C'\fR (key \*(L"!\*(R").
.PP
.Vb 4
\& f   Fork the process.  (Run in background)
\& c   Run the current file only, instead of the selection
\& r   Run application with root privilege (requires sudo)
\& t   Run application in a new terminal window
.Ve
.PP
There are some additional flags that can currently be used only in the \f(CW\*(C`shell\*(C'\fR
command: (for example \f(CW\*(C`:shell \-w df\*(C'\fR)
.PP
.Vb 3
\& p   Redirect output to the pager
\& s   Silent mode.  Output will be discarded.
\& w   Wait for an Enter\-press when the process is done
.Ve
.PP
By default, all the flags are off unless specified otherwise in the
\&\fIrifle.conf\fR configuration file.  You can specify as many flags as you want.
An uppercase flag negates the effect: \*(L"ffcccFsf\*(R" is equivalent to \*(L"cs\*(R".
.PP
The terminal program name for the \*(L"t\*(R" flag is taken from the environment
variable \f(CW$TERMCMD\fR.  If it doesn't exist, it tries to extract it from \f(CW$TERM\fR and
uses \*(L"xterm\*(R" as a fallback if that fails.
.PP
Examples: \f(CW\*(C`:open_with c\*(C'\fR will open the file that you currently point at, even
if you have selected other files.  \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-1PLUGINS\s0"
.IX Subsection "PLUGINS"
ranger's plugin system consists of python files which are located in
\&\fI~/.config/ranger/plugins/\fR and are imported in alphabetical order when
starting ranger.  A plugin changes rangers behavior by overwriting or extending
a function that ranger uses.  This allows you to change pretty much every part
of ranger, but there is no guarantee that things will continue to work in
future versions as the source code evolves.
.PP
There are some hooks that are specifically made for the use in plugins.  They
are functions that start with hook_ and can be found throughout the code.
.PP
.Vb 1
\& grep \*(Aqdef hook_\*(Aq \-r /path/to/rangers/source
.Ve
.PP
Also try:
.PP
.Vb 1
\& pydoc ranger.api
.Ve
.PP
Note that you should \s-1NOT\s0 simply overwrite a function unless you know what
you're doing.  Instead, save the existing function and call it from your new
one.  This way, multiple plugins can use the same hook.  There are several
sample plugins in the \fI/usr/share/doc/ranger/examples/\fR directory, including a
hello-world plugin that describes this procedure.
.SH "KEY BINDINGS"
.IX Header "KEY BINDINGS"
Key bindings are defined in the file \fIranger/config/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
.IP "H, L" 14
.IX Item "H, L"
Move back and forward in the history
.IP "gg" 14
.IX Item "gg"
Move to the top
.IP "G" 14
.IX Item "G"
Move to the bottom
.IP "^R" 14
.IX Item "^R"
Reload everything
.IP "^L" 14
.IX Item "^L"
Redraw the screen
.IP "i" 14
.IX Item "i"
Display the current file in a bigger window.
.IP "E" 14
.IX Item "E"
Edit the current file in \f(CW$EDITOR\fR (\*(L"nano\*(R" by default)
.IP "S" 14
.IX Item "S"
Open a shell in the current directory
.IP "?" 14
Opens this man page
.IP "<octal>=, +<who><what>, \-<who><what>" 14
.IX Item "<octal>=, +<who><what>, -<who><what>"
Change the permissions of the selection.  For example, \f(CW\*(C`777=\*(C'\fR is equivalent to
\&\f(CW\*(C`chmod 777 %s\*(C'\fR, \f(CW\*(C`+ar\*(C'\fR does \f(CW\*(C`chmod a+r %s\*(C'\fR, \f(CW\*(C`\-ow\*(C'\fR does \f(CW\*(C`chmod o\-w %s\*(C'\fR etc.
.IP "yy" 14
.IX Item "yy"
Copy (yank) the selection, like pressing Ctrl+C in modern \s-1GUI\s0 programs.
.IP "dd" 14
.IX Item "dd"
Cut the selection, like pressing Ctrl+X in modern \s-1GUI\s0 programs.
.IP "pp" 14
.IX Item "pp"
Paste the files which were previously copied or cut, like pressing Ctrl+V in
modern \s-1GUI\s0 programs.
.IP "po" 14
.IX Item "po"
Paste the copied/cut files, overwriting existing files.
.IP "m\fIX\fR" 14
.IX Item "mX"
Create a bookmark with the name \fIX\fR
.IP "`\fIX\fR" 14
.IX Item "`X"
Move to the bookmark with the name \fIX\fR
.IP "n" 14
.IX Item "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)
.IP "z\fIX\fR" 14
.IX Item "zX"
Change settings.  See the settings section for a list of settings and their
hotkey.
.IP "u\fI?\fR" 14
.IX Item "u?"
Universal undo-key.  Depending on the key that you press after \*(L"u\*(R", it either
restores closed tabs (uq), removes tags (ut), clears the copy/cut buffer (ud),
starts the reversed visual mode (uV) or clears the selection (uv).
.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
.IP "V" 14
.IX Item "V"
Starts the visual mode, which selects all files between the starting point and
the cursor until you press \s-1ESC\s0.  To unselect files in the same way, use \*(L"uV\*(R".
.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.
.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 "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 while
scrolling 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/rc.conf\fR or on the
fly with the command \fB:set option value\fR.  Examples:
.PP
.Vb 2
\& set column_ratios 1,2,3
\& set show_hidden true
.Ve
.PP
The different types of settings and an example for each type:
.PP
.Vb 7
\& setting type   | example values
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& bool           | true, false
\& integer        | 1, 23, 1337
\& string         | foo, hello world
\& list           | 1,2,3,4
\& none           | none
.Ve
.PP
You can view a list of all settings and their current values by pressing \*(L"3?\*(R"
in ranger.
.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 "autoupdate_cumulative_size [bool]" 4
.IX Item "autoupdate_cumulative_size [bool]"
You can display the \*(L"real\*(R" cumulative size of directories by using the command
:get_cumulative_size or typing \*(L"dc\*(R".  The size is expensive to calculate and
will not be updated automatically.  You can choose to update it automatically
though by turning on this option.
.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 [string]" 4
.IX Item "colorscheme [string]"
Which colorscheme to use?  These colorschemes are available by default:
\&\fBdefault\fR, \fBjungle\fR, \fBsnow\fR.  Snow is a monochrome scheme, jungle replaces
blue directories with green ones for better visibility on certain terminals.
.IP "column_ratios [list]" 4
.IX Item "column_ratios [list]"
How many columns are there, and what are their relative widths?  For example, a
value of 1,1,1 would mean 3 evenly sized columns. 1,1,1,1,4 means 5 columns
with the preview column being as large as the other columns combined.
.IP "confirm_on_delete [string]" 4
.IX Item "confirm_on_delete [string]"
Ask for a confirmation when running the \*(L"delete\*(R" command?  Valid values are
\&\*(L"always\*(R" (default), \*(L"never\*(R", \*(L"multiple\*(R". With \*(L"multiple\*(R", ranger will ask only
if you delete multiple files at once.
.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_borders [bool]" 4
.IX Item "draw_borders [bool]"
Draw borders around columns?
.IP "draw_progress_bar_in_statusbar [bool]" 4
.IX Item "draw_progress_bar_in_statusbar [bool]"
Draw a progress bar in the status bar which displays the average state of all
currently running tasks which support progress bars?
.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 [string]" 4
.IX Item "hidden_filter [string]"
A regular expression pattern for files which should be hidden.  For example,
this pattern will hide all files that start with a dot or end with a tilde.
.Sp
.Vb 1
\& set hidden_filter ^\e.|~$
.Ve
.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?  \*(L"none\*(R" will disable the
limit.
.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_images [bool]" 4
.IX Item "preview_images [bool]"
Draw images inside the console with the external program w3mimgpreview?
.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]" 4
.IX Item "shorten_title [integer]"
Trim the title of the window if it gets long?  The number defines how many
directories are displayed at once. A value of 0 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>"
Reverse the order of files?
.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 typing an uppercase second letter in the key
combination, e.g. \*(L"oN\*(R" to sort from Z to A.
.IP "status_bar_on_top [bool]" 4
.IX Item "status_bar_on_top [bool]"
Put the status bar at the top of the window?
.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 [bo