README.md

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