README.md

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