From 71c57a7b150447e6120e0a7e2735dfe827975512 Mon Sep 17 00:00:00 2001 From: David Pugnasse Date: Wed, 10 Aug 2011 10:46:59 +0200 Subject: improved renaming doesn't overwrite files creates directories on rename --- ranger/core/actions.py | 2 +- ranger/defaults/commands.py | 15 ++++++++++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/ranger/core/actions.py b/ranger/core/actions.py index 8cecf077..7bb80343 100644 --- a/ranger/core/actions.py +++ b/ranger/core/actions.py @@ -830,6 +830,6 @@ class Actions(FileManagerAware, EnvironmentAware, SettingsAware): src = src.path try: - os.rename(src, dest) + os.renames(src, dest) except OSError as err: self.notify(err) diff --git a/ranger/defaults/commands.py b/ranger/defaults/commands.py index ad3fa0e5..319c5cef 100644 --- a/ranger/defaults/commands.py +++ b/ranger/defaults/commands.py @@ -632,11 +632,20 @@ class rename(Command): def execute(self): from ranger.fsobject import File + from os import access + from os.path import join + line = parse(self.line) - if not line.rest(1): + new_name = line.rest(1) + + if not new_name: return self.fm.notify('Syntax: rename ', bad=True) - self.fm.rename(self.fm.env.cf, line.rest(1)) - f = File(line.rest(1)) + + if access(new_name, os.F_OK): + return self.fm.notify("Can't rename: file already exists!", bad=True) + + self.fm.rename(self.fm.env.cf, new_name) + f = File(new_name) self.fm.env.cwd.pointed_obj = f self.fm.env.cf = f -- cgit 1.4.1-2-gfad0 From c7720fff4fc500dab7cfb2d2b3b63e2b966502d2 Mon Sep 17 00:00:00 2001 From: hut Date: Sat, 24 Sep 2011 17:57:00 +0200 Subject: Overhauled manpage. It's in POD format now. --- Makefile | 6 +- doc/ranger.1 | 577 ++++++++++++++++++++++++++++++++++++++------------------- doc/ranger.pod | 414 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 802 insertions(+), 195 deletions(-) create mode 100644 doc/ranger.pod diff --git a/Makefile b/Makefile index fd525721..1c0b5fda 100644 --- a/Makefile +++ b/Makefile @@ -63,6 +63,10 @@ doc: cleandoc pydoc.writedocs("$(CWD)")' find . -name \*.html -exec sed -i 's|'$(CWD)'|../..|g' -- {} \; +man: + pod2man --stderr --center='ranger manual' --date='$(NAME)-$(VERSION)' \ + --release=$(shell date +%x) doc/ranger.pod doc/ranger.1 + cleandoc: test -d $(DOCDIR) && rm -f -- $(DOCDIR)/*.html || true @@ -75,4 +79,4 @@ bm: snapshot: git archive --prefix='$(NAME)-$(VERSION)/' --format=tar HEAD | gzip > $(SNAPSHOT_NAME) -.PHONY: default options compile clean doc cleandoc test bm snapshot install +.PHONY: default options compile clean doc cleandoc test bm snapshot install man diff --git a/doc/ranger.1 b/doc/ranger.1 index 5b9d9df8..4d6dab24 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -1,226 +1,415 @@ -.TH RANGER 1 ranger-1.4.3 -.SH NAME -ranger - visual file manager -.\"----------------------------------------- -.SH SYNOPSIS -.B ranger -.R [OPTIONS] [FILE] -.\"----------------------------------------- -.SH DESCRIPTION +.\" 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. -.P +.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 -.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 +\&\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. -.TP ---copy-config=\fIwhich\fR +.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: -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\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 +\&\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 -.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 +.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 \fBpo\fR. -.TP -m\fIX\fR +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 +.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. -.TP -gn, ^N +.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 +.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, "enter" it, like a directory, by clicking on the preview. -.TP -Right Mouse Button -Enter a directory -.TP -Scroll Wheel +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 -.\"----------------------------------------- -.SS Commands -.TP -:delete +.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. -.TP -:rename \fInewname\fR +.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. -.TP -:quit +.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 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://savannah.nongnu.org/projects/ranger > -.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 > +.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() +.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: " 4 +.IX Item "Download: " +.PD 0 +.IP "The project page: " 4 +.IX Item "The project page: " +.IP "The mailing list: " 4 +.IX Item "The mailing list: " +.PD +.SH "BUGS" +.IX Header "BUGS" +Please report them here and include as much relevant information as possible: + diff --git a/doc/ranger.pod b/doc/ranger.pod new file mode 100644 index 00000000..db3210b2 --- /dev/null +++ b/doc/ranger.pod @@ -0,0 +1,414 @@ +=head1 NAME + +ranger - visual file manager + + + + +=head1 SYNOPSIS + +B [I] [I] + + + + +=head1 DESCRIPTION + +Ranger is a file manager with an ncurses frontend written in Python. + +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 +B, B or B so the usage will be intuitive and efficient. + + + + +=head1 OPTIONS + +=over 14 + +=item B<--verison> + +print the version and exit + +=item B<-h>, B<--help> + +print a list of options and exit + +=item B<-d>, B<--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. + +=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 + +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 I. + +=item B<--choosedir>=I + +Allows you to pick a directory with ranger. When you exit ranger, it will write the last visited directory into I. + +=item B<--copy-config>=I + +Create copies of the default configuration files in your local configuration +directory. Existing ones will not be overwritten. Possible values: +I, I, I, I, I, I. + +=item B<--fail-unless-c>d + +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, B<--mode>=I + +When a filename is supplied, run it in mode I. This has no effect unless +the execution of this filetype is explicitly handled in the configuration. + +=item B<-f> I, B<--flags>=I + +When a filename is supplied, run it with the given I to modify behaviour. +the execution of this filetype is explicitly handled in the configuration. + +=back + + + + +=head1 KEY 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 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. + +=item mI + +Create a bookmark with the name I + +=item `I + +Move to the bookmark with the name I + +=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 + +Change the sort method (like in mutt) + +=item zI + +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 + +Unmark all files + +=item ^VI + +Mark all files in the given direction. Works just like dI. + +=item gI + +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. + +=item / + +Search for files in the current directory. + +=item : + +Open the console. + +=item ? + +Opens the help screen with more keybindings and documentation + +=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 + +Scroll + +=back + + + + +=head1 COMMANDS + +=over + +=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. + +=item :rename I + +Rename the current file. Also try the keybinding A for appending something +to a file name. + +=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. + +=back + + + + +=head1 FILES + +ranger reads several configuration files which are located in +$HOME/.config/ranger or $XDG_CONFIG_HOME/ranger if $XDG_CONFIG_HOME 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. + +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 +overlayed on top of the defaults (options.py, command.py, keys.py) or can be +subclassed (apps.py, colorschemes). + +=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 keys.py + +Defines keybindings. + +=item options.py + +Sets a handful of basic options. + +=item scope.sh + +This is a script that handles file previews. When the options I and I or, respectively, I are set, the program specified in the option I 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 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. + +=item history + +Contains a list of commands that have been previously typed in. + +=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 "$HOME/.config". + +=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() + +=head2 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 C to go +back to the original one. + + function ranger-cd { + tempfile=/tmp/chosendir + /usr/bin/ranger --choosedir=$tempfile "$@" + if [ -f $tempfile -a "$(cat $tempfile)" != "$(pwd | tr -d "\n")" ] + then + cd "$(cat $tempfile)" + rm $tempfile + fi + } + + + + +=head1 LICSENSE + +GNU General Public License 3 or (at your option) any later version. + + + + +=head1 LINKS + +=over + +=item Download: L + +=item The project page: L + +=item The mailing list: L + +=back + + + + +=head1 BUGS + +Please report them here and include as much relevant information as possible: +L -- cgit 1.4.1-2-gfad0 From 951afe4b3e9142e9a0ac772f2dd537fee7deca20 Mon Sep 17 00:00:00 2001 From: hut Date: Sat, 24 Sep 2011 23:53:05 +0200 Subject: doc/ranger.pod: extended the man page --- doc/ranger.1 | 446 ++++++++++++++++++++++++++++++++++++++++++------- doc/ranger.pod | 519 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 845 insertions(+), 120 deletions(-) diff --git a/doc/ranger.1 b/doc/ranger.1 index 4d6dab24..9fc64759 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -136,55 +136,66 @@ ranger \- visual file manager \&\fBranger\fR [\fIoptions\fR] [\fIpath/filename\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" -Ranger is a file manager with an ncurses frontend written in Python. +Ranger is a file manager with an ncurses front-end 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. +previews and backviews, dividing the screen into several columns. The +key bindings 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 +Print the version and exit. .IP "\fB\-h\fR, \fB\-\-help\fR" 14 .IX Item "-h, --help" -print a list of options and exit +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. +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. +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. +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. .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. +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. +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.) +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. +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 behaviour. -the execution of this filetype is explicitly handled in the configuration. +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. .SH "KEY BINDINGS" .IX Header "KEY BINDINGS" +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\fR to mark 10 files +or \fI3?\fR to read the third chapter of the documentation. +.PP +Key bindings can be changed. Detailed instructions for this are in the +key binding configuration file at ranger/defaults/keys.py. You can copy it to +your local configuration directory with the \-\-copy\-config option. .IP "h, j, k, l" 14 .IX Item "h, j, k, l" Move left, down, up or right @@ -217,9 +228,9 @@ Yank the selection to the \*(L"copy\*(R" buffer and mark them as to be copied 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. +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 @@ -229,8 +240,8 @@ 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. +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. @@ -239,7 +250,8 @@ Find the previous file. 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. +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. @@ -249,16 +261,19 @@ 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" +.IP "V, uv" 14 +.IX Item "V, uv" 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 "u^V\fIdirection\fR" 14 +.IX Item "u^Vdirection" +Unmark 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. +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. @@ -273,50 +288,331 @@ Search for files in the current directory. .IP ":" 14 Open the console. .IP "?" 14 -Opens the help screen with more keybindings and documentation +Opens the help screen with more key bindings and documentation +.SS "\s-1MIDNIGHT\s0 COMMANDER-LIKE \s-1BINDINGS\s0" +.IX Subsection "MIDNIGHT COMMANDER-LIKE BINDINGS" +.IP "" 14 +.IX Item "" +Display Help. +.IP "" 14 +.IX Item "" +Display the file. +.IP "" 14 +.IX Item "" +Edit the file. +.IP "" 14 +.IX Item "" +Copy the file. +.IP "" 14 +.IX Item "" +Cut the file. +.IP "" 14 +.IX Item "" +Open the console with \*(L":mkdir \*(R". +.IP "" 14 +.IX Item "" +Prompt for deletion of the selected files. +.IP "" 14 +.IX Item "" +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. +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 +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 , if +a hotkey exists. +.PP +Settings can be changed in the file ~/.config/ranger/options.py or on the fly +with the command \fB:set option value\fR. Examples: \f(CW\*(C`:set column_ratios (1,2,3)\*(C'\fR, +\&\f(CW\*(C`:set show_hidden=True\*(C'\fR +.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] " 4 +.IX Item "collapse_preview [bool] " +When no preview is visible, should the last column be squeezed to make use of +the whitespace? +.IP "colorscheme_overlay [python function, None]" 4 +.IX Item "colorscheme_overlay [python 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] " 4 +.IX Item "flushinput [bool] " +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 [regular expression]" 4 +.IX Item "hidden_filter [regular expression]" +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] " 4 +.IX Item "mouse_enabled [bool] " +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] " 4 +.IX Item "preview_directories [bool] " +Preview directories in the preview column? +.IP "preview_files [bool] " 4 +.IX Item "preview_files [bool] " +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] , <^H>" 4 +.IX Item "show_hidden [bool] , <^H>" +Show hidden files? +.IP "sort_case_insensitive [bool] " 4 +.IX Item "sort_case_insensitive [bool] " +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] " 4 +.IX Item "sort_directories_first [bool] " +Sort directories first? +.IP "sort_reverse [bool] " 4 +.IX Item "sort_reverse [bool] " +Sort reversed? +.IP "sort [string] , , , , , , " 4 +.IX Item "sort [string] , , , , , , " +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] " 4 +.IX Item "use_preview_script [bool] " +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" -.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 +.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 "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 [\-+] and = 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 "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 \fIpython_code\fR" 2 +.IX Item "eval python_code" +Evaluates the python code. `fm' is a reference to the \s-1FM\s0 instance. To display +text, use the function `p'. +.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 \fIconfdir/copy_buffer\fR. This can be used to pass the +list of copied files to another ranger instance. +.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 "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, it will be +overwritten without notice. Also try the key binding 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. +.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 7 +\& None None +\& bool True or False +\& list [1, 2, 3] +\& tuple 1, 2, 3 or (1, 2, 3) +\& function lambda : +\& regexp regexp(\*(Aq\*(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 "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 \&\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. +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.) When removing a -config file, remove the compiled file too. +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 -overlayed on top of the defaults (options.py, command.py, keys.py) or can be -subclassed (apps.py, colorschemes). +overlaid on top of the defaults (options.py, command.py, keys.py) or can be +sub-classed (apps.py, colorschemes). .SS "\s-1CONFIGURATION\s0" .IX Subsection "CONFIGURATION" .IP "apps.py" 10 @@ -327,26 +623,43 @@ Controls which applications are used to open files. Defines commands which can be used by typing \*(L":\*(R". .IP "keys.py" 10 .IX Item "keys.py" -Defines keybindings. +Defines key bindings. .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. +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, accessed by typing +\&' and deleted by typing um. +.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. -.IP "history" 10 -.IX Item "history" -Contains a list of commands that have been previously typed in. +the path to the file. In ranger, tags can be set by pressing t and removed +with T. To assign a named tag, type ". .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" These environment variables have an effect on ranger: @@ -396,8 +709,8 @@ back to the original one. \& fi \& } .Ve -.SH "LICSENSE" -.IX Header "LICSENSE" +.SH "LICENSE" +.IX Header "LICENSE" \&\s-1GNU\s0 General Public License 3 or (at your option) any later version. .SH "LINKS" .IX Header "LINKS" @@ -409,7 +722,16 @@ back to the original one. .IP "The mailing list: " 4 .IX Item "The mailing list: " .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" -Please report them here and include as much relevant information as possible: - +Please report bugs here: +.PP +In many cases, ranger prints more diagnostics information when you run it with +the \fB\-\-debug\fR option. Please include as much relevant information as possible. diff --git a/doc/ranger.pod b/doc/ranger.pod index db3210b2..4bd12889 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -14,12 +14,12 @@ B [I] [I] =head1 DESCRIPTION -Ranger is a file manager with an ncurses frontend written in Python. +Ranger is a file manager with an ncurses front-end written in Python. 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 -B, B or B so the usage will be intuitive and efficient. +previews and backviews, dividing the screen into several columns. The +key bindings are similar to those of other console programs like B, +B or B so the usage will be intuitive and efficient. @@ -30,52 +30,56 @@ B, B or B so the usage will be intuitive and efficient. =item B<--verison> -print the version and exit +Print the version and exit. =item B<-h>, B<--help> -print a list of options and exit +Print a list of options and exit. =item B<-d>, B<--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. +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. +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 -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 I. +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. =item B<--choosedir>=I -Allows you to pick a directory with ranger. When you exit ranger, it will write the last visited directory into I. +Allows you to pick a directory with ranger. When you exit ranger, it will +write the last visited directory into I. =item B<--copy-config>=I Create copies of the default configuration files in your local configuration -directory. Existing ones will not be overwritten. Possible values: -I, I, I, I, I, I. +directory. Existing ones will not be overwritten. Possible values: I, +I, I, I, I, I. =item B<--fail-unless-c>d -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.) +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, B<--mode>=I When a filename is supplied, run it in mode I. This has no effect unless -the execution of this filetype is explicitly handled in the configuration. +the execution of this file type is explicitly handled in the configuration. =item B<-f> I, B<--flags>=I -When a filename is supplied, run it with the given I to modify behaviour. -the execution of this filetype is explicitly handled in the configuration. +When a filename is supplied, run it with the given I to modify +behavior. The execution of this file type is explicitly handled in the +configuration. =back @@ -84,6 +88,14 @@ the execution of this filetype is explicitly handled in the configuration. =head1 KEY BINDINGS +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> to mark 10 files +or I<3?> to read the third chapter of the documentation. + +Key bindings can be changed. Detailed instructions for this are in the +key binding configuration file at ranger/defaults/keys.py. You can copy it to +your local configuration directory with the --copy-config option. + =over 14 =item h, j, k, l @@ -128,9 +140,9 @@ 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. +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. =item mI @@ -143,8 +155,8 @@ Move to the bookmark with the name I =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. +directory, but if you search something using the keys /, cm, ct, ..., it will +get you to the next found entry. =item N @@ -156,7 +168,8 @@ Change the sort method (like in mutt) =item zI -Change settings. See the settings section for a list of settings and their hotkey. +Change settings. See the settings section for a list of settings and their +hotkey. =item f @@ -170,7 +183,7 @@ Mark a file. Toggle the mark-status of all files, unmark all files. -=item V +=item V, uv Unmark all files @@ -178,10 +191,14 @@ Unmark all files Mark all files in the given direction. Works just like dI. +=item u^VI + +Unmark all files in the given direction. Works just like dI. + =item gI -Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, -it will be created. +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 @@ -205,11 +222,73 @@ Open the console. =item ? -Opens the help screen with more keybindings and documentation +Opens the help screen with more key bindings and documentation =back +=head2 MIDNIGHT COMMANDER-LIKE BINDINGS + +=over 14 + +=item + +Display Help. + +=item + +Display the file. + +=item + +Edit the file. +=item + +Copy the file. + +=item + +Cut the file. + +=item + +Open the console with ":mkdir ". + +=item + +Prompt for deletion of the selected files. + +=item + +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 @@ -218,8 +297,8 @@ Opens the help screen with more keybindings and documentation =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. +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 @@ -227,32 +306,330 @@ Enter a directory or run a file. =item Scroll Wheel -Scroll +Scrolls up or down. You can point at the column of the parent directory to +switch directories. =back -=head1 COMMANDS +=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 , if +a hotkey exists. + +Settings can be changed in the file ~/.config/ranger/options.py or on the fly +with the command B<:set option value>. Examples: C<:set column_ratios (1,2,3)>, +C<:set show_hidden=True> =over -=item :delete +=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] + +When no preview is visible, should the last column be squeezed to make use of +the whitespace? + +=item colorscheme_overlay [python 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, B, B, B, B. 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] + +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 [regular expression] + +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] + +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] + +Preview directories in the preview column? + +=item preview_files [bool] + +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] -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. +Show dotfiles in the bookmark preview window? (Type ') -=item :rename I +=item show_hidden [bool] , <^H> -Rename the current file. Also try the keybinding A for appending something +Show hidden files? + +=item sort_case_insensitive [bool] + +Sort case-insensitively? If true, "a" will be listed before "B" even though its ASCII value is higher. + +=item sort_directories_first [bool] + +Sort directories first? + +=item sort_reverse [bool] + +Sort reversed? + +=item sort [string] , , , , , , + +Which sorting mechanism should be used? Choose one of B, B, +B, B, B, B, B + +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] + +Use the preview script defined in the setting I? + +=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 + +=over 2 + +=item cd [I] + +The cd command changes the directory. The command C<:cd -> is equivalent to +typing ``. + +=item chmod I + +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 [-+] and = 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 delete [I] + +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] + +Edit the current file or the file in the argument. + +=item eval I + +Evaluates the python code. `fm' is a reference to the FM instance. To display +text, use the function `p'. + +Examples: + :eval fm + :eval len(fm.env.directories) + :eval p("Hello World!") + +=item filter [I] + +Displays only the files which contain the I in their basename. + +=item find I + +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 + +Looks for a string in all marked files or directories. + +=item load_copy_buffer + +Load the copy buffer from I. This can be used to pass the +list of copied files to another ranger instance. + +=item mark I + +Mark all files matching the regular expression pattern. + +=item mkdir I + +Creates a directory with the name I. + +=item open_with [I] [I] [I] + +Open the selected files with the given application, unless it is omitted, in +which case the default application is used. I are characters out of +"sdpcwSDPCW" and I is any positive integer. Their meanings are discussed +in their own sections. + +=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 + +Rename the current file. If a file with that name already exists, it will be +overwritten without notice. Also try the key binding A for appending something to a file name. -=item :quit +=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 + +Search files in the current directory that match the given (case insensitive) +regular expression pattern. + +=item search_inc I + +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