path: root/doc/ranger.1

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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.4.3" "09/24/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 [\fIoptions\fR] [\fIpath/filename\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Ranger is a file manager with an ncurses frontend written in Python.
.PP
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
\&\fBvim\fR, \fBmutt\fR or \fBncmpcpp\fR so the usage will be intuitive and efficient.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-verison\fR" 14
.IX Item "--verison"
print the version and exit
.IP "\fB\-h\fR, \fB\-\-help\fR" 14
.IX Item "-h, --help"
print a list of options and exit
.IP "\fB\-d\fR, \fB\-\-debug\fR" 14
.IX Item "-d, --debug"
activate the debug mode: Whenever an erroroccurs, 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 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 behaviour so that when you open a file, ranger will exit and write the name of that file into \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.
.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, \fIapps\fR, \fIcommands\fR, \fIkeys\fR, \fIoptions\fR, \fIscope\fR.
.IP "\fB\-\-fail\-unless\-c\fRd" 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 filetype 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 behaviour.
the execution of this filetype is explicitly handled in the configuration.
.SH "KEY BINDINGS"
.IX Header "KEY 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 "S" 14
.IX Item "S"
Open a shell in the current directory
.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
.IP "`\fIX\fR" 14
.IX Item "`X"
Move to the bookmark with the name \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)
.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" 14
.IX Item "V"
Unmark all files
.IP "^V\fIdirection\fR" 14
.IX Item "^Vdirection"
Mark all files in the given direction.  Works just like d\fIdirection\fR.
.IP "g\fIN\fR" 14
.IX Item "gN"
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.
.IP "/" 14
Search for files in the current directory.
.IP ":" 14
Open the console.
.IP "?" 14
Opens the help screen with more keybindings and documentation
.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"
Scroll
.SH "COMMANDS"
.IX Header "COMMANDS"
.IP ":delete" 4
.IX Item ":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.
.IP ":rename \fInewname\fR" 4
.IX Item ":rename newname"
Rename the current file.  Also try the keybinding A for appending something
to a file name.
.IP ":quit" 4
.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.
.SH "FILES"
.IX Header "FILES"
ranger reads several configuration files which are located in
\&\f(CW$HOME\fR/.config/ranger or \f(CW$XDG_CONFIG_HOME\fR/ranger if \f(CW$XDG_CONFIG_HOME\fR is defined.
The configuration is done mostly in python.  (Note that python files get
compiled and the compiled files are stored in your configuration directory too.
Since python3 they are saved in the _\|_pycache_\|_ directory, earlier versions
store them with the .pyc extension in the same directory.)  When removing a
config file, remove the compiled file too.
.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
overlayed on top of the defaults (options.py, command.py, keys.py) or can be
subclassed (apps.py, colorschemes).
.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 "keys.py" 10
.IX Item "keys.py"
Defines keybindings.
.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 "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.
.IP "history" 10
.IX Item "history"
Contains a list of commands that have been previously typed in.
.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 \*(L"$HOME/.config\*(R".
.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 (to put in your ~/.bashrc) 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=/tmp/chosendir
\&   /usr/bin/ranger \-\-choosedir=$tempfile "$@"
\&   if [ \-f $tempfile \-a "$(cat $tempfile)" != "$(pwd | tr \-d "\en")" ]
\&   then
\&     cd "$(cat $tempfile)"
\&     rm $tempfile
\&   fi
\& }
.Ve
.SH "LICSENSE"
.IX Header "LICSENSE"
\&\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>" 4
.IX Item "Download: <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
.SH "BUGS"
.IX Header "BUGS"
Please report them here and include as much relevant information as possible: 
<http://savannah.nongnu.org/bugs/?group=ranger>