fmeta

A find alternative that emits files with rich metadata — size, kind, encoding, mime, a coarse type hint — gitignore-aware, and designed to be easy for humans and AI agents to consume.

fmeta walks one or more directories and prints each visited file alongside detected metadata columns. Think of it as find crossed with a lightweight file: the same deterministic walk, but every line already carries the metadata you would otherwise have to spawn a second tool for.

Why

find lists paths. To know whether a file is text, what encoding it uses, or what mime type it has, you pipe into file, xdetect, or a script — once per entry, spawning a process for every file. fmeta does the walk and the detection in a single pass, so the output is immediately useful for:

• piping into awk / jq for filtering
• feeding an LLM agent a compact inventory of a tree
• auditing a directory for binary files or non-UTF-8 encodings

Install

Cargo

cargo install fmeta

Build from source

Requires Rust 1.74+.

git clone https://github.com/ljh-sh/fmeta
cd fmeta
cargo build --release
# binary: target/release/fmeta

Direct binary

Download a prebuilt binary from the releases page.

Usage

# Walk the current directory, emit one TSV row per file (default).
fmeta

# Limit depth, show hidden files, emit JSON Lines.
fmeta --max-depth 2 --all --format json path/to/dir

# Human-readable aligned table.
fmeta --format table path/to/dir

# Disable .gitignore filtering; show everything.
fmeta --no-ignore path/to/dir

# Skip detection entirely (paths only, fastest).
fmeta --paths-only path/to/dir

# Read more bytes per file for better detection accuracy.
fmeta --sniff 16384 path/to/dir

Output formats

TSV (default) — size kind encoding mime mime_hint path, tab-separated, no header. path is last so paths with spaces don't break awk/cut. The agent/pipeline format.

-	-	-	-	-	./src
12	file	UTF-8	-	text	./Cargo.toml
17	file	-	image/png	image	./logo.png

Table (--format table) — aligned columns (adds depth and dims) for human reading:

depth  size  kind  mime       encoding  mime_hint  dims     path
-----  ----  ----  ---------  --------  ---------  -------  ----
1      12    file  -          UTF-8     text       -        ./Cargo.toml
1      17    file  image/png  -         image      256x256  ./logo.png
1      -     dir   -          -         -          -        ./src

JSON Lines (--format json) — one object per line, stable schema, safe for jq, grep, or direct LLM consumption. Images additionally carry width, height, and an exif map:

{"path":"src/cli.rs","depth":1,"kind":"file","size":1684,"encoding":"UTF-8","binary":false,"category":"text"}
{"path":"logo.png","depth":1,"kind":"file","size":12345,"mime":"image/png","binary":true,"category":"image","width":256,"height":256}

Fields:

Options

Database mode

fmeta is also a file metadata database. Build an index of a tree, then query it with raw SQL — no re-walk, no jq.

# Index a tree into the default DB (~/.local/data/ljh-sh/fmeta/sqlite.db).
fmeta --index path/to/dir

# Re-indexing is incremental: files whose mtime is unchanged are skipped.
fmeta --index path/to/dir      # -> "indexed 3 (cached 2594)"

# Query with raw SQL (TSV output).
fmeta --sql "SELECT path,size FROM files WHERE category='image' ORDER BY size DESC LIMIT 20"
fmeta --sql "SELECT mime,count(*) FROM files GROUP BY mime ORDER BY 2 DESC"
fmeta --sql "SELECT path,pages FROM files WHERE pages > 100"

The schema is the files table — one row per indexed file (absolute path as primary key), columns mirror the fields above (size, mime, category, encoding, width, height, duration_secs, pages, tables, entries, mtime, ctime, …; exif/tags as JSON text). WAL mode enables concurrent readers. Use --db PATH to target a different DB.

Scope

In scope: directory traversal (gitignore-aware), rich per-file metadata (size/mime/encoding/image dims+EXIF/PDF pages/audio tags+duration/video dims+duration/Office props/archives/EPUB/SQLite tables/font/CSV cols/mtime/ctime), TSV + table + JSON output, and a global SQLite index (--index/--sql).

Out of scope (future): --prune (drop deleted files from index), parallel traversal, mkv/webm, network/remote files, parquet (→ duckdb). See docs/design.md for the roadmap.

License

Apache-2.0. See LICENSE.