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 (will implicitly close any left at end)
  - 'C-u M-(' = open paren, with '-not' on
  - 'M-) M-+' = close paren / or (left parens will be implicitly added if
  needed)
  - '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:

- show state of undo/redo in some readable way
- fix highlighting of results in helm and highlighting of previews; maybe
use some logic in ; `f3--filter-buffer-candidates'?
- add readme to commentary section
- make M-R/C-M-R a stack instead of a single variable
- make f3-default-directory be able to refer to a filename relative to a
.dir-locals.el file or whatnot


License:

GPL 3.0+

End Commentary