README.md

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