diff options
Diffstat (limited to 'doc/ranger.pod')
| -rw-r--r-- | doc/ranger.pod | 335 |
1 files changed, 202 insertions, 133 deletions
diff --git a/doc/ranger.pod b/doc/ranger.pod index 2a3a345b..f8ba66b1 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -75,7 +75,7 @@ Open ranger with I<targetfile> selected. Create copies of the default configuration files in your local configuration directory. Existing ones will not be overwritten. Possible values: I<all>, -I<rc>, I<apps>, I<commands>, I<options>, I<scope>. +I<rc>, I<commands>, I<scope>. =item B<--list-unused-keys> @@ -124,6 +124,9 @@ Print a list of options and exit. =head1 CONCEPTS +This part explains how certain parts of ranger work and how they can be used +efficiently. + =head2 TAGS Tags are single characters which are displayed left of a filename. You can use @@ -175,7 +178,7 @@ are in different directories: @diff %c %f Macros for file paths are generally shell-escaped so they can be used in the -:shell command. +C<shell> command. =head2 BOOKMARKS @@ -190,39 +193,75 @@ Bookmarks are selectable when tabbing in the :cd command. Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. +=head2 RIFLE + +Rifle is the file opener of ranger. It can be used as a standalone program or +a python module. It is located at F<ranger/ext/rifle.py>. In contrast to +other, more simple file openers, rifle can automatically find installed +programs so it can be used effectively out of the box on a variety of systems. + +It's configured in F<rifle.conf> through a list of conditions and commands. +For each line the conditions are checked and if they are met, the respective +command is taken into consideration. By default, simply the first matching +rule is used. In ranger, you can list and choose rules by typing "r" or simply +by typing "<rulenumber><enter>". If you use rifle standalone, you can list all +rules with the "-l" option and pick a rule with "-p <number>". + +The rules, along with further documentation, are contained in +F<ranger/config/rifle.conf>. + =head2 FLAGS Flags give you a way to modify the behavior of the spawned process. They are -used in the commands :open_with (key "r") and :shell (key "!"). +used in the commands C<:open_with> (key "r") and C<:shell> (key "!"). - s Silent mode. Output will be discarded. - d Detach the process. (Run in background) - p Redirect output to the pager - w Wait for an Enter-press when the process is done + f Fork the process. (Run in background) c Run the current file only, instead of the selection r Run application with root privilege (requires sudo) t Run application in a new terminal window -By default, all the flags are off unless specified otherwise in the F<apps.py> -configuration file. You can specify as many flags as you want. An uppercase -flag negates the effect: "ddcccDs" is equivalent to "cs". +There are some additional flags that can currently be used only in the C<shell> +command: (for example C<:shell -w df>) + + p Redirect output to the pager + s Silent mode. Output will be discarded. + w Wait for an Enter-press when the process is done + +By default, all the flags are off unless specified otherwise in the +F<rifle.conf> configuration file. You can specify as many flags as you want. +An uppercase flag negates the effect: "ffcccFsf" is equivalent to "cs". + +The terminal program name for the "t" flag is taken from the environment +variable $TERMCMD. If it doesn't exist, it tries to extract it from $TERM and +uses "xterm" as a fallback if that fails. + +Examples: C<:open_with c> will open the file that you currently point at, even +if you have selected other files. C<:shell -w df> will run "df" and wait for +you to press Enter before switching back to ranger. + +=head2 PLUGINS + +ranger's plugin system consists of python files which are located in +F<~/.config/ranger/plugins/> and are imported in alphabetical order when +starting ranger. A plugin changes rangers behavior by overwriting or extending +a function that ranger uses. This allows you to change pretty much every part +of ranger, but there is no guarantee that things will continue to work in +future versions as the source code evolves. -The "t" flag looks for the environment variable TERMCMD, and uses it as the -terminal command, if it's not set it'll use xterm. +There are some hooks that are specifically made for the use in plugins. They +are functions that start with hook_ and can be found throughout the code. -Examples: C<:open_with p> will pipe the output of that process into -the pager. C<:shell -w df> will run "df" and wait for you to press Enter before -switching back to ranger. + grep 'def hook_' -r /path/to/rangers/source -=head2 MODES +Also try: -By specifying a mode (a positive integer), you can tell ranger what to do with -a file when running it. You can specify which mode to use by typing <mode>l or -<mode><Enter> or :open_with <mode>. The default mode is 0. + pydoc ranger.api -Examples: C<l> (mode zero) to list the contents of an archive, C<1l> (mode one) -to extract an archive. See the F<apps.py> configuration file for all programs -and modes. +Note that you should NOT simply overwrite a function unless you know what +you're doing. Instead, save the existing function and call it from your new +one. This way, multiple plugins can use the same hook. There are several +sample plugins in the F<examples/> directory, including a hello-world plugin +that describes this procedure. @@ -443,8 +482,8 @@ 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. +Scrolls up or down. You can point at the column of the parent directory while +scrolling to switch directories. =back @@ -457,10 +496,24 @@ 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 +Settings can be changed in the file F<~/.config/ranger/rc.conf> or on the fly with the command B<:set option value>. Examples: - :set column_ratios (1,2,3) - :set show_hidden=True + + set column_ratios 1,2,3 + set show_hidden true + +The different types of settings and an example for each type: + + setting type | example values + ---------------+---------------------------- + bool | true, false + integer | 1, 23, 1337 + string | foo, hello world + list | 1,2,3,4 + none | none + +You can view a list of all settings and their current values by pressing "3?" +in ranger. =over @@ -470,26 +523,28 @@ 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 autoupdate_cumulative_size [bool] + +You can display the "real" cumulative size of directories by using the command +:get_cumulative_size or typing "dc". The size is expensive to calculate and +will not be updated automatically. You can choose to update it automatically +though by turning on this option. + =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. +B<default>, B<jungle>, B<snow>. Snow is a monochrome scheme, jungle replaces +blue directories with green ones for better visibility on certain terminals. -=item column_ratios [tuple, list] +=item column_ratios [list] How many columns are there, and what are their relative widths? For example, a -value of (1, 1, 1) would mean 3 even sized columns. (1, 1, 1, 1, 4) means 5 columns +value of 1,1,1 would mean 3 evenly sized columns. 1,1,1,1,4 means 5 columns with the preview column being as large as the other columns combined. =item dirname_in_tabs [bool] @@ -508,29 +563,34 @@ Display the file size in the status bar? 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 draw_progress_bar_in_statusbar [bool] + +Draw a progress bar in the status bar which displays the average state of all +currently running tasks which support progress bars? + =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] +=item hidden_filter [string] -A regular expression pattern for files which should be hidden. +A regular expression pattern for files which should be hidden. For example, +this pattern will hide all files that start with a dot or end with a tilde. -=item max_console_history_size [integer, None] + set hidden_filter ^\.|~$ -How many console commands should be kept in history? +=item max_console_history_size [integer, none] -=item max_history_size [integer, None] +How many console commands should be kept in history? "none" will disable the +limit. + +=item max_history_size [integer, none] How many directory changes should be kept in history? @@ -552,7 +612,7 @@ Preview directories in the preview column? Preview files in the preview column? -=item preview_script [string, None] +=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 @@ -595,7 +655,7 @@ Sort directories first? =item sort_reverse [bool] <or> -Sort reversed? +Reverse the order of files? =item sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os> @@ -632,13 +692,63 @@ Enable this if key combinations with the Alt Key don't work for you. You can enter the commands in the console which is opened by pressing ":". +You can always get a list of the currently existing commands by typing "2?" in +ranger. For your convenience, this is a list of the "public" commands including their parameters, excluding descriptions: + + alias [newcommand] [oldcommand] + bulkrename + cd [directory] + chain command1[; command2[; command3...]] + chmod octal_number + cmap key command + console [-pSTARTPOSITION] command + copycmap key newkey [newkey2...] + copymap key newkey [newkey2...] + copypmap key newkey [newkey2...] + copytmap key newkey [newkey2...] + cunmap keys... + delete [confirmation] + edit [filename] + eval [-q] python_code + filter [string] + find pattern + grep pattern + load_copy_buffer + map key command + mark pattern + mkdir dirname + open_with [application] [flags] [mode] + pmap key command + punmap keys... + quit + quit! + relink newpath + rename newname + save_copy_buffer + search pattern + search_inc pattern + set option value + shell [-FLAGS] command + terminal + tmap key command + touch filename + tunmap keys... + unmap keys... + unmark pattern + There are additional commands which are directly translated to python functions, one for every method in the ranger.core.actions.Actions class. They are not documented here, since they are mostly for key bindings, not to be typed in by a user. Read the source if you are interested in them. +These are the public commands including their descriptions: + =over 2 +=item alias [I<newcommand>] [I<oldcommand>] + +Copies the oldcommand as newcommand. + =item bulkrename This command opens a list of selected files in an external editor. After you @@ -655,7 +765,7 @@ typing ``. =item chain I<command1>[; I<command2>[; I<command3>...]] -Combines multiple commands into one, separated by columns. +Combines multiple commands into one, separated by semicolons. =item chmod I<octal_number> @@ -702,7 +812,7 @@ See C<copymap> See C<copymap> -=item cunmap I<key> I<command> +=item cunmap [I<keys...>] Removes key mappings of the console. Works like the C<unmap> command. @@ -732,7 +842,8 @@ Examples: =item filter [I<string>] -Displays only the files which contain the I<string> in their basename. +Displays only the files which contain the I<string> in their basename. Running +this command without any parameter will reset the fitler. =item find I<pattern> @@ -779,7 +890,7 @@ in their own sections. Binds keys for the pager. Works like the C<map> command. -=item punmap I<key> I<command> +=item punmap [I<keys ...>] Removes key mappings of the pager. Works like the C<unmap> command. @@ -792,15 +903,16 @@ Like quit!, but closes only this tab if multiple tabs are open. 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 relink I<newpath> + +Change the link destination of the current symlink file to <newpath>. First +<tab> will load the original link. + =item rename I<newname> Rename the current file. If a file with that name already exists, the renaming will fail. Also try the key binding A for appending something to a file name. -=item relink I<newpath> - -Change the link destination of the current symlink file to <newpath>. First <tab> will load the original link. - =item save_copy_buffer Save the copy buffer from I<~/.config/ranger/copy_buffer>. This can be used to @@ -817,20 +929,19 @@ 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> +=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 + setting type | example values + ---------------+---------------------------- + bool | true, false + integer | 1, 23, 1337 + string | foo, hello world + list | 1,2,3,4 + none | none =item shell [-I<flags>] I<command> @@ -840,15 +951,15 @@ Run a shell command. I<flags> are discussed in their own section. 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 tmap I<key> I<command> Binds keys for the taskview. Works like the C<map> command. -=item tunmap I<key> I<command> +=item touch I<filename> + +Creates an empty file with the name I<filename>, unless it already exists. + +=item tunmap [I<keys ...>] Removes key mappings of the taskview. Works like the C<unmap> command. @@ -870,17 +981,12 @@ Unmark all files matching a regular expression pattern. 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. +defined. You can use the --copy-config option to obtain the default +configuration files. Each of the files contains further documentation. 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<rc.conf>) or -can be sub-classed (F<apps.py>, F<colorschemes>). +overlaid on top of the defaults (F<commands.py>, F<rc.conf>) or can be +sub-classed (F<colorschemes>). When starting ranger with the B<--clean> option, it will not access or create any of these files. @@ -889,35 +995,35 @@ any of these files. =over 10 -=item apps.py +=item rc.conf -Controls which applications are used to open files. +Contains a list of commands which are executed on startup. Mostly key bindings +and settings are defined here. =item commands.py -Defines commands which can be used by typing ":". - -=item rc.conf - -Contains a list of commands which are executed on startup. Mostly key bindings -are defined here. +A python module that defines commands which can be used in ranger's console by +typing ":" or in the rc.conf file. -=item options.py +=item rifle.conf -Sets a handful of basic options. +This is the configuration file for the built-in file launcher called "rifle". =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. +I<use_preview_script> and I<preview_files> 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. +=item plugins/ + +Plugins can be placed here. + =back =head2 STORAGE @@ -962,7 +1068,7 @@ These environment variables have an effect on ranger: =item RANGER_LEVEL -Ranger sets this environment variable to "1" or increments it if it already +ranger sets this environment variable to "1" or increments it if it already exists. External programs can determine whether they were spawned from ranger by checking for this variable. @@ -1004,46 +1110,9 @@ docstrings. Using this will disable the <F1> key on commands. =head1 EXAMPLES -=head2 BASH: Display that the shell spawned from ranger: - -By putting this in ~/.bashrc, "(in ranger) " will be displayed next to your -prompt to notify you that the shell spawned from ranger. - - [ -n "$RANGER_LEVEL" ] && PS1="$PS1"'(in ranger) ' - -=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() - exec "silent !ranger --choosefile=/tmp/chosenfile " . expand("%:p:h") - 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 (for 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" "${@:-$(pwd)}" - test -f "$tempfile" && - if [ "$(cat -- "$tempfile")" != "$(echo -n `pwd`)" ]; then - cd -- "$(cat "$tempfile")" - fi - rm -f -- "$tempfile" - } - - # This binds Ctrl-O to ranger-cd: - bind '"\C-o":"ranger-cd\C-m"' +There are various examples on how to extend ranger with plugins or combine +ranger with other programs. These can be found in the F<examples/> directory +that is provided along with the source code. |