findlike

findlike is a command-line tool written in Python that retrieves a list of similar files in relation to a reference text or ad-hoc query.

Imagine you have a document, and you want to find other documents on your computer that talk about similar things. You can use findlike to do that. It looks at the words and phrases used in your reference document or a specific question you have, and then finds other files that use similar language. It's a bit like doing a Google search across your own files.

Features:

• Choose between Okapi BM25 and TF-IDF algorithms for the lexical similarity calculation between file contents
• Recursive search option
• Control over parameters like maximum number of results, whether to display similarity scores etc.
• Optionally return results in JSON format
• Multilingual support
• Highly configurable and can be used as backend for other programs (e.g. personal knowledge management systems, Emacs, etc.)

Table of Contents

• findlike
  • Table of Contents
  • Prerequisites
  • Installation
    • Using uv (recommended)
    • Using pip and virtual environments
    • Manual installation from source
  • Usage
  • Options
  • Examples
  • Development
  • Projects using findlike
  • Acknowledgements
  • License

Prerequisites

• Python 3.10 or higher
• Additional dependencies as listed in the pyproject.txt file

Installation

Using uv (recommended)

To install findlike system-wide using uv, run:

uv tool install findlike

Or to install from source:

git clone https://github.com/brunoarine/findlike.git
cd findlike
uv tool install -e .

Using pip and virtual environments

If you wish to install findlike with pip in a new virtual environment, first create and activate the environment:

python -m venv <virtual environment directory>
source <virtual environment directory>/bin/activate

Then run pip install findlike (without the --user flag).

Manual installation from source

Lastly, if you prefer to install findlike from this repository instead of fetching the package from PyPI:

# Clone this repository
git clone https://github.com/brunoarine/findlike.git

# Navigate into the findlike directory
cd findlike

# Install it as a Python package using `pip`:

pip install -e .

Optionally, you can create an alias for the findlike command to be accessible without activating its virtual environment:

# Replace .bashrc with .zshrc depending on your shell environment.
echo "alias findlike='/path/to/findlike/venv/bin/findlike'" >> ~/.bashrc
source ~/.bashrc

Usage

Here is the basic usage of findlike:

findlike [OPTIONS] [REFERENCE_FILE]

findlike works with either a reference file or a --query option. Once the reference text is set, findlike will scan a given directory (default is the current working dir), and return the most similar documents against the reference.

Options

Here's the breakdown of the available options:

Examples

To find similar documents in a directory (recursively) against a reference text file:

findlike -R -d /path/to/directory reference_file.md 

To search files using a query instead of a reference file while filtering by extension:

findlike -q "black holes" -d /path/to/ayreon/lyrics -f "*.txt"

To find similar files and show their similarity scores and filenames in JSON format:

findlike -s -F json reference_file.md

To print the similarity results as a Markdown list:

findlike -H "# List of similar documents" -p "- " reference_file.txt

Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

cd findlike
python -m venv venv
source venv/bin/activate

Now install the development dependencies:

pip install -e '.[dev]'

To run the tests:

pytest

Projects using findlike

• org-similarity - Emacs package to search for similar org files in relation to the current buffer.

Acknowledgements

• Simon Willison for being an inspiration on releasing small but useful tools more often.
• Sindre Sorhus for the comprehensive list of plain-text file extensions.

License

This project is licensed under the terms of the MIT license. See LICENSE for more details.