Ranger

Build Status

• master :
• develop :

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->

Table of Contents

• Ranger
  • Description
  • Installation
    • Screenshot
    • Screencast
  • Features
  • Todo
  • Window conventions for Ranger
  • Ranger Key Bindings
    • Basic Commands
    • Navigation
    • Search for a File / Directory
    • Copy, Rename/Move or Delete
    • Subdirectories
    • Marking
    • Sorting
    • Toggles / Settings
    • Shell
    • Writable Dired Mode
    • Other
    • Mouse
  • Coming from dired
  • Minimal Ranger Mode (deer)
  • Setting as Default Directory Handler
  • Bookmark Navigation
  • Tab and History Usage
  • Copy and Paste Functionality
  • Selected File Actions
  • File Sorting and Listing
  • Troubleshooting and Package Workarounds
    • helm-descbinds
  • Configuration
    • Buffer Management
    • Directory Listing
    • Window Decoration and Appearance
      • Header-lines
      • Delays
    • Parent Window Options
    • Preview Window Options
      • Exclude Files From Being Previewed
        • By Extension
        • By Size
        • Binary Files

<!-- markdown-toc end -->

Description

This is a minor mode that runs within dired, it emulates many of ranger's features. This minor mode shows a stack of parent directories, and updates the parent buffers, while you're navigating the file system. The preview window takes some of the ideas from Peep-Dired, to display previews for the selected files, in the primary dired buffer.

If you'd like to support development, you can leave a tip on Ko-fi: https://ko-fi.com/rich_alesi

Installation

Ranger requires Emacs 27.1 or later. Once you have setup Melpa you can use the package-install command, to install Ranger. The package name is ranger.

For optional hydra menu support, also install the hydra package:

M-x package-install RET hydra RET

Screenshot

Ranger mode active

Ranger mode showing an image

Screencast

Ranger screencast

Features

• Preview the selected file / directory
• Multi-column display of parent directories
• History log and prompt to navigate through history
• Toggle the file preview, between literal (raw) or fully formatted
• Indirectly scroll through previewed files
• Show images in the preview window
• Fit images to the window when previewing (requires image-dired)
• Quick and persistent sorting across folders
• Quick access to the shell
• Mouse support
• Emacs bookmarks support
• Create bindings to go up / down the next directory
• Minimal ranger mode (deer-mode)
• Copy / paste functionality
• Persistent flags showing recently copied items
• Optional hydra integration for discoverable command menus

Todo

• Preview PDF and document viewing
• Improved navigation within archive files
• Set up tabs and navigate between them
• Work with flattened subdirs and tree

Window conventions for Ranger

Ranger mode with preview enabled

Ranger has the ability to show parent directories, for the current working directory, and a preview of the currently selected file or folder.

In this package, the parent windows denote any window to the left of the active ranger window. These represent the selected file or folder's immediate parent directory. And to the left of the parent window, any number of grandparent windows, if the ranger-parent-depth variable is greater than 1. If you navigate to the root directory, then the parent window will disappear. The parent window is not expected to be interacted with, however [ and ] will navigate up and down the parent directories. <Mouse-1> can also be used to quickly navigate to a file / folder in the parent window.

The active window is designated as the ranger or primary window. Most file activities are performed here. h navigates up to the parent directory, and l opens the selected file or directory. When a file is opened in ranger, then the ranger interface closes, and the window configuration reverts to its previous state.

The window on the right side is designated as the preview window. It shows the contents of the selected file or directory. The preview window is open by default, but it can be opened or closed by pressing: i. It's default state is set with the ranger-preview-file variable. Selected files are previewed literally (raw) without any formatting, by default. To toggle between a fully formatted or a literal preview, press: zi. To preview images, and the contents of archive files, then the literal preview needs to be disabled. The default literal state, is set with the ranger-show-literal variable.

Ranger Key Bindings

Basic Commands

Key Binding | Description ------------- | ----------- ? | show basic commands in the minibuffer du | show selected files, file size q / ZZ | close tab or disable (quit) ranger Q / ZQ | disable (quit) ranger C-r | refresh ranger buffer

Navigation

Key Binding | Description ----------------- | ----------- k/up | up j/down | down h/-/left | to parent directory l/RET/right | to selected directory / open file gg | to top G | to bottom < | to previous directory > | to next directory gh | to home directory C-b | scroll ranger window full page up C-f | scroll ranger window full page down K/C-u | scroll ranger window half page up J/C-d | scroll ranger window half page down C-k | scroll preview window up C-j | scroll preview window down [ | previous parent directory ] | next parent directory ;M-{ | previous marked file / directory ;M-} | next marked file / directory

Search for a File / Directory

Key Binding | Description ------------- | ----------- f | search for file / directory

Copy, Rename/Move or Delete

When the copy command is called by pressing ;C, and only a single file or directory is selected. Then a you'll be asked to enter a new name. However when it's called with multiple marked files / directories, then a you'll be asked for the path to the target directory.

Key Binding | Description ------------- | ----------- ;C | copy the current/marked file(s) / dir(s) R | rename/move the current/marked file(s) / dir(s) D | delete the current/marked file(s) / dir(s) ;d | flag current file/dir for deletion, and select next ;x | delete flagged file(s) / dir(s)

Subdirectories

Key Binding | Description -------------- | ----------- I | insert subdirectory from selected folder gk | move to prev subdirectory gj | move to next subdirectory

Marking

Key Binding | Description ------------------ | ----------- t | toggle mark on current file / directory ;m/C-SPC/TAB | mark current file / dir, and select next ;u | unmark current file / dir, and select next ;U | unmark all files v | invert all marks " | mark files (regexp)

Sorting

Key Binding | Description ------------- | ----------- on | name oN | name (reverse) oe | extension oE | extension (reverse) os | size oS | size (reverse) ot | modified date/time oT | modified date/time (reverse) oc | created date/time oC | created date/time (reverse) zd | sort directories first or last

Toggles / Settings

Key Binding | Description ------------- | ----------- i | toggle the preview window zh | toggle hidden files (e.g. dotfiles) zi | toggle literal / full-text previews zf |