README.md

   1 ranger v.1.6.1
   2 ==============
   3 ranger is a console file manager with VI key bindings.  It provides a
   4 minimalistic and nice curses interface with a view on the directory hierarchy.
   5 It ships with "rifle", a file launcher that is good at automatically finding
   6 out which program to use for what file type.
   7
   8 ![screenshot](doc/screenshot.png)
   9
  10 This file describes ranger and how to get it to run.  For instructions on the
  11 usage, please read the man page.  See doc/HACKING for development specific
  12 information.  For configuration, check the files in ranger/config/.  They
  13 are usually installed to /usr/lib/python*/site-packages/ranger/config/
  14 and can be obtained with ranger's --copy-config option.  The doc/examples/
  15 directory contains several scripts and plugins that demonstrate how ranger can
  16 be extended or combined with other programs.
  17
  18 A note to packagers:  Versions meant for packaging are listed in the changelog
  19 on the website.
  20
  21
  22 About
  23 -----
  24 * Authors:     Check the copyright notices in each source file
  25 * License:     GNU General Public License Version 3
  26 * Website:     http://ranger.nongnu.org/
  27 * Download:    http://ranger.nongnu.org/ranger-stable.tar.gz
  28 * Bug reports: https://github.com/hut/ranger/issues
  29 * git clone    http://git.sv.gnu.org/r/ranger.git
  30
  31
  32 Design Goals
  33 ------------
  34 * An easily maintainable file manager in a high level language
  35 * A quick way to switch directories and browse the file system
  36 * Keep it small but useful, do one thing and do it well
  37 * Console based, with smooth integration into the unix shell
  38
  39
  40 Features
  41 --------
  42 * UTF-8 Support  (if your python copy supports it)
  43 * Multi-column display
  44 * Preview of the selected file/directory
  45 * Common file operations (create/chmod/copy/delete/...)
  46 * Renaming multiple files at once
  47 * VIM-like console and hotkeys
  48 * Automatically determine file types and run them with correct programs
  49 * Change the directory of your shell after exiting ranger
  50 * Tabs, Bookmarks, Mouse support
  51
  52
  53 Dependencies
  54 ------------
  55 * Python (tested with version 2.6, 2.7, 3.1, 3.2) with support for ncurses
  56   and (optionally) wide-unicode.
  57 * A pager ("less" by default)
  58
  59 Optional:
  60 * The "file" program for determining file types
  61 * The python module "chardet", in case of encoding detection problems
  62 * "sudo" to use the "run as root"-feature
  63 * w3m for the "w3mimgdisplay" program to preview images
  64
  65 Optional, for enhanced file previews (with "scope.sh"):
  66 * img2txt (from caca-utils) for ASCII-art image previews
  67 * highlight for syntax highlighting of code
  68 * atool for previews of archives
  69 * lynx, w3m or elinks for previews of html pages
  70 * pdftotext for pdf previews
  71 * transmission-show for viewing bit-torrent information
  72 * mediainfo or exiftool for viewing information about media files
  73
  74
  75 Installing
  76 ----------
  77 Use the package manager of your operating system to install ranger.
  78 Note that ranger can be started without installing by simply running ranger.py.
  79
  80 To install ranger manually:
  81 > sudo make install
  82
  83 This translates roughly to:
  84 > sudo python setup.py install --optimize=1 --record=install_log.txt
  85
  86 This also saves a list of all installed files to install_log.txt, which you can
  87 use to uninstall ranger.
  88
  89
  90 Getting Started
  91 ---------------
  92 After starting ranger, you can use the Arrow Keys (or hjkl) to navigate, Enter
  93 to open a file or type Q to quit.  The third column shows a preview of the
  94 current file.  The second is the main column and the first shows the parent
  95 directory.
  96
  97 Ranger can automatically copy default configuration files to ~/.config/ranger
  98 if you run it with the switch --copy-config. (see ranger --help for a
  99 description of that switch.)  Also check ranger/config/ for the default
 100 configuration.