Marlin/README.md

Marlin Logo

Marlin

Marlin is a lightweight, metadata-driven file indexer you run on your own machine. It scans folders, stores paths and basic stats in a local SQLite database, and lets you tag files from the command line.

Nothing leaves your computer.

This repo contains the Sprint-0 foundation:

• XDG-aware config — no hard-coded paths
• Embedded SQLite migrations (WAL mode)
• Fast directory scanner (now accepts multiple paths in one call)
• Simple tagging tool
• Human-readable logging via tracing

---

How it works

┌──────────────┐  scan dir(s)    ┌─────────────┐
│  your files  │ ───────────────▶│   SQLite    │
└──────────────┘                 │  index.db   │
        ▲  tag <glob> <tag>      │ files tags  │
        └────────────────────────┴─────────────┘

1. marlin scan <PATHS>... walks each directory tree, gathers size and modification time, then upserts rows into files.
2. marlin tag "<glob>" <tag> looks up each matching file row and inserts junction rows into file_tags. New tag names are created on the fly.
3. You can open the DB yourself (sqlite3 ~/.local/share/marlin/index.db) while search and GUI features are still under construction.

---

Prerequisites

What	Why
Rust ≥ 1.77	Build toolchain (rustup.rs)
Build essentials	gcc, make, etc. for rusqlite’s bundled SQLite

Platform notes

Windows

rustup-init.exe installs MSVC build tools automatically.

macOS

xcode-select --install        # command-line tools

Linux (Debian / Ubuntu)

sudo apt install build-essential

or on Fedora / RHEL

sudo dnf groupinstall "Development Tools"

---

Build & install

git clone https://github.com/yourname/marlin.git
cd marlin
cargo build --release            # produces target/release/marlin

Copy the release binary somewhere on your PATH (optional):

sudo install -Dm755 target/release/marlin /usr/local/bin/marlin

---

Quick start

# 1 – create or upgrade the database (idempotent)
marlin init

# 2 – index all common folders in one shot
marlin scan ~/Pictures ~/Documents ~/Downloads ~/Music ~/Videos

# 3 – add a tag to matching files
marlin tag "~/Pictures/**/*.jpg" vacation

The database path defaults to:

~/.local/share/marlin/index.db         # Linux
~/Library/Application Support/marlin   # macOS
%APPDATA%\marlin\index.db              # Windows

Override with:

export MARLIN_DB_PATH=/path/to/custom.db

---

CLI reference

USAGE:
    marlin <COMMAND> [ARGS]

COMMANDS:
    init                              Create (or upgrade) the SQLite database
    scan <PATHS>...                   Walk one or more directories recursively
    tag  "<glob>" <tag>               Apply <tag> to all files matched

FLAGS:
    -h, --help                        Show this help
    -V, --version                     Show version info

Command	Notes
marlin init	Safe to run repeatedly; applies pending migrations.
marlin scan <PATHS>...	Accepts any number of absolute/relative paths. Directories you can’t read are skipped with a warning.
marlin tag "<glob>" <tag>	Quote the glob so your shell doesn’t expand it. Uses glob crate rules (** for recursive matches).

---

Upgrading to a new build

During development you’ll be editing source files frequently. Two common ways to run the updated program:

1. Run straight from the project directory

cargo run --release -- scan ~/Pictures

Cargo recompiles what changed and runs the fresh binary located in target/release/marlin.

2. Replace the global copy

If you previously installed Marlin (e.g. into ~/.cargo/bin/ or /usr/local/bin/), overwrite it:

cargo install --path . --force

Now which marlin should print the new location, and multi-path scan works:

marlin scan ~/Pictures ~/Documents …

If the CLI still shows the old single-path usage (Usage: marlin scan <PATH>), you’re invoking an outdated executable—check your PATH and reinstall.

---

Development tips

• Tight loop: cargo watch -x 'run -- scan ~/Pictures'
• Debug logs: RUST_LOG=debug marlin scan ~/Pictures
• Lint: cargo clippy --all-targets --all-features -D warnings
• Tests: cargo test

---

Roadmap

Milestone	Coming soon
M1	Hierarchical tags • attributes table • tags:// virtual folder
M2	Sync service • change log • diff viewer
M3	Natural-language search • visual query builder
M4	Plug-in marketplace • mobile companion (view-only)

---

License

Released under the MIT License – see LICENSE for full text.