path: root/README

Ranger v.1.0.3
==============

Ranger

   A keeper, guardian, or soldier who ranges over a region
   to protect the area or enforce the law.

This file browser gives you the ability to swiftly move around
and get a broad overview of your forest of directory trees.

Rangers default hotkeys make it intuitive for users of the popular
text-editor VIM, but it is fully customizable.

The program is written in Python since version 1.0.0 and uses
ncurses for the (completely text based) user interface.


About
-----

* Author:          hut
* Email:           hut@lavabit.com
* Git repo:        http://repo.or.cz/w/ranger.git
* Version:         1.0.3


Features
--------

* Multi-column display
* Preview of the selected file/directory
* Common file operations (create/chmod/copy/delete/...)
* Quickly find files or text inside files
* VIM-like console and hotkeys
* Open files in external programs
* Mouse support
* Change the directory of your shell after exiting ranger
* Bookmarks


Dependencies
------------

* A Unix-like OS        (Linux, BSD, Mac OS, ...)
* Python 2.6 or 3.1
* Python curses module


Bugs and Feature Requests
-------------------------

Report bugs and feature requests on the bug tracker of
the ranger repository on GitHub:
    http://github.com/hut/ranger/issues

Alternatively you can send an email to hut@lavabit.com.

Please include as much relevant information as possible.
Using ranger with the --debug option will abort the program and
print tracebacks in certain cases.


Getting Started
---------------

At first, it's a good idea to create a symlink in your bin dir:
    sudo ln -s /path/to/ranger.py /usr/bin/ranger

Now type in ranger to start it.

You should see 4 columns.  The third is the directory where you are at
the moment.  To the left, there are the directories above the current
working directory, and the column on the right is a preview of the selected
file/directory.

Now use the arrow keys to navigate, press enter to open a file.

A list of commands with short descriptions can be viewed by
pressing "?" inside the program and following the instructions.
The file code/keys.rb contains all key combinations, so that's another
place you may want to check out.
More extensive documentation will be written when enough users ask me to :)


Opening Files with Ranger
-------------------------

If you use the same applications like me, you'll be able to open
files by pressing the right arrow key.  If not, you will have to
specify them in ranger/defaults/apps.py.  It's explained
in the docstrings how exactly to do that.

Once you've set up your applications, you can also use ranger to
open files from the shell:
    ranger blabla.pdf


Customizing Ranger
------------------

The file ranger/defaults/options.py contains most of the options.
apps.py defines how files are run, keys.py defines keybindings.

The files in ranger/defaults/ can be copied into ~/.ranger/ for per-user
modifications.  Colorschemes can be placed in ~/.ranger/colorschemes.

The configuration files should be self-explanatory.  If you need more
information, check out the source code.

Also, see the file HACKING for more detailed instructions on
modifying the program.