mirror of
https://github.com/PR0M3TH3AN/Marlin.git
synced 2025-09-09 15:48:43 +00:00
145 lines
4.4 KiB
Markdown
145 lines
4.4 KiB
Markdown
# Marlin Usage Tutorial
|
||
|
||
Below is a hands-on lab you can run in a throw-away directory.
|
||
It shows how Marlin’s **tags** give you cross-folder “links” that a plain Bash
|
||
workflow can’t match without resorting to symlinks or scratch scripts.
|
||
|
||
Everything uses *only the functionality that exists today* (`init / scan / tag`)
|
||
plus one `sqlite3` query for discovery.
|
||
|
||
---
|
||
|
||
## 0 . Prep
|
||
|
||
```bash
|
||
# make a playground so we don't touch real files
|
||
mkdir -p ~/marlin_demo/{Projects/{Alpha,Beta},Media/Photos,Docs}
|
||
cd ~/marlin_demo
|
||
```
|
||
|
||
### Create a handful of files
|
||
|
||
```bash
|
||
echo "Alpha draft" > Projects/Alpha/draft.txt
|
||
echo "Alpha final" > Projects/Alpha/final.txt
|
||
echo "Beta summary" > Projects/Beta/summary.md
|
||
echo "Budget spreadsheet" > Docs/budget.ods
|
||
echo "Scan of receipt" > Docs/receipt.pdf
|
||
echo "fake JPEG header" > Media/Photos/vacation001.jpg
|
||
echo "fake JPEG header" > Media/Photos/vacation002.jpg
|
||
```
|
||
|
||
---
|
||
|
||
## 1 . Initialise & scan
|
||
|
||
```bash
|
||
marlin init
|
||
marlin scan ~/marlin_demo
|
||
```
|
||
|
||
*What happened?*
|
||
Marlin walked every file under `~/marlin_demo` and upserted rows into `files`.
|
||
|
||
---
|
||
|
||
## 2 . Tagging – adding cross-folder metadata
|
||
|
||
### Tag Alpha project files
|
||
|
||
```bash
|
||
marlin tag "~/marlin_demo/Projects/Alpha/**/*.txt" project-alpha
|
||
```
|
||
|
||
### Tag everything Markdown or ODS as **docs**
|
||
|
||
```bash
|
||
marlin tag "~/marlin_demo/**/*.md" docs
|
||
marlin tag "~/marlin_demo/**/*.ods" docs
|
||
```
|
||
|
||
### Tag photos
|
||
|
||
```bash
|
||
marlin tag "~/marlin_demo/Media/Photos/**/*.jpg" photos
|
||
```
|
||
|
||
You can layer tags—`vacation001.jpg` now has both `photos` and (later) `trip-2024`
|
||
if you choose to add that.
|
||
|
||
---
|
||
|
||
## 3 . Discovering files with plain SQL
|
||
|
||
There’s no `marlin search` command *yet*, but the DB is just SQLite:
|
||
|
||
```bash
|
||
sqlite3 ~/.local/share/marlin/index.db <<'SQL'
|
||
.headers on
|
||
.mode column
|
||
|
||
-- show all files tagged 'docs'
|
||
SELECT path
|
||
FROM files f
|
||
JOIN file_tags ft ON ft.file_id = f.id
|
||
JOIN tags t ON t.id = ft.tag_id
|
||
WHERE t.name = 'docs';
|
||
SQL
|
||
```
|
||
|
||
Expected output:
|
||
|
||
```
|
||
path
|
||
--------------------------------------------------------------
|
||
/home/user/marlin_demo/Projects/Beta/summary.md
|
||
/home/user/marlin_demo/Docs/budget.ods
|
||
```
|
||
|
||
Do the same for `project-alpha`:
|
||
|
||
```bash
|
||
sqlite3 ~/.local/share/marlin/index.db "
|
||
SELECT path FROM files
|
||
JOIN file_tags USING(file_id)
|
||
JOIN tags USING(tag_id)
|
||
WHERE tags.name = 'project-alpha';
|
||
"
|
||
```
|
||
|
||
---
|
||
|
||
## 4 . Why this beats a pure Bash approach
|
||
|
||
| Task | With Bash alone | With Marlin tags |
|
||
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||
| Gather every Alpha file (any extension) scattered across sub-folders | `find ~/Projects -path '*Alpha*'` (works) but blows up if naming scheme changes | One-time glob + `marlin tag ... project-alpha`, then just query by tag. |
|
||
| Re-classify files later | Mass-rename or new `find`/`grep` pipeline | `marlin tag` new glob or manual ad-hoc files; DB keeps history (future). |
|
||
| Combine orthogonal facets e.g. “docs AND project-alpha” | Complex `find` piped to `grep -F -f list.txt` or symlink forest | Future `marlin search docs AND project-alpha` (for now SQL query). |
|
||
| Persist metadata when files move | Must update symlinks / scripts | Scanner sees the move (once watcher lands); tags stay attached by inode/hash. |
|
||
|
||
Think of tags as **Git branches for files**—cheap, many-to-many, roam across
|
||
directories, and live in one place.
|
||
|
||
---
|
||
|
||
## 5 . Cleaning up
|
||
|
||
```bash
|
||
rm -rf ~/marlin_demo
|
||
sqlite3 ~/.local/share/marlin/index.db "DELETE FROM files; DELETE FROM tags; DELETE FROM file_tags;"
|
||
```
|
||
|
||
*(or simply delete the DB file to start fresh).*
|
||
|
||
---
|
||
|
||
### Recap
|
||
|
||
1. **Scan** every folder once.
|
||
2. **Tag** by glob to create semantic “links.”
|
||
3. **Query** the DB (today) or use future built-in search (soon).
|
||
|
||
Even with just these three commands, you get an index that answers questions
|
||
plain Bash would need an ever-growing tangle of `find`, `grep`, and symlinks to solve.
|