emacs-dir-treeview

Emacs file system navigator and simple file manager.

This document describes v1.1.0 of emacs-dir-treeview.

• Overview
• Screenshots
• Installation
  • From MELPA
  • Manual installation
  • Post-installation setup
  • Setup of the "pleasant" theme
• Usage
  • Start
  • Current vs. side window
  • Navigating in the tree, with and without mouse
  • The context menu
  • Selection
  • Key bindings
• File notifications
• Customization
• Troubleshooting

Overview

• Displays the file system as a tree; subtrees can be folded and unfolded
• A click on a filename loads the file in Emacs
• A right-click opens a context menu with further actions
• Can open files by external programs or Lisp functions
• Can open terminal in directory
• Can copy, delete, and move files
• Provides selection of multiple files to operate on them
• Works in text mode, too
• Supports file notifications
• Highly customizable
• Themable
• Ships with one theme called "pleasant" using Font Awesome icons

Screenshots

Theme 'pleasant'

Context dialog

Without theme

Text modus

Installation

From MELPA

Dir-treeview is available on MELPA. Provided MELPA is configured in your Emacs (see here for more information), you can install dir-treeview by typing:

    M-x package-install RET dir-treeview RET

Manual installation

As a prerequisite, install emacs-treeview.

Copy the file dir-treeview.el to somewhere in the load path. Optionally, byte-compile the file. Add the following to your init.el:

    (require 'dir-treeview)

Post-installation setup

Bind a key, for example F9, to the command dir-treeview by adding the following to your init.el:

    (global-set-key (kbd "<f9>") 'dir-treeview)

If you installed dir-treeview manually, this statement must occur after the (require 'dir-treeview) statement above.

Setup of the "pleasant" theme

Make sure the "Font Awesome" icon font is installed on your computer.

If you installed dir-treeview manually, copy the file dir-treeview-pleasant-theme.el either to somewhere in the theme load path (cf. Lisp variable custom-theme-load-path) or to somewhere in the usual load path (cf. Lisp variable load-path).

Add the following to your init.el:

    (load-theme 'dir-treeview-pleasant t)

If you installed dir-treeview manually, this statement must occur after the (require 'dir-treeview) statement above.

For moe information about themes, see Custom Themes in the Emacs Manual.

Usage

Start

The normal way to start dir-treeview is by the command dir-treeview. This is why we recommended to bind a key to it in the "Installation" section above. It shows the tree originating at your home directory. If you want to start dir-treeview with a different origin, use the command dir-treeview-open. It will ask for the origin directory in the minibuffer:

    M-x dir-treeview-open RET <directory> RET

The first line of the dir-treeview buffer shows the origin of the tree. The symbol .. in the second line represents the parent directory. A click on the symbol displays the tree of the parent directory. Below that the actual tree starts.

The major mode of the buffer is dir-treeview-mode.

Current vs. side window

By default, dir-treeview uses the current window to display the tree. However, it is also possible to display the tree in a side window (cf. Side Windows in the Emacs Lisp Manual). Thic can be controlled by the customizable variable dir-treeview-show-in-side-window.

Navigating in the tree, with and without mouse

Navigating in the tree with the mouse is straight forward. A left click on the [+] or [-] symbols expand or collapse the respective directory. A left click on a filename opens the respective file in Emacs. A left click on the .. symbol atop the first node switches to the tree originating at the parent directory.

It is possible to navigate in the tree completely without the mouse, only with the keyboard:

• The up and down arrow keys jump to the previuos or next node, respectively. The point (cursor) is placed on the [+] resp. [-] symbol if the node is a directory, and on the filename otherwise.
• The SPACE key expands/collapses the respective directory if the point is on a [+]/[-] symbol.
• The RETURN key expands/collapses the respective directory if the point is on a [+]/[-] symbol.
• The RETURN key opens the respective file in Emacs if the point is on a filename.
• The RETURN key switches to the tree of the parent node if the point is on the .. symbol atop the first node.

The context menu

This section describes the context menu of unselected nodes. Selection and its effect on the context menu is described in the next section.

A right-click on an node opens the nodes's context menu. Alternativly, the context menu can be opened with the e key when the point is on a node. The menu looks different depending on whether the node is a directory or not:

Non-directory-file:

Directory:

Most of the menu items should be self-explanatory.

The Open with... item opens a submenu with external programs or Lisp functions to open the file.

The Open Terminal item opens a shell in terminal program at the corresponding directory.

Both the context menu and the Open with... submenu are customizable.

Selection

Selecting and unselecting files

To select a file, click the filename while holding the control key pressed (<C-mouse-1>), or move the point to the line of the file and type a. The same unselects the file if it is selected, thus, <C-mouse-1> and a actually toggle selection. You can select as many files as you want. Selected files are highlighted in the customizable face dir-treeview-select-face.

You can also select a region of successive files at once: First, select the topmost file. Then, click the last file while holding the shift key pressed (<S-mouse-1>), or move the point to the line of the last file and type A.

To unselect all files, simply press C-g.

Operations on selected files

The following operations can be done on the selected files:

• Copying all selected files
• Moving all selected files
• Deleting all selected files
• Opening all selected files in Emacs
• Open all selected files with an external program

To copy or move the selected files, navigate to the destination (which must be a directory), and open its context menu (right-click or e). The context menu offers one item for moving and one for copying the selected files to the destination directory.

For the other three operations (deleting, opening in Emacs, opening with an external program), open the context menu of one of the selected files. The context menu consists of three items, one for each of the three operations.

Key bindings

As usual in Emacs, dir-treeview activates a special local keymap in its buffers (cf. Local Keymaps in the Emacs Manual). Besides this, dir-treeview defines three additional keymaps which are only active in particular places of the buffer: the control keymap inside the [+]/[-] symbols, the label keymap inside the filenames of the nodes, and the parent dir keymap inside the .. symbol atop the first node. The following tables list the default key bindings of the keymaps:

Local keymap

Control keymap

Label keymap

File notifications

If the operating system provides file watching, dir-treeview can make use of this feature to get notified if a file is changed outside Emacs and update the tree accordingly (cf. Notifications on File Changes in the Emacs Lisp Manual). For example, if a new file is created outside Emacs, a corresponding node shows up automatically without the need to refresh the tree manually.

File notifications are switched on by default. If you don't like that, change the customizable variable dir-treeview-use-file-watch to the value nil. You do so by typing

    M-x customize-variable RET dir-treeview-use-file-watch RET

File notifications can also be switched on and off manually by typing

    M-x dir-treeview-switch-on-file-watch RET

and

    M-x dir-treeview-switch-off-file-watch RET

respectively.

Customization

Dir-treeview uses Emacs' Easy Customization system. The customization group is "dir-treeview". Type

    M-x customize-group RET dir-treeview RET

The customization buffer for dir-treeview opens and a list of settings is displayed. You can change each setting interactively in the buffer. For example, to change the key bindings of the [+]/[-] symbols, open the "Dir Treeview Control Keymap" entry by clicking on the small triangle left to it. You will see the following:

You can now add or remove keys or change the Lisp commands bound the them.

Troubleshooting

If the tree seems to be incorrect, outdated or broken, hit the = key. This runs the command dir-treeview-refresh-tree, which recreates the whole tree and (hopefully) fixes the problems.