Difference between revisions of "Ranger"

From ArchWiki
Jump to: navigation, search
(Installing: +optional)
m (Format)
(18 intermediate revisions by 8 users not shown)
Line 2: Line 2:
 
[[Category:File systems]]
 
[[Category:File systems]]
 
[[fr:ranger]]
 
[[fr:ranger]]
 +
[[zh-CN:ranger]]
 
{{Article summary start|Summary}}
 
{{Article summary start|Summary}}
 
{{Article summary text|A guide to installing and configuring ranger}}
 
{{Article summary text|A guide to installing and configuring ranger}}
 
{{Article summary heading|Related}}
 
{{Article summary heading|Related}}
{{Article summary wiki|atool}}
+
{{Article summary wiki|vifm}}:Another text-based file manager with vi-like keybinds.
 
{{Article summary end}}
 
{{Article summary end}}
 
{{DISPLAYTITLE:ranger}}
 
{{DISPLAYTITLE:ranger}}
 +
 
'''ranger''' is a text-based file manager written in Python with vi-style key bindings. It has an extensive set of features , and you can accomplish file management tasks with a few keystrokes with no need for the mouse.
 
'''ranger''' is a text-based file manager written in Python with vi-style key bindings. It has an extensive set of features , and you can accomplish file management tasks with a few keystrokes with no need for the mouse.
  
==Installing==
+
== Installing ==
{{Pkg|ranger}} can be installed from the [[Official Repositories|official repositories]] with [[pacman]]:
+
 
# pacman -S ranger
+
{{Pkg|ranger}} can be [[pacman|installed]] from the [[official repositories]]. There is also {{AUR|ranger-git}} in [[AUR]].
There is also [https://aur.archlinux.org/packages.php?ID=35421 ranger-git] in [[AUR]].
+
  
 
Optional, for file previews with "scope.sh":
 
Optional, for file previews with "scope.sh":
* {{Pkg|caca-utils}} (img2txt) for previewing images
+
* {{Pkg|libcaca}} (img2txt) for previewing images as ASCII-art
 
* {{Pkg|highlight}} for syntax highlighting of code
 
* {{Pkg|highlight}} for syntax highlighting of code
 
* {{Pkg|atool}} for previews of archives
 
* {{Pkg|atool}} for previews of archives
 
* {{Pkg|lynx}},  {{Pkg|w3m}} or {{Pkg|elinks}} for previews of html pages
 
* {{Pkg|lynx}},  {{Pkg|w3m}} or {{Pkg|elinks}} for previews of html pages
* {{Pkg|itext}} (pdftotext) for pdf previews
+
* {{Pkg|poppler}} (pdftotext) for pdf previews
 
* {{Pkg|transmission-show}} for viewing bit-torrent information
 
* {{Pkg|transmission-show}} for viewing bit-torrent information
* {{Pkg|mediainfo}} or  {{Pkg|exiftool}} for viewing information about media files
+
* {{Pkg|mediainfo}} or  {{Pkg|perl-image-exiftool}} for viewing information about media files
 +
 
 +
== Running ==
  
==Running==
 
 
To start ranger, launch a terminal such as xterm, and type the command {{ic|ranger}}.  Or, you can use the command  
 
To start ranger, launch a terminal such as xterm, and type the command {{ic|ranger}}.  Or, you can use the command  
 
  xterm -e ranger
 
  xterm -e ranger
  
==Comparison with other File Managers==
+
== Comparison with other file managers ==
 +
 
 
Compared to graphical mouse-based file managers, ranger is much more efficient, but still visually appealing.  ranger has one pane with multiple columns for different directories in the path, and file previews on the right.  Compared to double-pane file managers, ranger shows more directory and file information.  You can quickly move between directories using keystrokes, bookmarks or the command history.  Previews of files and directory contents automatically show up for the current selection.  ranger's features include: vi-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view.  ranger has customizable commands and key bindings, including bindings to external scripts.  The closest competitor is [[Vifm]], which has two panes and vi-style key bindings, but has fewer features overall.
 
Compared to graphical mouse-based file managers, ranger is much more efficient, but still visually appealing.  ranger has one pane with multiple columns for different directories in the path, and file previews on the right.  Compared to double-pane file managers, ranger shows more directory and file information.  You can quickly move between directories using keystrokes, bookmarks or the command history.  Previews of files and directory contents automatically show up for the current selection.  ranger's features include: vi-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view.  ranger has customizable commands and key bindings, including bindings to external scripts.  The closest competitor is [[Vifm]], which has two panes and vi-style key bindings, but has fewer features overall.
  
==Documentation==
+
== Documentation ==
 +
 
 
ranger's man page can be opened by typing {{ic|?}}. You can also press {{ic|1?}} for a list of key bindings, {{ic|2?}} for a list of commands and {{ic|3?}} for a list of settings.
 
ranger's man page can be opened by typing {{ic|?}}. You can also press {{ic|1?}} for a list of key bindings, {{ic|2?}} for a list of commands and {{ic|3?}} for a list of settings.
  
==Customization==
+
== Customization ==
 +
 
 
After startup, ranger creates a directory {{ic|~/.config/ranger/}}.  You can copy the default configuration files to this directory with the following command:
 
After startup, ranger creates a directory {{ic|~/.config/ranger/}}.  You can copy the default configuration files to this directory with the following command:
<pre>ranger --copy-config=all</pre>
+
ranger --copy-config=all
They can be then customized. Some basic knowledge of python is useful.
+
They can then be customized. Some basic knowledge of python is useful.
 +
 
 +
* {{ic|rc.conf}} controls startup commands and key bindings
 +
* {{ic|commands.py}} controls the commands which are launched with the ":" key
 +
* {{ic|rifle.conf}} controls the applications used when a given type of file is launched.
 +
 
 +
You can launch files with "l" (ell) or "<Enter>".  For {{ic|rc.conf}}, you need only include changes from the default file, since both are loaded.  For {{ic|commands.py}}, if you do not include the whole file, put this line at the top:
  
*{{ic|options.py}} controls general options
+
from ranger.api.commands import *
*{{ic|rc.conf}} controls startup commands and key bindings
+
*{{ic|commands.py}} controls the commands which are launched with the ":" key
+
*{{ic|apps.py}} controls the applications used when a given type of file is launched.
+
  
You can launch files with "l" (ell) or "<Enter>".  You need only include changes from the default files, but be sure to include any necessary headers.  Also, if you change part of a function, be sure to include the whole thing, since you're redefining that function.
+
=== Binding keys ===
  
===Binding keys===
 
 
Use the file {{ic|~/.config/ranger/rc.conf}} to modify key bindings.  There are many keybindings already defined, and you can learn the syntax by reading the file.
 
Use the file {{ic|~/.config/ranger/rc.conf}} to modify key bindings.  There are many keybindings already defined, and you can learn the syntax by reading the file.
  
 
The following example shows how to use "DD" to move selected files to a directory {{ic|~/.Trash/}}.  Put this code in {{ic|~/.config/ranger/rc.conf}}
 
The following example shows how to use "DD" to move selected files to a directory {{ic|~/.Trash/}}.  Put this code in {{ic|~/.config/ranger/rc.conf}}
<pre>
 
# move to trash
 
map DD shell mv -t /home/myname/.config/ranger/Trash %s
 
</pre>
 
  
===Defining commands===
+
# move to trash
 +
map DD shell mv -t /home/myname/.config/ranger/Trash %s
 +
 
 +
=== Defining commands ===
 +
 
 
Continuing the above example, adding the following entry to {{ic|~/.config/ranger/commands.py}} would define a command to empty the trash directory {{ic|~/.Trash}}.
 
Continuing the above example, adding the following entry to {{ic|~/.config/ranger/commands.py}} would define a command to empty the trash directory {{ic|~/.Trash}}.
<pre>
+
{{bc|<nowiki>
 
class empty(Command):
 
class empty(Command):
"""
+
    """:empty
:empty
+
  
Empties the trash directory ~/.Trash
+
    Empties the trash directory ~/.Trash
"""
+
    """
  
def execute(self):
+
    def execute(self):
self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")
+
        self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")
</pre>
+
</nowiki>}}
 
To use it, you would type ":empty<Enter>", using tab completion if desired.
 
To use it, you would type ":empty<Enter>", using tab completion if desired.
  
 
{{Warning|Note that [^.] is an essential part of the above command.  Otherwise, it will remove all files and directories of the form ..*, thereby wiping out everything in your home directory.}}
 
{{Warning|Note that [^.] is an essential part of the above command.  Otherwise, it will remove all files and directories of the form ..*, thereby wiping out everything in your home directory.}}
  
===Starting programs in the background===
+
=== Opening files with a given application ===
In many cases, launching a file will make ranger unusable until the program you used to launch the file is closed.  The following example shows how to change this for html files.  In {{ic|~/.config/ranger/apps.py}}, change
+
 
<pre>
+
Modify {{ic|~/.config/ranger/rifle.conf}}. Since the beginning lines are executed first, you should put your modifications at the beginning of the file. For example, the following entry will open a tex file with kile.
if f.extension in ('html', 'htm', 'xhtml', 'swf'):
+
 
return self.either(c, 'firefox', 'opera', 'elinks')
+
ext tex = kile "$@"
</pre>
+
 
to
+
==== Using sxiv to browse through images ====
<pre>
+
 
if f.extension in ('html', 'htm', 'xhtml', 'swf'):
+
In order to browse through images in [[sxiv]] after launching the viewer from ranger by opening an image file, use the [http://git.savannah.gnu.org/cgit/ranger.git/tree/doc/examples/rifle_sxiv.sh rifle_sxiv.sh script] and follow the instructions in its comments.
c.flags += 'd'
+
 
return self.either(c, 'firefox', 'opera')
+
== Useful commands ==
</pre>
+
 
The option "d" stands for "detached". We removed "elinks" because it's a text-mode browser, and cannot be detached
+
=== External Drives ===
  
==Useful commands==
 
===External Drives===
 
 
External drives can be automatically mounted with an [[Udev]] rule or with the help of an automounting Udev wrapper. Drives mounted under {{ic|/media}} can be easily accessed by pressing {{keypress|gm}} (go, media).
 
External drives can be automatically mounted with an [[Udev]] rule or with the help of an automounting Udev wrapper. Drives mounted under {{ic|/media}} can be easily accessed by pressing {{keypress|gm}} (go, media).
  
===Network Drives===
+
=== Network drives ===
 +
 
 +
=== Archive related ===
  
===Archive Related===
 
 
These commands use {{Pkg|atool}} to perform archive operations.
 
These commands use {{Pkg|atool}} to perform archive operations.
  
====Extraction====
+
==== Extraction ====
 +
 
 
The following command implements archive extraction by copying (yy) one or more archive files and then executing ":extracthere" on the desired directory.
 
The following command implements archive extraction by copying (yy) one or more archive files and then executing ":extracthere" on the desired directory.
  
<pre>
+
{{bc|<nowiki>
 
import os
 
import os
 
from ranger.core.loader import CommandLoader
 
from ranger.core.loader import CommandLoader
Line 132: Line 138:
 
         obj.signal_bind('after', refresh)
 
         obj.signal_bind('after', refresh)
 
         self.fm.loader.add(obj)
 
         self.fm.loader.add(obj)
</pre>
+
</nowiki>}}
  
====Compression====
+
==== Compression ====
The following command allows the user to compress several files on the current directory by marking them and then calling ":compress <package name>". It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension.
+
  
<pre>
+
The following command allows the user to compress several files on the current directory by marking them and then calling {{ic|:compress ''package name''}}. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension.
 +
 
 +
{{bc|<nowiki>
 
import os
 
import os
 
from ranger.core.loader import CommandLoader
 
from ranger.core.loader import CommandLoader
Line 170: Line 177:
 
         extension = ['.zip', '.tar.gz', '.rar', '.7z']
 
         extension = ['.zip', '.tar.gz', '.rar', '.7z']
 
         return ['compress ' + os.path.basename(self.fm.env.cwd.path) + ext for ext in extension]
 
         return ['compress ' + os.path.basename(self.fm.env.cwd.path) + ext for ext in extension]
</pre>
+
</nowiki>}}
 +
 
 +
=== Image mounting ===
  
===Image Mounting===
 
 
The following command assumes you are using [[cdemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Don't forget to change mountpath to reflect your system settings'''.
 
The following command assumes you are using [[cdemu]] as your image mounter and some kind of system like [[autofs]] which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). '''Don't forget to change mountpath to reflect your system settings'''.
  
 
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.
 
To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.
  
<pre>
+
{{bc|<nowiki>
 
import os, time
 
import os, time
 
from ranger.core.loader import Loadable
 
from ranger.core.loader import Loadable
Line 227: Line 235:
 
         obj.signal_bind('after', mount_finished)
 
         obj.signal_bind('after', mount_finished)
 
         self.fm.loader.add(obj)
 
         self.fm.loader.add(obj)
</pre>
+
</nowiki>}}
 +
 
 +
== See also ==
  
==Web Resources==
 
 
* [http://nongnu.org/ranger ranger] web page.
 
* [http://nongnu.org/ranger ranger] web page.
* Arch Linux [https://bbs.archlinux.org/viewtopic.php?id=93025 forum thread].
+
* [https://lists.nongnu.org/mailman/listinfo/ranger-users ranger mailing list]
 +
* Arch Linux [https://bbs.archlinux.org/viewtopic.php?id=93025 Forum thread].
 
* [http://github.com/hut/ranger GitHub-page]
 
* [http://github.com/hut/ranger GitHub-page]
 
* [http://dotshare.it/category/fms/ranger/ DotShare.it] configurations.
 
* [http://dotshare.it/category/fms/ranger/ DotShare.it] configurations.

Revision as of 11:34, 10 June 2013

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki:Another text-based file manager with vi-like keybinds. Template:Article summary end


ranger is a text-based file manager written in Python with vi-style key bindings. It has an extensive set of features , and you can accomplish file management tasks with a few keystrokes with no need for the mouse.

Installing

ranger can be installed from the official repositories. There is also ranger-gitAUR in AUR.

Optional, for file previews with "scope.sh":

Running

To start ranger, launch a terminal such as xterm, and type the command ranger. Or, you can use the command

xterm -e ranger

Comparison with other file managers

Compared to graphical mouse-based file managers, ranger is much more efficient, but still visually appealing. ranger has one pane with multiple columns for different directories in the path, and file previews on the right. Compared to double-pane file managers, ranger shows more directory and file information. You can quickly move between directories using keystrokes, bookmarks or the command history. Previews of files and directory contents automatically show up for the current selection. ranger's features include: vi-style key bindings, bookmarks, selections, tagging, tabs, command history, the ability to make symbolic links, several console modes, and a task view. ranger has customizable commands and key bindings, including bindings to external scripts. The closest competitor is Vifm, which has two panes and vi-style key bindings, but has fewer features overall.

Documentation

ranger's man page can be opened by typing ?. You can also press 1? for a list of key bindings, 2? for a list of commands and 3? for a list of settings.

Customization

After startup, ranger creates a directory ~/.config/ranger/. You can copy the default configuration files to this directory with the following command:

ranger --copy-config=all

They can then be customized. Some basic knowledge of python is useful.

  • rc.conf controls startup commands and key bindings
  • commands.py controls the commands which are launched with the ":" key
  • rifle.conf controls the applications used when a given type of file is launched.

You can launch files with "l" (ell) or "<Enter>". For rc.conf, you need only include changes from the default file, since both are loaded. For commands.py, if you do not include the whole file, put this line at the top:

from ranger.api.commands import *

Binding keys

Use the file ~/.config/ranger/rc.conf to modify key bindings. There are many keybindings already defined, and you can learn the syntax by reading the file.

The following example shows how to use "DD" to move selected files to a directory ~/.Trash/. Put this code in ~/.config/ranger/rc.conf

# move to trash
map DD shell mv -t /home/myname/.config/ranger/Trash %s

Defining commands

Continuing the above example, adding the following entry to ~/.config/ranger/commands.py would define a command to empty the trash directory ~/.Trash.

class empty(Command):
    """:empty

    Empties the trash directory ~/.Trash
    """

    def execute(self):
        self.fm.run("rm -rf /home/myname/.Trash/{*,.[^.]*}")

To use it, you would type ":empty<Enter>", using tab completion if desired.

Warning: Note that [^.] is an essential part of the above command. Otherwise, it will remove all files and directories of the form ..*, thereby wiping out everything in your home directory.

Opening files with a given application

Modify ~/.config/ranger/rifle.conf. Since the beginning lines are executed first, you should put your modifications at the beginning of the file. For example, the following entry will open a tex file with kile.

ext tex = kile "$@"

Using sxiv to browse through images

In order to browse through images in sxiv after launching the viewer from ranger by opening an image file, use the rifle_sxiv.sh script and follow the instructions in its comments.

Useful commands

External Drives

External drives can be automatically mounted with an Udev rule or with the help of an automounting Udev wrapper. Drives mounted under /media can be easily accessed by pressing Template:Keypress (go, media).

Network drives

Archive related

These commands use atool to perform archive operations.

Extraction

The following command implements archive extraction by copying (yy) one or more archive files and then executing ":extracthere" on the desired directory.

import os
from ranger.core.loader import CommandLoader

class extracthere(Command):
    def execute(self):
        """ Extract copied files to current directory """
        copied_files = tuple(self.fm.env.copy)

        if not copied_files:
            return

        def refresh(_):
            cwd = self.fm.env.get_directory(original_path)
            cwd.load_content()

        one_file = copied_files[0]
        cwd = self.fm.env.cwd
        original_path = cwd.path
        au_flags = ['-X', cwd.path]
        au_flags += self.line.split()[1:]
        au_flags += ['-e']

        self.fm.env.copy.clear()
        self.fm.env.cut = False
        if len(copied_files) == 1:
            descr = "extracting: " + os.path.basename(one_file.path)
        else:
            descr = "extracting files from: " + os.path.basename(one_file.dirname)
        obj = CommandLoader(args=['aunpack'] + au_flags \
                + [f.path for f in copied_files], descr=descr)

        obj.signal_bind('after', refresh)
        self.fm.loader.add(obj)

Compression

The following command allows the user to compress several files on the current directory by marking them and then calling :compress package name. It supports name suggestions by getting the basename of the current directory and appending several possibilities for the extension.

import os
from ranger.core.loader import CommandLoader

class compress(Command):
    def execute(self):
        """ Compress marked files to current directory """
        cwd = self.fm.env.cwd
        marked_files = cwd.get_selection()

        if not marked_files:
            return

        def refresh(_):
            cwd = self.fm.env.get_directory(original_path)
            cwd.load_content()

        original_path = cwd.path
        parts = self.line.split()
        au_flags = parts[1:]

        descr = "compressing files in: " + os.path.basename(parts[1])
        obj = CommandLoader(args=['apack'] + au_flags + \
                [os.path.relpath(f.path, cwd.path) for f in marked_files], descr=descr)

        obj.signal_bind('after', refresh)
        self.fm.loader.add(obj)

    def tab(self):
        """ Complete with current folder name """

        extension = ['.zip', '.tar.gz', '.rar', '.7z']
        return ['compress ' + os.path.basename(self.fm.env.cwd.path) + ext for ext in extension]

Image mounting

The following command assumes you are using cdemu as your image mounter and some kind of system like autofs which mounts the virtual drive to a specified location ('/media/virtualrom' in this case). Don't forget to change mountpath to reflect your system settings.

To mount an image (or images) to a cdemud virtual drive from ranger you select the image files and then type ':mount' on the console. The mounting may actually take some time depending on your setup (in mine it may take as long as one minute) so the command uses a custom loader that waits until the mount directory is mounted and then opens it on the background in tab 9.

import os, time
from ranger.core.loader import Loadable
from ranger.ext.signals import SignalDispatcher
from ranger.ext.shell_escape import *

class MountLoader(Loadable, SignalDispatcher):
    """
    Wait until a directory is mounted
    """
    def __init__(self, path):
        SignalDispatcher.__init__(self)
        descr = "Waiting for dir '" + path + "' to be mounted"
        Loadable.__init__(self, self.generate(), descr)
        self.path = path

    def generate(self):
        available = False
        while not available:
            try:
                if os.path.ismount(self.path):
                    available = True
            except:
                pass
            yield
            time.sleep(0.03)
        self.signal_emit('after')

class mount(Command):
    def execute(self):
        selected_files = self.fm.env.cwd.get_selection()

        if not selected_files:
            return

        space = ' '
        self.fm.execute_command("cdemu -b system unload 0")
        self.fm.execute_command("cdemu -b system load 0 " + \
                space.join([shell_escape(f.path) for f in selected_files]))
 
        mountpath = "/media/virtualrom/"

        def mount_finished(path):
            currenttab = self.fm.current_tab
            self.fm.tab_open(9, mountpath)
            self.fm.tab_open(currenttab)

        obj = MountLoader(mountpath)
        obj.signal_bind('after', mount_finished)
        self.fm.loader.add(obj)

See also