package docfd

Docfd

TUI multiline fuzzy document finder

Think interactive grep for text files, PDFs, DOCXs, etc, but word/token based instead of regex and line based, so you can search across lines easily.

Docfd aims to provide good UX via integration with common text editors and PDF viewers, so you can jump directly to a search result with a single key press.

Navigating repo:

Quick search with non-interactive mode:

Navigating PDF and opening it to the closest location to the selected search result via PDF viewer integration:

Features

• Multithreaded indexing and searching

• Multiline fuzzy search of multiple files or a single file

• Swap between multi-file view and single file view on the fly

• Content view pane that shows the snippet surrounding the search result selected

• Text editor and PDF viewer integration

Installation

Statically linked binaries are available via GitHub releases.

Docfd is also packaged on:

• opam

• AUR (as docfd-bin) by kseistrup

• Nix (as docfd) by chewblacka

Notes for packagers: Outside of the OCaml toolchain for building (if you are packaging from source), Docfd also requires the following external tools at run time for full functionality:

• pdftotext from poppler-utils for PDF support

• pandoc for support of .epub, .odt, .docx, .fb2, .ipynb, .html, and .htm files

• fzf for file selection menu

Launching

Read from piped stdin

command | docfd

Docfd uses single file view when source of document is piped stdin.

No paths should be supplied as arguments in this case. If any paths are specified, then stdin is ignored.

Scan for files

docfd [PATH]...

The list of paths can contain directories. Each directory in the list is scanned recursively for files with one of the following extensions by default:

• .txt

• .md

• .pdf

You can change the file extensions to use via --exts, or add onto the list of extensions via --add-exts.

If the list PATHs is empty, then Docfd defaults to scanning the current directory ..

Scan for files then select with fzf

docfd [PATH]... ?

The ? can be in any position in the path list. If any of the path is ?, then file selection of the discovered files via fzf is invoked.

Use list of paths from file

docfd [PATH]... --paths-from paths.txt

The final list of paths used is then the concatenation of PATHs and paths listed in paths.txt, which has one path per line.

The list PATHs does not default to . when --paths-from is used.

Searching

The search field takes a search expression as input. A search expression is one of:

• Search phrase, e.g. fuzzy search

• ?expression (optional)

• (expression)

• expression | expression (or), e.g. go ( left | right )

To use literal ?, (, ) or |, a backslash (\) needs to be placed in front of the character.

Common controls between multi-file view and single file view

Navigation mode

• Switch to search mode

  • /

• Clear search phrase

  • x

• Exit Docfd

  • Esc, Ctrl+C or Ctrl+Q

• Print selected search result to stderr

  • p

• Print path of selected document to stderr

  • Shift+P

Search mode

• Search field is active in this mode

• Enter to confirm search phrase and exit search mode

Multi-file view

The default TUI is divided into four sections:

• Left is the list of documents which satisfy the search phrase

• Top right is the content view of the document which tracks the search result selected

• Bottom right is the ranked search result list

• Bottom pane consists of:

  • Status bar

  • Key binding info

  • File content requirement field

  • Search field

Controls

Single file view

If the specified path to Docfd is not a directory, then single file view is used.

In this view, the TUI is divided into only two sections:

• Top is ranked search result list

• Bottom is the search interface

Controls

Limitations

• File auto-reloading is not supported for PDF files, as PDF viewers are invoked in the background via shell. It is possible to support this properly in the ways listed below, but requires a lot of engineering for potentially very little gain:

  • Docfd waits for PDF viewer to terminate fully before resuming, but this prohibits viewing multiple search results simultaneously in different PDF viewer instances.

  • Docfd manages the launched PDF viewers completely, but these viewers are closed when Docfd terminates.

  • Docfd invokes the PDF viewers via shell so they stay open when Docfd terminates. Docfd instead periodically checks if they are still running via the PDF viewers' process IDs, but this requires handling forks.

  • Outside of tracking whether the PDF viewer instances interacting with the files are still running, Docfd also needs to set up file update handling either via inotify or via checking file modification times periodically.

Acknowledgement

• Demo gifs are made using vhs.

• ripgrep-all for text extraction software choices