mirror of
https://github.com/PR0M3TH3AN/Marlin.git
synced 2025-09-08 15:18:44 +00:00
185 lines
5.5 KiB
Markdown
185 lines
5.5 KiB
Markdown
|
||
|
||
# Marlin
|
||
|
||
**Marlin** is a lightweight, metadata-driven file indexer that runs entirely on
|
||
your computer.
|
||
It scans folders, stores paths and file stats in SQLite, lets you add
|
||
hierarchical **tags** and **custom attributes**, takes automatic snapshots, and
|
||
offers instant full-text search with FTS5.
|
||
Nothing ever leaves your machine.
|
||
|
||
---
|
||
|
||
## Feature highlights
|
||
|
||
| Area | What you get |
|
||
|----------------|---------------------------------------------------------------------------------|
|
||
| **Safety** | Timestamped backups `marlin backup` and one-command restore `marlin restore` |
|
||
| **Upgrades** | Automatic schema migrations + dynamic column adds |
|
||
| **Indexing** | Fast multi-path scanner (WAL mode) |
|
||
| **Metadata** | Hierarchical tags (`project/alpha`) & key-value attributes (`reviewed=yes`) |
|
||
| **Search** | Prefix-aware FTS5, optional `--exec` action per hit |
|
||
| **DX / Logs** | Readable tracing (`RUST_LOG=debug …`) |
|
||
|
||
---
|
||
|
||
## How it works
|
||
|
||
```text
|
||
┌──────────────┐ marlin scan ┌─────────────┐
|
||
│ your files │ ─────────────────────▶│ SQLite │
|
||
│ (any folder) │ │ files/tags │
|
||
└──────────────┘ tag / attr │ attrs / FTS │
|
||
▲ search / exec └──────┬──────┘
|
||
└────────── backup / restore ▼
|
||
timestamped snapshots
|
||
````
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
| Requirement | Why |
|
||
| ------------------ | -------------------------------------- |
|
||
| **Rust** ≥ 1.77 | Build toolchain (`rustup.rs`) |
|
||
| C build essentials | `gcc`, `make`, etc. for bundled SQLite |
|
||
|
||
*(Windows/macOS: let the Rust installer pull the matching build tools.)*
|
||
|
||
---
|
||
|
||
## Build & install
|
||
|
||
```bash
|
||
git clone https://github.com/yourname/marlin.git
|
||
cd marlin
|
||
cargo build --release
|
||
# optional: add to PATH
|
||
sudo install -Dm755 target/release/marlin /usr/local/bin/marlin
|
||
```
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
marlin init # create DB
|
||
marlin scan ~/Pictures ~/Documents # index files
|
||
marlin tag "~/Pictures/**/*.jpg" photos/trip-2024 # add tag
|
||
marlin attr set "~/Documents/**/*.pdf" reviewed yes
|
||
marlin search reviewed --exec "xdg-open {}" # open hits
|
||
marlin backup # snapshot DB
|
||
```
|
||
|
||
### Database location
|
||
|
||
* **Linux** `~/.local/share/marlin/index.db`
|
||
* **macOS** `~/Library/Application Support/marlin/index.db`
|
||
* **Windows** `%APPDATA%\marlin\index.db`
|
||
|
||
Override:
|
||
|
||
```bash
|
||
export MARLIN_DB_PATH=/path/to/custom.db
|
||
```
|
||
|
||
---
|
||
|
||
## CLI reference
|
||
|
||
```text
|
||
marlin <COMMAND> [ARGS]
|
||
|
||
init create / migrate database
|
||
scan <PATHS>... walk directories & index files
|
||
tag "<glob>" <tag_path> add hierarchical tag
|
||
attr set|ls … manage custom attributes
|
||
search <query> [--exec CMD] FTS query, optionally run CMD on each hit
|
||
backup create timestamped snapshot in backups/
|
||
restore <snapshot.db> replace DB with snapshot
|
||
```
|
||
|
||
### Attribute subcommands
|
||
|
||
| Command | Example |
|
||
| ---------- | ------------------------------------------------ |
|
||
| `attr set` | `marlin attr set "~/Docs/**/*.pdf" reviewed yes` |
|
||
| `attr ls` | `marlin attr ls ~/Docs/report.pdf` |
|
||
|
||
---
|
||
|
||
## Backups & restore
|
||
|
||
* **Create snapshot**
|
||
|
||
```bash
|
||
marlin backup
|
||
# → ~/.local/share/marlin/backups/backup_2025-05-14_22-15-30.db
|
||
```
|
||
|
||
* **Restore snapshot**
|
||
|
||
```bash
|
||
marlin restore ~/.local/share/marlin/backups/backup_2025-05-14_22-15-30.db
|
||
```
|
||
|
||
Marlin automatically takes a safety backup before any schema migration.
|
||
|
||
---
|
||
|
||
## Upgrading to a new build
|
||
|
||
```bash
|
||
cargo install --path . --force # rebuild & overwrite installed binary
|
||
```
|
||
|
||
Backups + dynamic migrations mean your data is preserved across upgrades.
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
| Milestone | Focus |
|
||
| --------- | -------------------------------------------------- |
|
||
| **M1** | `tags://` virtual folder • attribute search DSL |
|
||
| **M2** | Real-time sync service • change-log diff viewer |
|
||
| **M3** | Natural-language query builder |
|
||
| **M4** | Plug-in marketplace • mobile (read-only) companion |
|
||
|
||
---
|
||
|
||
## Five-minute tutorial
|
||
|
||
```bash
|
||
# 0. Playground
|
||
mkdir -p ~/marlin_demo/{Projects/{Alpha,Beta},Media/Photos,Docs}
|
||
echo "Alpha draft" > ~/marlin_demo/Projects/Alpha/draft.txt
|
||
echo "Receipt PDF" > ~/marlin_demo/Docs/receipt.pdf
|
||
echo "fake jpg" > ~/marlin_demo/Media/Photos/vacation.jpg
|
||
|
||
# 1. Init & scan
|
||
marlin init
|
||
marlin scan ~/marlin_demo
|
||
|
||
# 2. Tags & attributes
|
||
marlin tag "~/marlin_demo/Projects/Alpha/**/*" project/alpha
|
||
marlin attr set "~/marlin_demo/**/*.pdf" reviewed yes
|
||
|
||
# 3. Search
|
||
marlin search alpha
|
||
marlin search reviewed --exec "echo Found: {}"
|
||
|
||
# 4. Snapshot & restore
|
||
marlin backup
|
||
marlin restore ~/.local/share/marlin/backups/backup_YYYY-MM-DD_HH-MM-SS.db
|
||
```
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT – see `LICENSE`
|
||
|
||
|