Deft for Emacs

Deft is an Emacs mode for quickly browsing, filtering, and editing directories of plain text notes, inspired by Notational Velocity. It was designed for increased productivity when writing and taking notes by making it fast and simple to find the right file at the right time and by automating many of the usual tasks such as creating new files and saving files.

Deft is open source software and may be freely distributed and modified under the BSD license. Version 0.7 is the latest stable version, released on December 21, 2015. You may download it directly here:

To follow or contribute to Deft development, you can browse or clone the Git repository at jblevins.org or GitHub:

git clone git://jblevins.org/git/deft.git
git clone https://github.com/jrblevin/deft.git

Build Status

Deft Screencast
Deft Screencast

The Deft buffer is simply a file browser which lists the titles of all text files in the Deft directory followed by short summaries and last modified times. The title is taken to be the first line of the file and the summary is extracted from the text that follows. Files are, by default, sorted in terms of the last modified date, from newest to oldest.

All Deft files or notes are simple plain text files where the first line contains a title. As an example, the following directory structure generated the screenshot above.

% ls ~/.deft
about.txt    browser.txt     directory.txt   operations.txt
ack.txt      completion.txt  extensions.org
binding.txt  creation.txt    filtering.txt

% cat ~/.deft/about.txt
# About

An Emacs mode for slicing and dicing plain text files.

Deft’s primary operation is searching and filtering. The list of files can be limited or filtered using a search string, which will match both the title and the body text. To initiate a filter, simply start typing. Filtering happens on the fly. As you type, the file browser is updated to include only files that match the current string.

To open the first matching file, simply press RET. If no files match your search string, pressing RET will create a new file using the string as the title. This is a very fast way to start writing new notes. The filename will be generated automatically. If you prefer to provide a specific filename, use C-RET instead.

To open files other than the first match, navigate up and down using C-p and C-n and press RET on the file you want to open. When opening a file, Deft searches forward and leaves the point at the end of the first match of the filter string.

You can also press C-o to open a file in another window, without switching to the other window. Issue the same command with a prefix argument, C-u C-o, to open the file in another window and switch to that window.

To edit the filter string, press DEL (backspace) to remove the last character or M-DEL to remove the last “word”. To yank (paste) the most recently killed (cut or copied) text into the filter string, press C-y. Press C-c C-c to clear the filter string and display all files and C-c C-g to refresh the file browser using the current filter string.

For more advanced editing operations, you can also edit the filter string in the minibuffer by pressing C-c C-l. While in the minibuffer, the history of previous edits can be cycled through by pressing M-p and M-n. This form of static, one-time filtering (as opposed to incremental, on-the-fly filtering) may be preferable in some situations, such as over slow connections or on systems where interactive filtering performance is poor.

By default, Deft filters files in incremental string search mode, where “search string” will match all files containing both “search” and “string” in any order. Alternatively, Deft supports direct regexp filtering, where the filter string is interpreted as a formal regular expression. For example, ^\(foo\|bar\) matches foo or bar at the beginning of a line. Pressing C-c C-t will toggle between incremental and regexp search modes. Regexp search mode is indicated by an “R” in the mode line.

Common file operations can also be carried out from within Deft. Files can be renamed using C-c C-r or deleted using C-c C-d. New files can also be created using C-c C-n for quick creation or C-c C-m for a filename prompt. You can leave Deft at any time with C-c C-q.

Unused files can be archived by pressing C-c C-a. Files will be moved to deft-archive-directory, which is a directory named archive within your deft-directory by default.

Files opened with deft are automatically saved after Emacs has been idle for a customizable number of seconds. This value is a floating point number given by deft-auto-save-interval (default: 1.0).

Getting Started

To start using it, place it somewhere in your Emacs load-path and add the line

(require 'deft)

in your .emacs file. Then run M-x deft to start. It is useful to create a global keybinding for the deft function (e.g., a function key) to start it quickly (see below for details).

When you first run Deft, it will complain that it cannot find the ~/.deft directory. You can either create a symbolic link to another directory where you keep your notes or run M-x deft-setup to create the ~/.deft directory automatically.

One useful way to use Deft is to keep a directory of notes in a Dropbox folder. This can be used with other applications and mobile devices, for example, nvALT, Notational Velocity, or Simplenote on OS X or Editorial, Byword, or 1Writer on iOS.

Basic Customization

You can customize items in the deft group to change the default functionality.

By default, Deft looks for notes by searching for files with the extensions .txt, .text, .md, .markdown, or .org in the ~/.deft directory. You can customize both the file extension and the Deft directory by running M-x customize-group and typing deft. Alternatively, you can configure them in your .emacs file:

(setq deft-extensions '("txt" "tex" "org"))
(setq deft-directory "~/Dropbox/notes")

The first element of deft-extensions (or in Lisp parlance, the car) is the default extension used to create new files.

By default, Deft only searches for files in deft-directory but not in any subdirectories. All files in deft-directory with one of the specified extensions will be included except for those matching deft-ignore-file-regexp. Set deft-recursive to a non-nil value to enable searching for files in subdirectories (those not matching deft-recursive-ignore-dir-regexp):

(setq deft-recursive t)

You can easily set up a global keyboard binding for Deft. For example, to bind it to F8, add the following code to your .emacs file:

(global-set-key [f8] 'deft)

Reading Files

The displayed title of each file is taken to be the first line of the file, with certain characters removed from the beginning. Hash characters, as used in Markdown headers, and asterisks, as in Org Mode headers, are removed. Additionally, Org mode #+TITLE: tags, MultiMarkdown Title: tags, LaTeX comment markers (%), and Emacs mode-line declarations (e.g., -*-mode-*-) are stripped from displayed titles. This can be customized by changing deft-strip-title-regexp.

More generally, the title post-processing function itself can be customized by setting deft-parse-title-function, which accepts the first line of the file as an argument and returns the parsed title to display in the file browser. The default function is deft-strip-title, which removes all occurrences of deft-strip-title-regexp as described above.

For compatibility with other applications which use the filename as the title of a note (rather than the first line of the file), set the deft-use-filename-as-title flag to a non-nil value. Deft will then use note filenames to generate the displayed titles in the Deft file browser. To enable this, add the following to your .emacs file:

(setq deft-use-filename-as-title t)

Finally, the short summary that is displayed following the file title can be customized by changing deft-strip-summary-regexp. By default, this is set to remove certain org-mode metadata statements such as #+OPTIONS: and #+AUTHOR:.

Creating Files

Filenames for newly created files are generated by Deft automatically. The process for doing so is determined by the variables deft-use-filename-as-title and deft-use-filter-string-for-filename as well as the rules in the deft-file-naming-rules alist. The possible cases are as follows:

  1. Default (deft-use-filename-as-title and deft-use-filter-string-for-filename are both nil):

    The filename will be automatically generated with prefix deft- and a numerical suffix as in deft-0.ext, deft-1.ext, … The filter string will be inserted as the first line of the file (which is also used as the display title).

  2. Filenames as titles (deft-use-filename-as-title is non-nil):

    When deft-use-filename-as-title is non-nil, the filter string will be used as the filename for new files (with the appropriate file extension appended to the end).

  3. Readable filenames (deft-use-filename-as-title is nil but deft-use-filter-string-for-filename is non-nil):

    In this case you can choose to display the title as parsed from the first line of the file while also generating readable filenames for new files based on the filter string. The variable deft-use-filter-string-for-filename controls this behavior and decouples the title display (deft-use-filename-as-title) from the actual filename. New filenames will be generated from the filter string and processed according to the rules defined in the deft-file-naming-rules alist. By default, slashes are removed and replaced by hyphens, but many other options are possible (camel case, replacing spaces by hyphens, and so on). See the documentation for deft-file-naming-rules for additional details.

Titles inserted into files from the filter string can also be customized for two common modes, markdown-mode and org-mode, by setting the following variables:

Other Customizations

Deft, by default, lists files from newest to oldest. You can set deft-current-sort-method to ’title to sort by file titles, case ignored. Or, you can toggle sorting method using deft-toggle-sort-method.

Incremental string search is the default method of filtering on startup, but you can set deft-incremental-search to nil to make regexp search the default.

Deft also provides a function for opening files without using the Deft buffer directly. Calling deft-find-file will prompt for a file to open, just like find-file, but starting from deft-directory. If the file selected is in deft-directory, it is opened with the usual deft features (automatic saving, automatic updating of the Deft buffer, etc.). Otherwise, the file will be opened by find-file as usual. Therefore, you can set up a global keybinding for this function to open Deft files anywhere. For example, to use C-x C-g, a neighbor of C-x C-f, use the following:

(global-set-key (kbd "C-x C-g") 'deft-find-file)

The faces used for highlighting various parts of the screen can also be customized. By default, these faces inherit their properties from the standard font-lock faces defined by your current color theme.

Acknowledgments

Thanks to Konstantinos Efstathiou for writing simplenote.el, from which I borrowed liberally, and to Zachary Schneirov for writing Notational Velocity, whose functionality and spirit I wanted to bring to Emacs.

History

Version 0.7 (2015–12–21):

Version 0.6 (2015–06–26):

Version 0.5.1 (2013–01–28):

Version 0.5 (2013–01–25):

Version 0.4 (2011–12–11):

Version 0.3 (2011–09–11):

Version 0.2 (2011–08–22):

Deft was originally written by Jason Blevins. The initial version, 0.1, was released on August 6, 2011.

Although Deft is free, it is the result of many years of work. If you use it regularly and it has made your life or work easier or more enjoyable, then you can say thanks by supporting Deft!