README.md

   1 ranger 1.9.1
   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:     https://ranger.github.io/
  33 * Download:    https://ranger.github.io/ranger-stable.tar.gz
  34 * Bug reports: https://github.com/ranger/ranger/issues
  35 * git clone    https://github.com/ranger/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 * `python-bidi` for correct display of RTL file names (Hebrew, Arabic)
  72
  73 Optional, for enhanced file previews (with `scope.sh`):
  74
  75 * `img2txt` (from `caca-utils`) for ASCII-art image previews
  76 * `highlight` or `pygmentize` for syntax highlighting of code
  77 * `atool`, `bsdtar` and/or `unrar` for previews of archives
  78 * `lynx`, `w3m` or `elinks` for previews of html pages
  79 * `pdftotext` or `mutool` for pdf previews
  80 * `transmission-show` for viewing bit-torrent information
  81 * `mediainfo` or `exiftool` for viewing information about media files
  82 * `odt2txt` for OpenDocument text files (`odt`, `ods`, `odp` and `sxw`)
  83 * `chardet` (Python package) for improved encoding detection of text files
  84
  85
  86 Installing
  87 ----------
  88 Use the package manager of your operating system to install ranger.
  89 Note that ranger can be started without installing by simply running `ranger.py`.
  90
  91 To install ranger manually:
  92 ```
  93 sudo make install
  94 ```
  95
  96 This translates roughly to:
  97 ```
  98 sudo python setup.py install --optimize=1 --record=install_log.txt
  99 ```
 100
 101 This also saves a list of all installed files to `install_log.txt`, which you can
 102 use to uninstall ranger.
 103
 104
 105 Getting Started
 106 ---------------
 107 After starting ranger, you can use the Arrow Keys or `h` `j` `k` `l` to navigate, `Enter`
 108 to open a file or type `Q` to quit.  The third column shows a preview of the
 109 current file.  The second is the main column and the first shows the parent
 110 directory.
 111
 112 Ranger can automatically copy default configuration files to `~/.config/ranger`
 113 if you run it with the switch `--copy-config=( rc | scope | ... | all )`.
 114 See `ranger --help` for a description of that switch.  Also check
 115 `ranger/config/` for the default configuration.