f³

The Fantastic File Finder for emacs. Find files fast, using helm. It's cool, trust me.

Motivation

There are many file operations that are difficult to perform without specialized tools. The two this package attempts to solve are:

1. Finding a particular file by name in a large project.
2. Performing operations of arbitrary complexity on many files at once.

The first is usually solved in IDEs by maintaining an index of all files in the project. However, this requires that the project be of a type that the IDE supports. The second is usually solved through a mixture of trial and error, and occasionally the use of find -exec. However, as find is a complex command which supports many different search options, it is often difficult to perform this process efficiently, and if find is not used, it can be time consuming and error-prone to specify a file list manually. This package provides an interactive interface to the find utility using helm as a frontend to solve both of these problems quickly so you can get back to work and stop playing around with the command line.

Usage

Finding Particular Files

M-x f3 brings up a helm buffer displaying all open buffers visiting files. Typing into the minibuffer will narrow down candidates which match the current text pattern among all open buffers, and also spawn a find process which will intelligently use the minibuffer input to search file paths in the current project. By default, f3 attempts to detect the project root; the method by which it does this can be customized by the variable f3-default-directory. Files which find ignores can be customized with the variable f3-before-args. RET visits the currently selected file, and TAB previews the file, killing it after the helm session is quit.

This is often enough to quickly locate files within a given project. For larger or deeply nested project hierarchies, find can become slow; however, after it is run a few times, the operating system's cache typically helps speed up the operation. f3-default-directory can be customized per-folder so that find does not search the entire project if more speed is required.

The current "input mode" determines whether find searches using wildcards or regex; see keybindings below.

Performing Operations On Many Files

When attempting to perform mass operations on files, more search complexity is often desired. find offers a series of predicates and algebraic operators to narrow down search results. Predicates supported by f3 include -[i]path, -[i]regex, -type, -perm, and also a "raw" mode which allows inputting arbitrary find arguments verbatim. This is useful for when the interface offered by f3 becomes too simplistic.

In addition to simple predicates, find offers operators which combine the results of multiple searches in different ways. The operators (sometimes called "combinators" in this documentation) supported by f3 are -and, -or, and parentheses. These are entered mnemonically as M-*, M-+, and M-(/M-), respectively. In this way, a more complex query can be built up. M-u and M-U can "undo" and "redo" pattern inputs, allowing for modification of the find command without having to start again from scratch.

When the results shown interactively in the helm buffer appear to match what is desired, M-d can be used to "bounce" them to a find-dired buffer, where the files can be acted upon in aggregate with a shell command or lisp function in a natural way.

Keybindings

• combinators: these set f3-current-combinator, take the current pattern as the find predicate, and clear the minibuffer
  • M-+ = union ("or")
  • M-* = intersection ("and")
• groupings: these add open or closed parentheses to the current find command and clear the minibuffer
  • M-( = open paren
    • f3 will implicitly close any remaining open parens by adding ) to the end of the find command line produced
  • C-u M-( = open paren, with -not on
  • M-) M-+ = close paren / or
    • if there are no unclosed ), they will be implicitly added
  • M-) M-* = close paren / and
• modes: these do NOT clear the minibuffer, just change the current find predicate
  • M-t = normal text mode (not regex mode)
  • M-x = regex mode
  • M-r = "find" mode (just input raw find arguments)
  • M-f = filetype (b|c|d|f|l|p|s)
  • M-p = perm
• complement: this toggles whether -not is applied to the current predicate
  • M-q = toggle complement (current)
• actions
  • M-d = exit helm and list the files in a find-dired buffer
  • RET = visit
  • TAB = preview
  • M-b = bounce to raw (can use M-R afterwards to restore previous)
• meta
  • M-u = undo whatever was just done
  • M-U = redo
  • M-< = set mindepth
  • M-> = set maxdepth
  • M-R = restore from previous command
  • C-M-R = undo restore (move up and down a previous command stack)
• changing directories
  • M-o = start search from project root
  • M-i = start search from initial choice of default-directory
  • M-c = choose directory to search from, starting at whatever the current choice is
  • M-j = start searching a directory up

Updates

Run ./update-commentary.el in this directory to update the commentary section of the lisp file after changing this README. Run npm install if it complains about node modules.

Further Work

• add docstrings containing the info in this readme
• show state of undo/redo in some readable way
  • also consider making it a traversable tree like emacs's undo-tree
• fix highlighting of results in helm and highlighting of previews
  • maybe use some logic in `f3--filter-buffer-candidates'?

License

GPL 3.0+