https://github.com/akkartik/mu/blob/master/081print.mu
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 container screen [
17 num-rows:num
18 num-columns:num
19 cursor-row:num
20 cursor-column:num
21 data:&:@:screen-cell
22 pending-scroll?:bool
23 top-idx:num
24
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
50 {
51 break-if screen
52
53 clear-display
54 return
55 }
56
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
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
78 return-unless screen, true
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
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
101 break-if color-found?
102 color <- copy 7/white
103 }
104 bg-color:num, bg-color-found?:bool <- next-input
105 {
106
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
114 break-if screen
115 print-character-to-display c, color, bg-color
116 return
117 }
118
119
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
127
128 row <- round row
129 column <- round column
130
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
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
148 {
149 pending-scroll?:bool <- get *screen, pending-scroll?:offset
150 break-unless pending-scroll?
151
152 scroll-fake-screen screen
153 *screen <- put *screen, pending-scroll?:offset, false
154 }
155
156
157 {
158 newline?:bool <- equal c, 10/newline
159 break-unless newline?
160 cursor-down-on-fake-screen screen
161 return
162 }
163
164 {
165 linefeed?:bool <- equal c, 13/linefeed
166 break-unless linefeed?
167 *screen <- put *screen, cursor-column:offset, 0
168 return
169 }
170
171
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
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
188
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
198
199 *screen <- put *screen, pending-scroll?:offset, true
200 row <- subtract row, 1
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
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
222 }
223 ]
224
225 def scroll-fake-screen screen:&:screen -> screen:&:screen [
226 local-scope
227 load-inputs
228
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
233 top-idx:num <- get *screen, top-idx:offset
234 next-top-idx:num <- add top-idx, width
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
242
243 loop
244 }
245
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
252
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
278 2 <- 97
279 3 <- 7
280
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
297 2 <- 97
298 3 <- 7
299
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
315 2 <- 97
316 3 <- 1
317
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