diff options
Diffstat (limited to 'doc/ranger.pod')
| -rw-r--r-- | doc/ranger.pod | 414 |
1 files changed, 414 insertions, 0 deletions
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<ranger> [I<options>] [I<path/filename>] + + + + +=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<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 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<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 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 filetype 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 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<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 + +Unmark all files + +=item ^VI<direction> + +Mark 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 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<newname> + +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<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 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()<CR> + +=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<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 LICSENSE + +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 + + + + +=head1 BUGS + +Please report them here and include as much relevant information as possible: +L<http://savannah.nongnu.org/bugs/?group=ranger> |