diff options
| -rw-r--r-- | Makefile | 9 | ||||
| -rw-r--r-- | doc/ranger.1 | 943 | ||||
| -rw-r--r-- | doc/ranger.pod | 832 | ||||
| -rw-r--r-- | ranger/container/settingobject.py | 2 | ||||
| -rw-r--r-- | ranger/core/actions.py | 15 | ||||
| -rw-r--r-- | ranger/core/helper.py | 3 | ||||
| -rw-r--r-- | ranger/core/runner.py | 2 | ||||
| -rw-r--r-- | ranger/defaults/commands.py | 68 | ||||
| -rw-r--r-- | ranger/defaults/keys.py | 24 | ||||
| -rw-r--r-- | ranger/fsobject/directory.py | 1 | ||||
| -rw-r--r-- | ranger/gui/widgets/console.py | 7 | ||||
| -rw-r--r-- | ranger/gui/widgets/pager.py | 16 | ||||
| -rw-r--r-- | ranger/help/console.py | 13 | ||||
| -rw-r--r-- | ranger/help/starting.py | 1 |
14 files changed, 1703 insertions, 233 deletions
diff --git a/Makefile b/Makefile index fd525721..ed100a8e 100644 --- a/Makefile +++ b/Makefile @@ -63,6 +63,13 @@ 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 + +manhtml: + pod2html doc/ranger.pod --outfile=doc/ranger.1.html + cleandoc: test -d $(DOCDIR) && rm -f -- $(DOCDIR)/*.html || true @@ -75,4 +82,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..406297bd 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -1,226 +1,751 @@ -.TH RANGER 1 ranger-1.4.3 -.SH NAME -ranger - visual file manager -.\"----------------------------------------- -.SH SYNOPSIS -.B ranger -.R [OPTIONS] [FILE] -.\"----------------------------------------- -.SH DESCRIPTION -Ranger is a file manager with an ncurses frontend written in Python. -.P +.\" 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/25/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 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 -.BR vim ", " mutt " or " ncmpcpp -so the usage will be intuitive and efficient. -.\"----------------------------------------- -.SH OPTIONS -.TP ---version +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. -.TP --h, --help +.IP "\fB\-h\fR, \fB\-\-help\fR" 14 +.IX Item "-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 +.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. -.TP ---copy-config=\fIwhich\fR +files nor will it leave any traces on your system. This is useful when your +configuration is broken, when you want to avoid clutter, etc. +.IP "\fB\-\-choosefile\fR=\fItargetfile\fR" 14 +.IX Item "--choosefile=targetfile" +Allows you to pick a file with ranger. This changes the behavior so that when +you open a file, ranger will exit and write the name of that file into +\&\fItargetfile\fR. +.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<Space>\fR to mark 10 files or \fI3?\fR to read the -third chapter of the documentation. -.TP -h, j, k, l -Move left, down, up, right -.TP -^D or J, ^U or K +directory. Existing ones will not be overwritten. Possible values: \fIall\fR, +\&\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 file type is explicitly handled in the configuration. +.IP "\fB\-f\fR \fIflags\fR, \fB\-\-flags\fR=\fIflags\fR" 14 +.IX Item "-f flags, --flags=flags" +When a filename is supplied, run it with the given \fIflags\fR to modify +behavior. The execution of this file type is explicitly handled in the +configuration. +.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<Space>\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 \fIranger/defaults/keys.py\fR. 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 +.IP "^D or J, ^U or K" 14 +.IX Item "^D or J, ^U or K" Move a half page down, up -.TP -H, L +.IP "H, L" 14 +.IX Item "H, L" Move back and forward in the history -.TP -gg +.IP "gg" 14 +.IX Item "gg" Move to the top -.TP -G +.IP "G" 14 +.IX Item "G" Move to the bottom -.TP -^R +.IP "^R" 14 +.IX Item "^R" Reload everything -.TP -^L +.IP "^L" 14 +.IX Item "^L" Redraw the screen -.TP -S +.IP "S" 14 +.IX Item "S" Open a shell in the current directory -.TP -yy -Yank the selection to the "copy" buffer and mark them as to be copied -.TP -dd -Cut the selection to the "copy" buffer and mark them as to be moved -.TP -pp -Paste the files from the "copy" buffer here (by moving or copying, depending -on how they are marked.) By default, this will not overwrite existing files. -To overwrite them, use \fBpo\fR. -.TP -m\fIX\fR +.IP "yy" 14 +.IX Item "yy" +Yank the selection to the \*(L"copy\*(R" buffer and mark them as to be copied +.IP "dd" 14 +.IX Item "dd" +Cut the selection to the \*(L"copy\*(R" buffer and mark them as to be moved +.IP "pp" 14 +.IX Item "pp" +Paste the files from the \*(L"copy\*(R" buffer here (by moving or copying, depending on +how they are marked.) By default, this will not overwrite existing files. To +overwrite them, use \fIpo\fR. +.IP "m\fIX\fR" 14 +.IX Item "mX" Create a bookmark with the name \fIX\fR -.TP -`\fIX\fR +.IP "`\fIX\fR" 14 +.IX Item "`X" Move to the bookmark with the name \fIX\fR -.TP -n, N -Find the next file, the previous file. You can define what to look for -by typing c\fIX\fR. If nothing is specified, pressing n will get you to -the newest file in the directory. -.TP -o\fIX\fR +.IP "n, N" 14 +.IX Item "n, N" +Find the next file. By default, this gets you to the newest file in the +directory, but if you search something using the keys /, cm, ct, ..., it will +get you to the next found entry. +.IP "N" 14 +.IX Item "N" +Find the previous file. +.IP "o\fIX\fR" 14 +.IX Item "oX" Change the sort method (like in mutt) -.TP -z\fIX\fR -Change settings -.TP -f -Quickly navigate by entering a part of the filename -.TP -Space -Mark a file -.TP -v, V -Toggle the mark-status of all files, unmark all files -.TP -/ -Open the search console -.TP -: -Open the command console -.TP -? -Opens the help screen with more keybindings and documentation -.\"----------------------------------------- -.SS Keybindings for using Tabs -Tabs are used to work in different directories in the same Ranger instance. -.TP -g\fIN\fR -Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, -it will be created. -.TP -gn, ^N +.IP "z\fIX\fR" 14 +.IX Item "zX" +Change settings. See the settings section for a list of settings and their +hotkey. +.IP "f" 14 +.IX Item "f" +Quickly navigate by entering a part of the filename. +.IP "Space" 14 +.IX Item "Space" +Mark a file. +.IP "v" 14 +.IX Item "v" +Toggle the mark-status of all files, unmark all files. +.IP "V, uv" 14 +.IX Item "V, uv" +Unmark all files +.IP "^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. +.IP "gn, ^N" 14 +.IX Item "gn, ^N" Create a new tab. -.TP -gt, gT -Go to the next or previous tab. You can also use TAB and SHIFT+TAB. -.TP -gc, ^W -Close the current tab. The last tab cannot be closed. -.P -.\"----------------------------------------- -.SS Mouse Usage -.TP -Left Mouse Button -Click on something and you'll move there. -To run a file, "enter" it, like a directory, by clicking on the preview. -.TP -Right Mouse Button -Enter a directory -.TP -Scroll Wheel -Scroll -.\"----------------------------------------- -.SS Commands -.TP -:delete -Destroy all files in the selection with a roundhouse kick. Ranger will -ask for a confirmation if you attempt to delete multiple (marked) files or -non-empty directories. -.TP -:rename \fInewname\fR -Rename the current file. Also try the keybinding A for appending something +.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 key bindings and documentation +.SS "\s-1MIDNIGHT\s0 COMMANDER-LIKE \s-1BINDINGS\s0" +.IX Subsection "MIDNIGHT COMMANDER-LIKE BINDINGS" +.IP "<F1>" 14 +.IX Item "<F1>" +Display Help. +.IP "<F3>" 14 +.IX Item "<F3>" +Display the file. +.IP "<F4>" 14 +.IX Item "<F4>" +Edit the file. +.IP "<F5>" 14 +.IX Item "<F5>" +Copy the file. +.IP "<F6>" 14 +.IX Item "<F6>" +Cut the file. +.IP "<F7>" 14 +.IX Item "<F7>" +Open the console with \*(L":mkdir \*(R". +.IP "<F8>" 14 +.IX Item "<F8>" +Prompt for deletion of the selected files. +.IP "<F10>" 14 +.IX Item "<F10>" +Exit ranger. +.SS "READLINE-LIKE \s-1BINDINGS\s0 \s-1IN\s0 \s-1THE\s0 \s-1CONSOLE\s0" +.IX Subsection "READLINE-LIKE BINDINGS IN THE CONSOLE" +.IP "^B, ^F" 14 +.IX Item "^B, ^F" +Move left and right (B for back, F for forward) +.IP "^P, ^N" 14 +.IX Item "^P, ^N" +Move up and down (P for previous, N for Next) +.IP "^A, ^E" 14 +.IX Item "^A, ^E" +Move to the start or to the end +.IP "^D" 14 +.IX Item "^D" +Delete the current character. +.IP "^H" 14 +.IX Item "^H" +Backspace. +.SH "MOUSE BUTTONS" +.IX Header "MOUSE BUTTONS" +.IP "Left Mouse Button" 4 +.IX Item "Left Mouse Button" +Click on something and you'll move there. To run a file, \*(L"enter\*(R" it, like a +directory, by clicking on the preview. +.IP "Right Mouse Button" 4 +.IX Item "Right Mouse Button" +Enter a directory or run a file. +.IP "Scroll Wheel" 4 +.IX Item "Scroll Wheel" +Scrolls up or down. You can point at the column of the parent directory to +switch directories. +.SH "SETTINGS" +.IX Header "SETTINGS" +This section lists all built-in settings of ranger. The valid types for the +value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if +a hotkey exists. +.PP +Settings can be changed in the file \fI~/.config/ranger/options.py\fR or on the +fly with the command \fB:set option value\fR. Examples: + :set column_ratios (1,2,3) + :set show_hidden=True +.IP "autosave_bookmarks [bool]" 4 +.IX Item "autosave_bookmarks [bool]" +Save bookmarks (used with mX and `X) instantly? This helps to synchronize +bookmarks between multiple ranger instances but leads to *slight* performance +loss. When false, bookmarks are saved when ranger is exited. +.IP "collapse_preview [bool] <zc>" 4 +.IX Item "collapse_preview [bool] <zc>" +When no preview is visible, should the last column be squeezed to make use of +the whitespace? +.IP "colorscheme_overlay [function, None]" 4 +.IX Item "colorscheme_overlay [function, None]" +An overlay function for colorschemes. See the default options.py for an +explanation and an example. +.IP "colorscheme [string]" 4 +.IX Item "colorscheme [string]" +Which colorscheme to use? These colorschemes are available by default: +\&\fBdefault\fR, \fBdefault88\fR, \fBtexas\fR, \fBjungle\fR, \fBsnow\fR. Snow is monochrome, +texas and default88 use 88 colors. +.IP "column_ratios [tuple, list]" 4 +.IX Item "column_ratios [tuple, list]" +How many columns are there, and what are their relative widths? For example, a +value of (1, 1, 1) would mean 3 even sized columns. (1, 1, 1, 1, 4) means 5 columns +with the preview column being as large as the other columns combined. +.IP "dirname_in_tabs [bool]" 4 +.IX Item "dirname_in_tabs [bool]" +Display the directory name in tabs? +.IP "display_size_in_main_column [bool]" 4 +.IX Item "display_size_in_main_column [bool]" +Display the file size in the main column? +.IP "display_size_in_status_bar [bool]" 4 +.IX Item "display_size_in_status_bar [bool]" +Display the file size in the status bar? +.IP "display_tags_in_all_columns [bool]" 4 +.IX Item "display_tags_in_all_columns [bool]" +Display tags in all columns? +.IP "draw_bookmark_borders [bool]" 4 +.IX Item "draw_bookmark_borders [bool]" +Draw borders around the bookmark window? +.IP "draw_borders [bool]" 4 +.IX Item "draw_borders [bool]" +Draw borders around columns? +.IP "flushinput [bool] <zi>" 4 +.IX Item "flushinput [bool] <zi>" +Flush the input after each key hit? One advantage is that when scrolling down +with \*(L"j\*(R", ranger stops scrolling instantly when you release the key. One +disadvantage is that when you type commands blindly, some keys might get lost. +.IP "hidden_filter [regexp]" 4 +.IX Item "hidden_filter [regexp]" +A regular expression pattern for files which should be hidden. +.IP "max_console_history_size [integer, None]" 4 +.IX Item "max_console_history_size [integer, None]" +How many console commands should be kept in history? +.IP "max_history_size [integer, None]" 4 +.IX Item "max_history_size [integer, None]" +How many directory changes should be kept in history? +.IP "mouse_enabled [bool] <zm>" 4 +.IX Item "mouse_enabled [bool] <zm>" +Enable mouse input? +.IP "padding_right [bool]" 4 +.IX Item "padding_right [bool]" +When collapse_preview is on and there is no preview, should there remain a +little padding on the right? This allows you to click into that space to run +the file. +.IP "preview_directories [bool] <zP>" 4 +.IX Item "preview_directories [bool] <zP>" +Preview directories in the preview column? +.IP "preview_files [bool] <zp>" 4 +.IX Item "preview_files [bool] <zp>" +Preview files in the preview column? +.IP "preview_script [string, None]" 4 +.IX Item "preview_script [string, None]" +Which script should handle generating previews? If the file doesn't exist, or +use_preview_script is off, ranger will handle previews itself by just printing +the content. +.IP "save_console_history [bool]" 4 +.IX Item "save_console_history [bool]" +Should the console history be saved on exit? If disabled, the console history +is reset when you restart ranger. +.IP "scroll_offset [integer]" 4 +.IX Item "scroll_offset [integer]" +Try to keep this much space between the top/bottom border when scrolling. +.IP "shorten_title [integer, bool]" 4 +.IX Item "shorten_title [integer, bool]" +Trim the title of the window if it gets long? The number defines how many +directories are displayed at once, False turns off this feature. +.IP "show_cursor [bool]" 4 +.IX Item "show_cursor [bool]" +Always show the terminal cursor? +.IP "show_hidden_bookmarks [bool]" 4 +.IX Item "show_hidden_bookmarks [bool]" +Show dotfiles in the bookmark preview window? (Type ') +.IP "show_hidden [bool] <zh>, <^H>" 4 +.IX Item "show_hidden [bool] <zh>, <^H>" +Show hidden files? +.IP "sort_case_insensitive [bool] <zc>" 4 +.IX Item "sort_case_insensitive [bool] <zc>" +Sort case-insensitively? If true, \*(L"a\*(R" will be listed before \*(L"B\*(R" even though +its \s-1ASCII\s0 value is higher. +.IP "sort_directories_first [bool] <zd>" 4 +.IX Item "sort_directories_first [bool] <zd>" +Sort directories first? +.IP "sort_reverse [bool] <or>" 4 +.IX Item "sort_reverse [bool] <or>" +Sort reversed? +.IP "sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>" 4 +.IX Item "sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>" +Which sorting mechanism should be used? Choose one of \fBatime\fR, \fBbasename\fR, +\&\fBctime\fR, \fBmtime\fR, \fBnatural\fR, \fBtype\fR, \fBsize\fR +.Sp +Note: You can reverse the order by using an uppercase O in the key combination. +.IP "tilde_in_titlebar [bool]" 4 +.IX Item "tilde_in_titlebar [bool]" +Abbreviate \f(CW$HOME\fR with ~ in the title bar (first line) of ranger? +.IP "unicode_ellipsis [bool]" 4 +.IX Item "unicode_ellipsis [bool]" +Use a unicode \*(L"...\*(R" character instead of \*(L"~\*(R" to mark cut-off filenames? +.IP "update_title [bool]" 4 +.IX Item "update_title [bool]" +Set a window title? +.IP "use_preview_script [bool] <zv>" 4 +.IX Item "use_preview_script [bool] <zv>" +Use the preview script defined in the setting \fIpreview_script\fR? +.IP "xterm_alt_key [bool]" 4 +.IX Item "xterm_alt_key [bool]" +Enable this if key combinations with the Alt Key don't work for you. +(Especially on xterm) +.SH "COMMANDS" +.IX Header "COMMANDS" +.IP "bulkrename" 2 +.IX Item "bulkrename" +This command opens a list of selected files in an external editor. After you +edit and save the file, it will generate a shell script which does bulk +renaming according to the changes you did in the file. +.Sp +This shell script is opened in an editor for you to review. After you close +it, it will be executed. +.IP "cd [\fIdirectory\fR]" 2 +.IX Item "cd [directory]" +The cd command changes the directory. The command \f(CW\*(C`:cd \-\*(C'\fR is equivalent to +typing ``. +.IP "chmod \fIoctal_number\fR" 2 +.IX Item "chmod octal_number" +Sets the permissions of the selection to the octal number. +.Sp +The octal number is between 000 and 777. The digits specify the permissions for +the user, the group and others. A 1 permits execution, a 2 permits writing, a +4 permits reading. Add those numbers to combine them. So a 7 permits +everything. +.Sp +Key bindings in the form of [\-+]<who><what> and =<octal> also exist. For +example, \fB+ar\fR allows reading for everyone, \-ow forbids others to write and +=777 allows everything. +.Sp +See also: man 1 chmod +.IP "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 \fI~/.config/ranger/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. -.TP -:quit -Quit ranger. The current directory will be bookmarked as ' so you can -re-enter it by typing `` or '' the next time you start ranger. -.\"----------------------------------------- -.SH TIPS -.SS -Change the directory after exit -A script like this in your bashrc would make you change the directory -of your parent shell after exiting ranger: -.nf - -ranger() { - command ranger --fail-unless-cd $@ && - cd "$(grep \\^\\' ~/.config/ranger/bookmarks | cut -b3-)" -} -.\"----------------------------------------- -.SH CONFIGURATION -The files in -.B ranger/defaults/ -can be copied into your configuration directory (by default, this is -~/.config/ranger) and customized according to your wishes. -Most files don't have to be copied completely though: Just define those -settings you want to add or change and they will override the defauls. -Colorschemes can be placed in ~/.config/ranger/colorschemes. -.P -All configuration is done in Python. -Each configuration file should contain sufficient documentation. -.\"----------------------------------------- -.SH COPYRIGHT -Copyright \(co -2009, 2010 -Roman Zimbelmann -.P -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -There is NO warranty; -not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -.\"----------------------------------------- -.SH SEE ALSO -The project page: -.RB < http://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 > +.IP "save_copy_buffer" 2 +.IX Item "save_copy_buffer" +Save the copy buffer from \fI~/.config/ranger/copy_buffer\fR. This can be used to +pass the list of copied files to another ranger instance. +.IP "search \fIpattern\fR" 2 +.IX Item "search pattern" +Search files in the current directory that match the given (case insensitive) +regular expression pattern. +.IP "search_inc \fIpattern\fR" 2 +.IX Item "search_inc pattern" +Search files in the current directory that match the given (case insensitive) +regular expression pattern. This command gets you to matching files as you +type. +.IP "set \fIoption\fR=\fIvalue\fR" 2 +.IX Item "set option=value" +Assigns a new value to an option. Valid options are listed in the settings +section. Use tab completion to get the current value of an option, though this +doesn't work for functions and regular expressions. Valid values are: +.Sp +.Vb 8 +\& None None +\& bool True or False +\& integer 0 or 1 or \-1 or 2 etc. +\& list [1, 2, 3] +\& tuple 1, 2, 3 or (1, 2, 3) +\& function lambda <arguments>: <expression> +\& regexp regexp(\*(Aq<pattern>\*(Aq) +\& string Anything +.Ve +.IP "shell [\-\fIflags\fR] \fIcommand\fR" 2 +.IX Item "shell [-flags] command" +Run a shell command. \fIflags\fR are discussed in their own section. +.IP "terminal" 2 +.IX Item "terminal" +Spawns the \fIx\-terminal-emulator\fR starting in the current directory. +.IP "touch \fIfilename\fR" 2 +.IX Item "touch filename" +Creates an empty file with the name \fIfilename\fR, unless it already exists. +.IP "unmark \fIpattern\fR" 2 +.IX Item "unmark pattern" +Unmark all files matching a regular expression pattern. +.SH "FILES" +.IX Header "FILES" +ranger reads several configuration files which are located in +\&\fI\f(CI$HOME\fI/.config/ranger\fR or \fI\f(CI$XDG_CONFIG_HOME\fI/ranger\fR if \f(CW$XDG_CONFIG_HOME\fR is +defined. The configuration is done mostly in python. When removing a +configuration file, remove its compiled version too. (Python automatically +compiles modules. Since python3 they are saved in the _\|_pycache_\|_ directory, +earlier versions store them with the .pyc extension in the same directory.) +.PP +Use the \-\-copy\-config option to obtain the default configuration files. They +include further documentation and it's too much to put here. +.PP +You don't need to copy the whole file though, most configuration files are +overlaid on top of the defaults (\fIoptions.py\fR, \fIcommand.py\fR, \fIkeys.py\fR) or +can be sub-classed (\fIapps.py\fR, \fIcolorschemes\fR). +.PP +When starting ranger with the \fB\-\-clean\fR option, it will not access or create +any of these files. +.SS "\s-1CONFIGURATION\s0" +.IX Subsection "CONFIGURATION" +.IP "apps.py" 10 +.IX Item "apps.py" +Controls which applications are used to open files. +.IP "commands.py" 10 +.IX Item "commands.py" +Defines commands which can be used by typing \*(L":\*(R". +.IP "keys.py" 10 +.IX Item "keys.py" +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. +.IP "colorschemes/" 10 +.IX Item "colorschemes/" +Colorschemes can be placed here. +.SS "\s-1STORAGE\s0" +.IX Subsection "STORAGE" +.IP "bookmarks" 10 +.IX Item "bookmarks" +This file contains a list of bookmarks. The syntax is /^(.):(.*)$/. The first +character is the bookmark key and the rest after the colon is the path to the +file. In ranger, bookmarks can be set by typing m<key>, accessed by typing +\&'<key> and deleted by typing um<key>. +.IP "copy_buffer" 10 +.IX Item "copy_buffer" +When running the command :save_copy_buffer, the paths of all currently copied +files are saved in this file. You can later run :load_copy_buffer to copy the +same files again, pass them to another ranger instance or process them in a +script. +.IP "history" 10 +.IX Item "history" +Contains a list of commands that have been previously typed in. +.IP "tagged" 10 +.IX Item "tagged" +Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first +letter is the optional name of the tag and the rest after the optional colon is +the path to the file. In ranger, tags can be set by pressing t and removed +with T. To assign a named tag, type "<tagname>. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +These environment variables have an effect on ranger: +.IP "\s-1EDITOR\s0" 8 +.IX Item "EDITOR" +Defines the editor to be used for the \*(L"E\*(R" key. Defaults to the first installed +program out of \*(L"vim\*(R", \*(L"emacs\*(R" and \*(L"nano\*(R". +.IP "\s-1SHELL\s0" 8 +.IX Item "SHELL" +Defines the shell that ranger is going to use with the :shell command and +the \*(L"S\*(R" key. Defaults to \*(L"bash\*(R". +.IP "\s-1XDG_CONFIG_HOME\s0" 8 +.IX Item "XDG_CONFIG_HOME" +Specifies the directory for configuration files. Defaults to \fI\f(CI$HOME\fI/.config\fR. +.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 \fI~/.bashrc\fR) to change the directory +to the last visited one after ranger quits. You can always type \f(CW\*(C`cd \-\*(C'\fR to go +back to the original one. +.PP +.Vb 9 +\& function ranger\-cd { +\& tempfile=/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 "LICENSE" +.IX Header "LICENSE" +\&\s-1GNU\s0 General Public License 3 or (at your option) any later version. +.SH "LINKS" +.IX Header "LINKS" +.IP "Download: <http://ranger.nongnu.org/ranger\-stable.tar.gz>" 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 +.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 bugs here: <http://savannah.nongnu.org/bugs/?group=ranger> +.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 new file mode 100644 index 00000000..8f6cc62a --- /dev/null +++ b/doc/ranger.pod @@ -0,0 +1,832 @@ +=head1 NAME + +ranger - visual file manager + + + + +=head1 SYNOPSIS + +B<ranger> [I<options>] [I<path/filename>] + + + + +=head1 DESCRIPTION + +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 +key bindings are similar to those of other console programs like B<vim>, +B<mutt> or B<ncmpcpp> 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 error occurs, ranger will exit and print a +full traceback. The default behavior is to merely print the name of the +exception in the statusbar/log and try to keep running. + +=item B<-c>, B<--clean> + +Activate the clean mode: Ranger will not access or create any configuration +files nor will it leave any traces on your system. This is useful when your +configuration is broken, when you want to avoid clutter, etc. + +=item B<--choosefile>=I<targetfile> + +Allows you to pick a file with ranger. This changes the behavior so that when +you open a file, ranger will exit and write the name of that file into +I<targetfile>. + +=item B<--choosedir>=I<targetfile> + +Allows you to pick a directory with ranger. When you exit ranger, it will +write the last visited directory into I<targetfile>. + +=item B<--copy-config>=I<file> + +Create copies of the default configuration files in your local configuration +directory. Existing ones will not be overwritten. Possible values: I<all>, +I<apps>, I<commands>, I<keys>, I<options>, I<scope>. + +=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<n>, B<--mode>=I<n> + +When a filename is supplied, run it in mode I<n>. This has no effect unless +the execution of this file type is explicitly handled in the configuration. + +=item B<-f> I<flags>, B<--flags>=I<flags> + +When a filename is supplied, run it with the given I<flags> to modify +behavior. The execution of this file type is explicitly handled in the +configuration. + +=back + + + + +=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<SpaceE<gt>> 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 F<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 + +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<po>. + +=item mI<X> + +Create a bookmark with the name I<X> + +=item `I<X> + +Move to the bookmark with the name I<X> + +=item n, N + +Find the next file. By default, this gets you to the newest file in the +directory, but if you search something using the keys /, cm, ct, ..., it will +get you to the next found entry. + +=item N + +Find the previous file. + +=item oI<X> + +Change the sort method (like in mutt) + +=item zI<X> + +Change settings. See the settings section for a list of settings and their +hotkey. + +=item f + +Quickly navigate by entering a part of the filename. + +=item Space + +Mark a file. + +=item v + +Toggle the mark-status of all files, unmark all files. + +=item V, uv + +Unmark all files + +=item ^VI<direction> + +Mark all files in the given direction. Works just like dI<direction>. + +=item u^VI<direction> + +Unmark all files in the given direction. Works just like dI<direction>. + +=item gI<N> + +Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it +will be created. + +=item gn, ^N + +Create a new tab. + +=item gt, gT + +Go to the next or previous tab. You can also use TAB and SHIFT+TAB instead. + +=item gc, ^W + +Close the current tab. The last tab cannot be closed this way. + +=item / + +Search for files in the current directory. + +=item : + +Open the console. + +=item ? + +Opens the help screen with more key bindings and documentation + +=back + +=head2 MIDNIGHT COMMANDER-LIKE BINDINGS + +=over 14 + +=item <F1> + +Display Help. + +=item <F3> + +Display the file. + +=item <F4> + +Edit the file. + +=item <F5> + +Copy the file. + +=item <F6> + +Cut the file. + +=item <F7> + +Open the console with ":mkdir ". + +=item <F8> + +Prompt for deletion of the selected files. + +=item <F10> + +Exit ranger. + +=back + +=head2 READLINE-LIKE BINDINGS IN THE CONSOLE + +=over 14 + +=item ^B, ^F + +Move left and right (B for back, F for forward) + +=item ^P, ^N + +Move up and down (P for previous, N for Next) + +=item ^A, ^E + +Move to the start or to the end + +=item ^D + +Delete the current character. + +=item ^H + +Backspace. + +=back + + +=head1 MOUSE BUTTONS + +=over + +=item Left Mouse Button + +Click on something and you'll move there. To run a file, "enter" it, like a +directory, by clicking on the preview. + +=item Right Mouse Button + +Enter a directory or run a file. + +=item Scroll Wheel + +Scrolls up or down. You can point at the column of the parent directory to +switch directories. + +=back + + + + +=head1 SETTINGS + +This section lists all built-in settings of ranger. The valid types for the +value are in [brackets]. The hotkey to toggle the setting is in <brokets>, if +a hotkey exists. + +Settings can be changed in the file F<~/.config/ranger/options.py> or on the +fly with the command B<:set option value>. Examples: + :set column_ratios (1,2,3) + :set show_hidden=True + +=over + +=item autosave_bookmarks [bool] + +Save bookmarks (used with mX and `X) instantly? This helps to synchronize +bookmarks between multiple ranger instances but leads to *slight* performance +loss. When false, bookmarks are saved when ranger is exited. + +=item collapse_preview [bool] <zc> + +When no preview is visible, should the last column be squeezed to make use of +the whitespace? + +=item colorscheme_overlay [function, None] + +An overlay function for colorschemes. See the default options.py for an +explanation and an example. + +=item colorscheme [string] + +Which colorscheme to use? These colorschemes are available by default: +B<default>, B<default88>, B<texas>, B<jungle>, B<snow>. Snow is monochrome, +texas and default88 use 88 colors. + +=item column_ratios [tuple, list] + +How many columns are there, and what are their relative widths? For example, a +value of (1, 1, 1) would mean 3 even sized columns. (1, 1, 1, 1, 4) means 5 columns +with the preview column being as large as the other columns combined. + +=item dirname_in_tabs [bool] + +Display the directory name in tabs? + +=item display_size_in_main_column [bool] + +Display the file size in the main column? + +=item display_size_in_status_bar [bool] + +Display the file size in the status bar? + +=item display_tags_in_all_columns [bool] + +Display tags in all columns? + +=item draw_bookmark_borders [bool] + +Draw borders around the bookmark window? + +=item draw_borders [bool] + +Draw borders around columns? + +=item flushinput [bool] <zi> + +Flush the input after each key hit? One advantage is that when scrolling down +with "j", ranger stops scrolling instantly when you release the key. One +disadvantage is that when you type commands blindly, some keys might get lost. + +=item hidden_filter [regexp] + +A regular expression pattern for files which should be hidden. + +=item max_console_history_size [integer, None] + +How many console commands should be kept in history? + +=item max_history_size [integer, None] + +How many directory changes should be kept in history? + +=item mouse_enabled [bool] <zm> + +Enable mouse input? + +=item padding_right [bool] + +When collapse_preview is on and there is no preview, should there remain a +little padding on the right? This allows you to click into that space to run +the file. + +=item preview_directories [bool] <zP> + +Preview directories in the preview column? + +=item preview_files [bool] <zp> + +Preview files in the preview column? + +=item preview_script [string, None] + +Which script should handle generating previews? If the file doesn't exist, or +use_preview_script is off, ranger will handle previews itself by just printing +the content. + +=item save_console_history [bool] + +Should the console history be saved on exit? If disabled, the console history +is reset when you restart ranger. + +=item scroll_offset [integer] + +Try to keep this much space between the top/bottom border when scrolling. + +=item shorten_title [integer, bool] + +Trim the title of the window if it gets long? The number defines how many +directories are displayed at once, False turns off this feature. + +=item show_cursor [bool] + +Always show the terminal cursor? + +=item show_hidden_bookmarks [bool] + +Show dotfiles in the bookmark preview window? (Type ') + +=item show_hidden [bool] <zh>, <^H> + +Show hidden files? + +=item sort_case_insensitive [bool] <zc> + +Sort case-insensitively? If true, "a" will be listed before "B" even though +its ASCII value is higher. + +=item sort_directories_first [bool] <zd> + +Sort directories first? + +=item sort_reverse [bool] <or> + +Sort reversed? + +=item sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os> + +Which sorting mechanism should be used? Choose one of B<atime>, B<basename>, +B<ctime>, B<mtime>, B<natural>, B<type>, B<size> + +Note: You can reverse the order by using an uppercase O in the key combination. + +=item tilde_in_titlebar [bool] + +Abbreviate $HOME with ~ in the title bar (first line) of ranger? + +=item unicode_ellipsis [bool] + +Use a unicode "..." character instead of "~" to mark cut-off filenames? + +=item update_title [bool] + +Set a window title? + +=item use_preview_script [bool] <zv> + +Use the preview script defined in the setting I<preview_script>? + +=item xterm_alt_key [bool] + +Enable this if key combinations with the Alt Key don't work for you. +(Especially on xterm) + +=back + + +=head1 COMMANDS + +=over 2 + +=item bulkrename + +This command opens a list of selected files in an external editor. After you +edit and save the file, it will generate a shell script which does bulk +renaming according to the changes you did in the file. + +This shell script is opened in an editor for you to review. After you close +it, it will be executed. + +=item cd [I<directory>] + +The cd command changes the directory. The command C<:cd -> is equivalent to +typing ``. + +=item chmod I<octal_number> + +Sets the permissions of the selection to the octal number. + +The octal number is between 000 and 777. The digits specify the permissions for +the user, the group and others. A 1 permits execution, a 2 permits writing, a +4 permits reading. Add those numbers to combine them. So a 7 permits +everything. + +Key bindings in the form of [-+]<who><what> and =<octal> also exist. For +example, B<+ar> allows reading for everyone, -ow forbids others to write and +=777 allows everything. + +See also: man 1 chmod + +=item delete [I<confirmation>] + +Destroy all files in the selection with a roundhouse kick. Ranger will ask for +a confirmation if you attempt to delete multiple (marked) files or non-empty +directories. + +When asking for confirmation, this command will only proceed if the last given +word starts with a `y'. + +=item edit [I<filename>] + +Edit the current file or the file in the argument. + +=item eval I<python_code> + +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<string>] + +Displays only the files which contain the I<string> in their basename. + +=item find I<pattern> + +Search files in the current directory that match the given (case-insensitive) +regular expression pattern as you type. Once there is an unambiguous result, +it will be run immediately. (Or entered, if it's a directory.) + +=item grep I<pattern> + +Looks for a string in all marked files or directories. + +=item load_copy_buffer + +Load the copy buffer from F<~/.config/ranger/copy_buffer>. This can be used to +pass the list of copied files to another ranger instance. + +=item mark I<pattern> + +Mark all files matching the regular expression pattern. + +=item mkdir I<dirname> + +Creates a directory with the name I<dirname>. + +=item open_with [I<application>] [I<flags>] [I<mode>] + +Open the selected files with the given application, unless it is omitted, in +which case the default application is used. I<flags> are characters out of +"sdpcwSDPCW" and I<mode> is any positive integer. Their meanings are discussed +in their own sections. + +=item quit + +Like quit!, but closes only this tab if multiple tabs are open. + +=item quit! + +Quit ranger. The current directory will be bookmarked as ' so you can re-enter +it by typing `` or '' the next time you start ranger. + +=item rename I<newname> + +Rename the current file. If a file with that name already exists, it will be +overwritten without notice. Also try the key binding A for appending something +to a file name. + +=item save_copy_buffer + +Save the copy buffer from I<~/.config/ranger/copy_buffer>. This can be used to +pass the list of copied files to another ranger instance. + +=item search I<pattern> + +Search files in the current directory that match the given (case insensitive) +regular expression pattern. + +=item search_inc I<pattern> + +Search files in the current directory that match the given (case insensitive) +regular expression pattern. This command gets you to matching files as you +type. + +=item set I<option>=I<value> + +Assigns a new value to an option. Valid options are listed in the settings +section. Use tab completion to get the current value of an option, though this +doesn't work for functions and regular expressions. Valid values are: + + None None + bool True or False + integer 0 or 1 or -1 or 2 etc. + list [1, 2, 3] + tuple 1, 2, 3 or (1, 2, 3) + function lambda <arguments>: <expression> + regexp regexp('<pattern>') + string Anything + +=item shell [-I<flags>] I<command> + +Run a shell command. I<flags> are discussed in their own section. + +=item terminal + +Spawns the I<x-terminal-emulator> starting in the current directory. + +=item touch I<filename> + +Creates an empty file with the name I<filename>, unless it already exists. + +=item unmark I<pattern> + +Unmark all files matching a regular expression pattern. + +=back + + + + +=head1 FILES + +ranger reads several configuration files which are located in +F<$HOME/.config/ranger> or F<$XDG_CONFIG_HOME/ranger> if $XDG_CONFIG_HOME is +defined. The configuration is done mostly in python. When removing a +configuration file, remove its compiled version too. (Python automatically +compiles modules. Since python3 they are saved in the __pycache__ directory, +earlier versions store them with the .pyc extension in the same directory.) + +Use the --copy-config option to obtain the default configuration files. They +include further documentation and it's too much to put here. + +You don't need to copy the whole file though, most configuration files are +overlaid on top of the defaults (F<options.py>, F<command.py>, F<keys.py>) or +can be sub-classed (F<apps.py>, F<colorschemes>). + +When starting ranger with the B<--clean> option, it will not access or create +any of these files. + +=head2 CONFIGURATION + +=over 10 + +=item apps.py + +Controls which applications are used to open files. + +=item commands.py + +Defines commands which can be used by typing ":". + +=item keys.py + +Defines key bindings. + +=item options.py + +Sets a handful of basic options. + +=item scope.sh + +This is a script that handles file previews. When the options +I<use_preview_script> and I<preview_files> or, respectively, +I<preview_directories> are set, the program specified in the option +I<preview_script> is run and its output and/or exit code determines rangers +reaction. + +=item colorschemes/ + +Colorschemes can be placed here. + +=back + +=head2 STORAGE + +=over 10 + +=item bookmarks + +This file contains a list of bookmarks. The syntax is /^(.):(.*)$/. The first +character is the bookmark key and the rest after the colon is the path to the +file. In ranger, bookmarks can be set by typing m<key>, accessed by typing +'<key> and deleted by typing um<key>. + +=item copy_buffer + +When running the command :save_copy_buffer, the paths of all currently copied +files are saved in this file. You can later run :load_copy_buffer to copy the +same files again, pass them to another ranger instance or process them in a +script. + +=item history + +Contains a list of commands that have been previously typed in. + +=item tagged + +Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first +letter is the optional name of the tag and the rest after the optional colon is +the path to the file. In ranger, tags can be set by pressing t and removed +with T. To assign a named tag, type "<tagname>. + +=back + + + + +=head1 ENVIRONMENT + +These environment variables have an effect on ranger: + +=over 8 + +=item EDITOR + +Defines the editor to be used for the "E" key. Defaults to the first installed +program out of "vim", "emacs" and "nano". + +=item SHELL + +Defines the shell that ranger is going to use with the :shell command and +the "S" key. Defaults to "bash". + +=item XDG_CONFIG_HOME + +Specifies the directory for configuration files. Defaults to F<$HOME/.config>. + +=back + + + + +=head1 EXAMPLES + +=head2 VIM: File Chooser + +This is a vim function which allows you to use ranger to select a file for +opening in your current vim session. + + fun! RangerChooser() + silent !ranger --choosefile=/tmp/chosenfile `[ -z '%' ] && echo -n . || dirname %` + if filereadable('/tmp/chosenfile') + exec 'edit ' . system('cat /tmp/chosenfile') + call system('rm /tmp/chosenfile') + endif + redraw! + endfun + map ,r :call RangerChooser()<CR> + +=head2 Bash: cd to last path after exit + +This is a bash function (to put in your F<~/.bashrc>) to change the directory +to the last visited one after ranger quits. You can always type C<cd -> to go +back to the original one. + + function ranger-cd { + tempfile=/tmp/chosendir + /usr/bin/ranger --choosedir=$tempfile "$@" + if [ -f $tempfile -a "$(cat $tempfile)" != "$(pwd | tr -d "\n")" ] + then + cd "$(cat $tempfile)" + rm $tempfile + fi + } + + + + +=head1 LICENSE + +GNU General Public License 3 or (at your option) any later version. + + + + +=head1 LINKS + +=over + +=item Download: L<http://ranger.nongnu.org/ranger-stable.tar.gz> + +=item The project page: L<http://ranger.nongnu.org/> + +=item The mailing list: L<http://savannah.nongnu.org/mail/?group=ranger> + +=back + +ranger is maintained with the git version control system. To fetch a fresh +copy, run: + + git clone git://git.savannah.nongnu.org/ranger.git + + + + +=head1 BUGS + +Please report bugs here: L<http://savannah.nongnu.org/bugs/?group=ranger> + +In many cases, ranger prints more diagnostics information when you run it with +the B<--debug> option. Please include as much relevant information as possible. + diff --git a/ranger/container/settingobject.py b/ranger/container/settingobject.py index d036245f..6b6fbae7 100644 --- a/ranger/container/settingobject.py +++ b/ranger/container/settingobject.py @@ -22,7 +22,7 @@ ALLOWED_SETTINGS = { 'collapse_preview': bool, 'colorscheme_overlay': (type(None), type(lambda:0)), 'colorscheme': str, - 'column_ratios': (tuple, list, set), + 'column_ratios': (tuple, list), 'dirname_in_tabs': bool, 'display_size_in_main_column': bool, 'display_size_in_status_bar': bool, diff --git a/ranger/core/actions.py b/ranger/core/actions.py index 96a2ad38..328d4365 100644 --- a/ranger/core/actions.py +++ b/ranger/core/actions.py @@ -163,7 +163,18 @@ class Actions(FileManagerAware, EnvironmentAware, SettingsAware): elif type(files) not in (list, tuple): files = [files] - return self.run(files=list(files), **kw) + if 'flags' in kw: + from ranger.core.runner import Context + context = Context(files=list(files), flags=kw['flags']) + context.squash_flags() + if 'c' in context.flags: + files = [self.fm.env.cf] + + self.signal_emit('execute.before', keywords=kw) + try: + return self.run(files=list(files), **kw) + finally: + self.signal_emit('execute.after') # -------------------------- # -- Moving Around @@ -403,7 +414,7 @@ class Actions(FileManagerAware, EnvironmentAware, SettingsAware): return self.env.cwd.search_fnc(fnc=fnc, offset=offset, forward=forward) - elif order in ('size', 'mimetype', 'ctime'): + elif order in ('size', 'mimetype', 'ctime', 'mtime', 'atime'): cwd = self.env.cwd if original_order is not None or not cwd.cycle_list: lst = list(cwd.files) diff --git a/ranger/core/helper.py b/ranger/core/helper.py index cb0afefe..ad5541f5 100644 --- a/ranger/core/helper.py +++ b/ranger/core/helper.py @@ -15,6 +15,7 @@ """Helper functions""" +from errno import EEXIST import os.path import sys from ranger import * @@ -150,7 +151,7 @@ def allow_access_to_confdir(confdir, allow): try: os.makedirs(confdir) except OSError as err: - if err.errno != 17: # 17 means it already exists + if err.errno != EEXIST: # EEXIST means it already exists print("This configuration directory could not be created:") print(confdir) print("To run ranger without the need for configuration") diff --git a/ranger/core/runner.py b/ranger/core/runner.py index dd0cf06a..53bede29 100644 --- a/ranger/core/runner.py +++ b/ranger/core/runner.py @@ -37,7 +37,7 @@ from subprocess import Popen, PIPE from ranger.ext.waitpid_no_intr import waitpid_no_intr -ALLOWED_FLAGS = 'sdpwSDPW' +ALLOWED_FLAGS = 'sdpwcSDPWC' def press_enter(): diff --git a/ranger/defaults/commands.py b/ranger/defaults/commands.py index 319c5cef..a96c842c 100644 --- a/ranger/defaults/commands.py +++ b/ranger/defaults/commands.py @@ -356,6 +356,7 @@ class set_(Command): name = line.chunk(1) name, value, _ = line.parse_setting_line() if name and value: + from re import compile as regexp try: value = eval(value) except: @@ -502,9 +503,11 @@ class load_copy_buffer(Command): from ranger.fsobject import File from os.path import exists try: - f = open(self.fm.confpath(self.copy_buffer_filename), 'r') + fname = self.fm.confpath(self.copy_buffer_filename) + f = open(fname, 'r') except: - return self.fm.notify("Cannot open file %s" % fname, bad=True) + return self.fm.notify("Cannot open %s" % \ + (fname or self.copy_buffer_filename), bad=True) self.fm.env.copy = set(File(g) \ for g in f.read().split("\n") if exists(g)) f.close() @@ -519,10 +522,13 @@ class save_copy_buffer(Command): """ copy_buffer_filename = 'copy_buffer' def execute(self): + fname = None try: - f = open(self.fm.confpath(self.copy_buffer_filename), 'w') + fname = self.fm.confpath(self.copy_buffer_filename) + f = open(fname, 'w') except: - return self.fm.notify("Cannot open file %s" % fname, bad=True) + return self.fm.notify("Cannot open %s" % \ + (fname or self.copy_buffer_filename), bad=True) f.write("\n".join(f.path for f in self.fm.env.copy)) f.close() @@ -692,6 +698,60 @@ class chmod(Command): pass +class bulkrename(Command): + """ + :bulkrename + + This command opens a list of selected files in an external editor. + After you edit and save the file, it will generate a shell script + which does bulk renaming according to the changes you did in the file. + + This shell script is opened in an editor for you to review. + After you close it, it will be executed. + """ + def execute(self): + import sys + import tempfile + from ranger.fsobject.file import File + from ranger.ext.shell_escape import shell_escape as esc + py3 = sys.version > "3" + + # Create and edit the file list + filenames = [f.basename for f in self.fm.env.get_selection()] + listfile = tempfile.NamedTemporaryFile() + + if py3: + listfile.write("\n".join(filenames).encode("utf-8")) + else: + listfile.write("\n".join(filenames)) + listfile.flush() + self.fm.execute_file([File(listfile.name)], app='editor') + listfile.seek(0) + if py3: + new_filenames = listfile.read().decode("utf-8").split("\n") + else: + new_filenames = listfile.read().split("\n") + listfile.close() + if all(a == b for a, b in zip(filenames, new_filenames)): + self.fm.notify("No renaming to be done!") + return + + # Generate and execute script + cmdfile = tempfile.NamedTemporaryFile() + cmdfile.write(b"# This file will be executed when you close the editor.\n") + cmdfile.write(b"# Please double-check everything, clear the file to abort.\n") + if py3: + cmdfile.write("\n".join("mv -vi " + esc(old) + " " + esc(new) \ + for old, new in zip(filenames, new_filenames) if old != new).encode("utf-8")) + else: + cmdfile.write("\n".join("mv -vi " + esc(old) + " " + esc(new) \ + for old, new in zip(filenames, new_filenames) if old != new)) + cmdfile.flush() + self.fm.run(['vim', cmdfile.name]) + self.fm.run(['/bin/sh', cmdfile.name], flags='w') + cmdfile.close() + + class filter(Command): """ :filter <string> diff --git a/ranger/defaults/keys.py b/ranger/defaults/keys.py index cd1c5d07..e8acebb7 100644 --- a/ranger/defaults/keys.py +++ b/ranger/defaults/keys.py @@ -193,6 +193,27 @@ map('phl', fm.paste_hardlink()) map('u<bg>', fm.hint("un*y*ank, unbook*m*ark, unselect:*v*")) map('ud', 'uy', fm.uncut()) +# ------------------------------------ changing of file permissions +# type "+ow" for "chmod o+w %s" and so on +from itertools import product +octal_help = 'Enter the octal mode number for chmod' +symbolic_help = '%s %s to *r*ead, *w*rite, e*x*ecute' +for mode in product('ugoa', 'rwxXst'): + map('-%s%s' % mode, fm.execute_console('shell chmod %s-%s %%s' % mode)) + map('+%s%s' % mode, fm.execute_console('shell chmod %s+%s %%s' % mode)) +for n in product(range(8), range(8), range(8)): + map('=%d%d%d' % n, fm.execute_console('shell chmod %d%d%d %%s' % n)) + map('=%d<bg>' % n[0], fm.hint(octal_help)) + map('=%d%d<bg>' % (n[0], n[1]), fm.hint(octal_help)) + +# hints: +for who, name in zip('ugoa', ('user', 'group', 'others', 'all')): + map('-%s<bg>' % who, fm.hint(symbolic_help % ('forbid', name))) + map('+%s<bg>' % who, fm.hint(symbolic_help % ('allow', name))) +map('-<bg>', '+<bg>', '=<bg>', fm.hint('change permission for *u*ser, ' + '*g*roup, *o*thers, *a*ll')) +map('=<bg>', fm.hint(octal_help)) + # ---------------------------------------------------- run programs map('S', fm.execute_command(os.environ['SHELL'])) map('E', fm.edit_file()) @@ -215,13 +236,14 @@ map('zf', fm.open_console('filter ')) # ------------------------------------------------------------ sort map('o<bg>', 'O<bg>', fm.hint('*sort by:* *s*ize *b*asename *m*time' \ - ' *t*ype *r*everse *n*atural')) + ' *c*time *a*time *t*ype *r*everse *n*atural')) sort_dict = { 's': 'size', 'b': 'basename', 'n': 'natural', 'm': 'mtime', 'c': 'ctime', + 'a': 'atime', 't': 'type', } diff --git a/ranger/fsobject/directory.py b/ranger/fsobject/directory.py index e0623e23..6d34b02d 100644 --- a/ranger/fsobject/directory.py +++ b/ranger/fsobject/directory.py @@ -88,6 +88,7 @@ class Directory(FileSystemObject, Accumulator, Loadable, SettingsAware): 'size': lambda path: -path.size, 'mtime': lambda path: -(path.stat and path.stat.st_mtime or 1), 'ctime': lambda path: -(path.stat and path.stat.st_ctime or 1), + 'atime': lambda path: -(path.stat and path.stat.st_atime or 1), 'type': lambda path: path.mimetype or '', } diff --git a/ranger/gui/widgets/console.py b/ranger/gui/widgets/console.py index a575405d..00d6828b 100644 --- a/ranger/gui/widgets/console.py +++ b/ranger/gui/widgets/console.py @@ -125,7 +125,7 @@ class Console(Widget): def close(self, trigger_cancel_function=True): if trigger_cancel_function: - cmd = self._get_cmd() + cmd = self._get_cmd(quiet=True) if cmd: try: cmd.cancel() @@ -324,11 +324,12 @@ class Console(Widget): if self.allow_close: self.close(trigger_cancel_function=False) - def _get_cmd(self): + def _get_cmd(self, quiet=False): try: command_class = self._get_cmd_class() except KeyError: - self.fm.notify("Invalid command! Press ? for help.", bad=True) + if not quiet: + self.fm.notify("Invalid command! Press ? for help.", bad=True) except: return None else: diff --git a/ranger/gui/widgets/pager.py b/ranger/gui/widgets/pager.py index 05485189..d1bf5918 100644 --- a/ranger/gui/widgets/pager.py +++ b/ranger/gui/widgets/pager.py @@ -111,12 +111,16 @@ class Pager(Widget): if TITLE_REGEXP.match(line): self.color_at(i, 0, -1, 'title', *baseclr) elif self.markup == 'ansi': - self.win.move(i, 0) - for chunk in ansi.text_with_fg_bg_attr(line): - if isinstance(chunk, tuple): - self.set_fg_bg_attr(*chunk) - else: - self.addstr(chunk) + try: + self.win.move(i, 0) + except: + pass + else: + for chunk in ansi.text_with_fg_bg_attr(line): + if isinstance(chunk, tuple): + self.set_fg_bg_attr(*chunk) + else: + self.addstr(chunk) def move(self, narg=None, **kw): direction = Direction(kw) diff --git a/ranger/help/console.py b/ranger/help/console.py index 716740b9..e25b5b5e 100644 --- a/ranger/help/console.py +++ b/ranger/help/console.py @@ -39,6 +39,11 @@ unambiguous name, e.g. ":chmod" can be written as ":ch" but not as ":c" since it conflicts with ":cd". +:bulkrename + This command opens a list of selected files in an external editor. + After you edit and save the file, it will generate a shell script which + does bulk renaming according to the changes you did in the file. + :cd <dirname> Changes the directory to <dirname> @@ -63,7 +68,7 @@ it conflicts with ":cd". :find <regexp> Quickly find files that match the regexp and execute the first - unambiguous match. + unambiguous match. :grep <string> Looks for a string in all marked files or directory. @@ -133,13 +138,13 @@ are in different directories: ============================================================================== 3.4. The more complicated Commands in Detail -3.3.1. "find" +3.4.1. "find" The find command is different than others: it doesn't require you to press <RETURN>. To speed things up, it tries to guess when you're done typing and executes the command right away. The key "f" opens the console with ":find " -3.3.2. "shell" +3.4.2. "shell" The shell command accepts flags |25?| as the first argument. This example will use the "p"-flag, which pipes the output to the pager: :shell -p cat somefile.txt @@ -149,7 +154,7 @@ There are some shortcuts which open the console with the shell command: "@" opens ":shell %s" "#" opens ":shell -p " -3.3.3. "open_with" +3.4.3. "open_with" The open_with command is explained in detail in chapter 2.2. |22?| ============================================================================== diff --git a/ranger/help/starting.py b/ranger/help/starting.py index 1796f83d..dbc6b6b5 100644 --- a/ranger/help/starting.py +++ b/ranger/help/starting.py @@ -103,6 +103,7 @@ Flags give you a way to modify the behaviour of the spawned process. d Detach the process. (Run in background) p Redirect output to the pager w Wait for an enter-press when the process is done + c Run the current file only, even when more files are marked For example, ":open_with p" will pipe the output of that process into the pager. |