The below is generated from a README at https://github.com/cosmicexplorer/f3. 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+ End Commentary