Skip to content
/ mentor Public

mentor is a GNU Emacs frontend for the rTorrent bittorrent client.

License

Notifications You must be signed in to change notification settings

skangas/mentor

Repository files navigation

mentor

https://elpa.nongnu.org/nongnu/mentor.svg

mentor is a GNU Emacs frontend for the rTorrent bittorrent client.

By default, it will start and run rTorrent from within Emacs but can also be configured to use an external rTorrent instance over XML-RPC.

This project aims to provide a feature complete and highly customizable interface, that will feel familiar to Emacs users. Key bindings are chosen to be as close to the vanilla rTorrent curses interface as possible.

mentor still has some way to go before it can really be considered a complete interface, so please moderate your expectations. It works fine for many common tasks though, and in some cases (dare we say?) much better than the standard ncurses interface.

Screenshot

doc/screenshot.png

Screenshot of moving a download and its data to another directory using ido integration. Sort your downloads in a breeze!

Features

Here is a summary of some of the features:

  • Show torrents in a table, with configurable columns.
  • Search torrents using C-s (no more of the manual up/down).
  • Mark and perform operations on more than one torrent at once.
  • Sort torrents according to one or more criteria.
  • Move downloads together with their data in one command.
  • Switch between views, create new etc. (like numbers)
  • Support for most standard operations. (Start/stop/rehash/move etc.)
  • Use all Emacs features you are used to: macros, Emacs Lisp, etc.

Installing mentor

Installing through NonGNU ELPA (recommended)

You can install mentor from NonGNU ELPA. Find and install Mentor using this command:

M-x package-list-packages

NonGNU ELPA is configured by default in Emacs 28.1 or later. For earlier versions of Emacs, please see the specific instructions for how to configure NonGNU ELPA.

Mentor should work on Emacs 25 or later. For the best performance I recommend using at least Emacs 27.1, built with libxml support. (See “Known issues” below.) I almost never test Mentor using old versions of Emacs, so please report any issues you run into.

Installing mentor manually

You can also install mentor manually. First, make sure you have the minimum version of xml-rpc.el installed.

Clone this repository using:

git clone https://github.com/skangas/mentor.git

Add this to your init.el:

(add-to-list 'load-path "~/src/mentor/")
(require 'mentor)

Change “~/src/mentor” to the path where you keep the mentor source code.

To byte-compile mentor, go to the source directory and run:

make

To setup autoloading, you can add this to your Init file:

(autoload 'mentor "mentor" nil t)

Quick Start

Make sure that you have rTorrent (0.9.0 or later) installed on your system.

To start mentor, just run:

M-x mentor

It should work out of the box, but you may want to do some additional configuration.

Configuration

General

You can find additional Mentor options in customize.

M-x customize-group RET mentor RET

Two useful variables to customize are mentor-rtorrent-download-directory and mentor-rtorrent-keep-session.

External rTorrent

If you are already running rTorrent outside of Emacs, it is easy to configure Mentor to use it.

Add this to your ~~/.rtorrent.rc~ and restart rTorrent:

scgi_local = ~/.rtorrent-rpc.socket
encoding.add = utf8

Customize mentor-rtorrent-external-rpc, or add this to your Init file and restart Emacs.

(setq mentor-rtorrent-external-rpc "~/.rtorrent-rpc.socket")

You can also specify an absolute path:

;; Alternative 2: Absolute path
(setq mentor-rtorrent-external-rpc "/path/to/rtorrent-rpc.socket")

It is also possible to connect to rtorrent over http. There are instructions on configuring this on the rtorrent wiki.

;; Alternative 3: Use a web server
(setq mentor-rtorrent-external-rpc "https://127.0.0.1:8080/RPC2")

Finally, you can connect directly to rtorrent over scgi. However, anyone that can send rtorrent xmlrpc requests can in all likelihood also execute arbitrary code as the user running rtorrent. Therefore, this is inadvisable on anything but the loopback device (e.g. 127.0.0.1) on single-user systems.

It is almost always easier and better to use a Unix domain socket (file) as suggested above.

;; Alternative 4: Connect directly to rtorrent over scgi
(setq mentor-rtorrent-external-rpc "scgi://127.0.0.1:5000")

Configuring rtorrent

For more information on configuring rTorrent, refer to the rTorrent wiki.

Key Bindings

Downloads

DELAdd torrent file
lAdd Magnet link, URL or torrent file path
sStart download
dStop download
DRemove download
kClose download
KRemove download including data
rInitiate hash check for download
gUpdate screen
GRe-initialize all download data
vShow download in dired

Marking

mMark item
uUnmark item
MMark all items
UUnmark all items

Sorting

t cSort downloads by state
t DSort downloads by directory
t dSort downloads by download speed
t nSort downloads by name
t pSort downloads by size
t tSort downloads by tied file name
t uSort downloads by upload speed

Misc

RETEnter file details screen
RMove download data
CCopy download data
xCall XML-RPC command
qBury mentor
QShutdown mentor

Mapping from rTorrent commands to Mentor

Main view keys

rTorrentMentorDescription
->RETView download
0 - 90 - 9Change view
^SsStart download
^D (1)dStop an active download
^D (2)DRemove download
^KkClose a torrent and its files
n/aKRemove download including data
^EeSet ‘create/resize queued’ flags
^RrInitiate hash check of torrent
^OoChange the destination directory of the download
^XxCall commands or change settings
^Bn/aSet download to perform initial seeding
+ / -+ / -Change the priority of the download
<DEL>DELAdd torrent file
lAdd Magnet link, URL or torrent file path
ln/aView log. Exit by pressing the space-bar
Un/aDelete the file the torrent is tied to, and clear the association
In/aToggle whether torrent ignores ratio settings

Known issues

  • There is no view for trackers/peers/extra information.
  • Mentor can be slow if Emacs was not built with libxml support. This typically happens only when there are several hundreds, or even thousands, of torrents loaded in rtorrent. Use an Emacs built with libxml support to avoid this issue. (Support for libxml was added in Emacs 27.1.)

Contact

You can find the latest version of mentor here:

https://www.github.com/skangas/mentor

Bug reports, comments, and suggestions are welcome! Send them to Stefan Kangas <[email protected]> or report them on GitHub.