A cross-platform (Windows/Linux) file database explorer and monitor. This tool scans your filesystem, stores file metadata in a SQLite database, allows fast searching, and monitors for file changes in real time.

• Scans your filesystem and stores file metadata (name, path, extension, size, timestamps, etc.)
• Search for files by name, extension, or folder
• Sort results by creation date, modification date, extension, or size
• Monitor file changes in real time (new/modified files are updated in the database)
• Open file locations in your system's file explorer
• Cross-platform: Works on Windows and Linux

Create a virtual environment (optional but recommended):

python -m venv search_venv
.\search_venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

python main.py <search_term> [--sort <sort_by>] [--file <filename>] [--folder <foldername>] [--extension <ext>]

• <search_term>: Search for files by name prefix
• --file <filename>: Search for a specific file
• --folder <foldername>: Search for a specific folder
• --extension <ext>: Search by file extension (e.g. --extension .txt or --extension txt)
• --sort <sort_by>: Sort results by one of: create, modified, extension, size

python main.py report --sort size
python main.py --file main.py
python main.py --extension pdf

After searching, the program will display a numbered list of results. Enter the number to open the file location in your system's file explorer.

• On first run, the program scans your filesystem (by default, C:/ on Windows or / on Linux/Unix) and builds a SQLite database (files.db).
• Subsequent runs use the database for fast searching.
• A background thread monitors the filesystem for changes and updates the database in real time.
• Sensitive system folders (like C:/Windows or /proc, /sys, /dev) are excluded from search results for privacy.

The code is designed to be easy to modify. Here are some tips for safe customization:

• Change the scan/monitor root:
  • Pass a different value to FileScanner(root) in main() to scan a different directory.
  • Pass a different path to start_monitor() to monitor a different directory.
• Change excluded folders:
  • Edit the blocked list in ThreadSafeDatabase.search() to add/remove system folders you want to exclude from search results.
• Add more file metadata:
  • Update the FileInfo.get() method to extract more attributes.
  • Update the database schema in ThreadSafeDatabase.create_table() and all related SQL queries to store new fields.
• Change database file location:
  • Change the db_path argument in ThreadSafeDatabase's constructor.
• Change batch size for scanning:
  • Adjust the batch_size argument in FileScanner.scan_and_insert() for performance tuning.
• Add more CLI options:
  • Add arguments in parse_args() and handle them in main().
• Support more OSes or file explorers:
  • Add more branches in FileExplorer.open() for other platforms.
• React to more file events:
  • Add methods like on_deleted or on_moved in FileMonitorHandler.

All major code sections are commented to help you find what to change. If you add new fields or logic, make sure to update all related parts of the code and database.

This project is licensed under the MIT License. See the LICENSE file for details.