NotDeft is an Emacs package for searching and managing collections of plain text note files. It features efficient, local, Xapian engine based search over potentially very large numbers of note files; in that respect it is not much unlike the Notmuch Emacs mode for managing email.
NotDeft was originally based on Deft, an “Emacs mode for quickly browsing, filtering, and editing directories of plain text notes.” NotDeft still includes notdeft-mode as a deft-mode style interface for browsing and filtering search results, but it is now just one of many ways to search and navigate between notes in NotDeft. A command such as M-x notdeft-select-find-file may be quicker in the common case of one just wanting to find a particular note for editing.
NotDeft does not aim for the user interaction simplicity of applications like Deft and Notational Velocity—instead, it intends to provide global note search and manipulation functionality, accessible from various Emacs buffers and Emacs-based applications. A motivation for having that functionality was the desire to allow the user to focus on worthwhile things like reading and reasoning and creating, supported by relevant collected information, but without requiring much time or effort on organization or retrieval of that information.
A popular Emacs-hosted tool for note taking and project planning is Org mode, and NotDeft specifically aims to allow for a degree of disorganization in Org, such that notes can be added to the collection without much thought of directory hierarchies or tagging. Even without a system of organization it should still be possible to find notes in terms of free-text search. Navigation between notes via Org links can nicely complement search, and NotDeft features specific support for linking of Org notes either in terms of (non-directory) file names or search queries, without the fragility and maintenance burden of links tied to specific locations within a filesystem.
NotDeft can be installed for example with its own notdeft-install feature or with straight.el, as we describe here. For further details about installing, configuring, and using NotDeft, see the documentation.
For operation NotDeft requires a notdeft-xapian backend program written in C++. To allow it to be built you should ensure that you have a C++ compiler and the required libraries installed. In addition to Xapian a notable library requirement for compiling the program is TCLAP. On a Debian-based system, for example, you would probably need to have installed the packages g++, pkg-config, libtclap-dev, and libxapian-dev.
For configuring and testing compilation read on about using notdeft-xapian-make and compile for that purpose.
A portable way to install NotDeft is manually with the help of notdeft-install. To do that first fetch the code with
git clone https://github.com/hasu/notdeft.gitTo make NotDeft loadable in Emacs evaluate the following code, and perhaps also add it to your Emacs init file (e.g., “~/.emacs”), replacing “notdeft” with the absolute path of the directory that got cloned:
(dolist (dir '("." "extras" "ivy" "transient"))
(add-to-list 'load-path (expand-file-name dir "notdeft")))With the notdeft-xapian dependencies installed you may want to also check that you have the right C++ compiler incantation configured for building the notdeft-xapian executable for your system. You can do that by evaluating
(require 'notdeft-xapian-make)
(customize-option 'notdeft-xapian-program-compile-command-format)NotDeft includes a notdeft-xapian-make-program-when-uncurrent action that can be registered to do the compilation on demand. Still, it can be instructive to first see feedback from the Emacs compile command, which you can invoke by evaluating
(compile (notdeft-xapian-program-compile-command))which will let you browse any errors or warnings issued by the compiler.
With compilation working you should be able to complete initial NotDeft installation and setup by evaluating
(require 'notdeft-install)
(notdeft-install)where the notdeft-install function generates autoloads and does Emacs Lisp byte-compilation.
The NotDeft source code includes a notdeft-example.el configuration, which you can load with
(load "notdeft-example")in order to have it set up NotDeft for use with Org mode based note files, also enabling some optional components of NotDeft, and setting up some keybindings. The code in that file may be a useful starting point for a personal configuration.
With NotDeft installed it is time to create a “~/.deft” directory for your note collection, and copy some “.org” files there.
After that you can try doing a search with M-x notdeft-select-find-file (<f6> C-f), or browsing your notes in a dedicated mode with M-x notdeft (<f6> e). Both of those commands and more have bindings in the notdeft-global-map keymap.
In a notdeft-mode buffer you can press TAB to enter a search query, and type characters to do further filtering of the results. Press RET to select a file to open. To see other commands of the notdeft-mode-map you can use C-c <f1>.
Those using straight.el and use-package can do cloning, byte-compilation, loading, and configuration of the notdeft package conveniently with a single use-package declaration. For basic configuration similar to the above one could
(use-package notdeft
:straight (notdeft
:type git :host github :repo "hasu/notdeft"
:files ("notdeft*.el" "xapian"))
:defer t
:init
(require 'notdeft-global) ;; for `notdeft-global-map'
(global-set-key [f6] 'notdeft-global-map) ;; choose a prefix key
(setq notdeft-open-query-function 'notdeft-mode-open-query)
(eval-after-load 'org ;; only if using Org format notes
(lambda ()
(require 'notdeft-org9) ;; for "deft:" and "notdeft:" link schemes
(add-hook 'org-mode-hook 'notdeft-note-mode-enable)))
:config
(notdeft-xapian-make-program-when-uncurrent))NotDeft is open source software. Its Emacs Lisp features are made available under GPL version 3 or later, although parts are covered by the BSD license (with text as included in source files where applicable).
The source code of the notdeft-xapian C++ program is turn is made available under GPL version 2 or later.
- “notdeft-homepage.org”
- documentation
- https://tero.hasu.is/tags/notdeft/
- related blog posts
- https://github.com/hasu/notdeft
- source code repository
- “notdeft.el” and “notdeft-mode.el”
- some more documentation (in comments)
- Xapian and Deft and Org mode
- related software and their documentation