select name, size where name = '*.rs'

The general shape of a query. The select keyword is implied — fselect is the select.

fselect [COLUMN, ...] [from PATH] [where CONDITION] [order by COLUMN] [limit N]

Find all JPEG files in your home directory. Dead simple.

$ fselect name from /home/user where name = '*.jpg'

Want to see the size too? Just add another column. Commas between columns are optional, by the way.

$ fselect size path from /home/user where name = '*.cfg' or name = '*.tmp'

No from? It searches the current directory.

$ fselect path, size where name = '*.jpg'

Human-readable file sizes with fsize (or hsize):

$ fselect fsize, path from /home/user where size gt 2g
$ fselect hsize, path from /home/user where size lt 8k

Size ranges with between:

$ fselect name, size from ./tmp where size between 5mb and 6mb

Find files by modification date. Supports natural language — today, yesterday, last fri, apr 1, you name it.

$ fselect path from /home/user where modified = today
$ fselect path from /home/user where accessed = yesterday
$ fselect path from /home/user where modified = 'last fri'
$ fselect path from /home/user where modified gte 2024-01-01

Get more specific with time intervals:

# everything created between 3PM and 4PM on May 1st
$ fselect path from /home/user where created = '2024-05-01 15'

# down to the minute
$ fselect path from /home/user where created = '2024-05-01 15:10'

Complex conditions with parentheses:

$ fselect "name from /tmp where (name = '*.tmp' and size = 0) or (name = '*.cfg' and size > 1000000)"

Boolean columns for common file types. No need to remember extensions — just ask!

$ fselect path from /home/user where is_image
$ fselect path from /home/user where is_video
$ fselect path from /home/user where is_doc
$ fselect path, mime from /home/user where is_audio
$ fselect path from /home/user where is_archive
$ fselect path from /home/user where is_source

Simple globs just work with = and !=:

$ fselect name from /home/user where path = '*Rust*'

Full regex support (Rust flavor) with the =~ operator:

$ fselect name from /home/user where path =~ '.*Rust.*'
$ fselect "name from . where path !=~ '^\./config'"

SQL-style LIKE patterns (% = any chars, _ = single char, ? = optional char):

$ fselect "path from /home/user where name like '%report-2024-__-__???'"

When you want exact matching (no glob expansion), use ===:

$ fselect "path from /home/user where name === 'some_*_literal_*_name'"

Search multiple directories, control depth, follow symlinks, and look inside archives:

# multiple search roots
$ fselect path from /home/user/old, /home/user/new where name = '*.jpg'

# limit depth per root
$ fselect path from /home/user depth 3, /tmp depth 1 where is_image

# min and max depth
$ fselect path from /home/user mindepth 2 maxdepth 5 where name = '*.jpg'

# follow symbolic links
$ fselect path, size from /home/user symlinks where name = '*.jpg'

# search inside zip archives
$ fselect path, size from /home/user archives where name = '*.jpg'

# combine everything
$ fselect size, path from /home/user depth 5 archives symlinks where name = '*.jpg' limit 100

# respect .gitignore
$ fselect size, path from /home/user/projects gitignore where name = '*.cpp'

Aggregate functions — get stats about your files. Curly braces work too, if that's your thing.

$ fselect "MIN(size), MAX{size}, AVG(size), SUM{size}, COUNT(*) from /home/user/Downloads"

String and formatting functions:

$ fselect "LOWER(name), UPPER(name), LENGTH(name), YEAR(modified) from /home/user/Downloads"

Year of the oldest file on your system? One-liner:

$ fselect "MIN(YEAR(modified)) from /home/user"

Include arbitrary text in your output:

$ fselect "name, ' has size of ', size, ' bytes'"

Group files by extension and count them:

$ fselect "ext, count(*) from /tmp group by ext"

Order results by size (descending), then by name:

$ fselect path from /tmp order by size desc, name

You can also order by column position:

$ fselect modified, fsize, path from ~ order by 1 desc, 3

Limit and offset — pagination for your filesystem:

$ fselect name from /home/user limit 10
$ fselect name from /home/user limit 10 offset 20

Search by image dimensions — find those wallpaper-quality photos:

$ fselect CONCAT(width, 'x', height), path from /home/user/photos where width gte 2000 or height gte 2000

Find perfectly square images:

$ fselect path from /home/user/Photos where width = height

Old-school rap at 320kbps? Say no more:

$ fselect duration, path from /home/user/music where genre = Rap and bitrate = 320 and mp3_year lt 2000

EXIF data — find photos from a specific camera:

$ fselect path, exif_make, exif_model from /home/user/photos where exif_make = 'Canon'

Find files with dangerous permissions:

$ fselect mode, path from /home/user where other_write or other_exec
$ fselect mode, path from /home/user where other_all

Glob or regex on permission strings:

$ fselect mode, path from /home/user where mode = '*rwx'
$ fselect mode, path from /home/user where mode =~ '.*rwx$'

Find files by owner, SUID, sticky bits:

$ fselect user, group, path from /home where user = mike
$ fselect name from /usr/bin where suid
$ fselect path from /tmp where is_sticky

Need to find files by their hash or check for duplicates?

$ fselect sha256, path from /home/user/downloads where name = '*.iso'

Search files by content:

$ fselect path from /home/user/src where contains('TODO') and name = '*.rs'

This is where it gets powerful. Find files with sizes that match files in another directory:

$ fselect "name from /test1 where size in (select size from /test2)"

Find files that exist in production but NOT in backup:

$ fselect "name from /production where name not in (select name from /backup)"

Correlated subqueries with table aliases — check if directories have children:

$ fselect "path from /home/user as parent
  where is_dir and exists (
    select * from /home/user as child
    where child.dir = parent.path
  )"

Nested subqueries — go as deep as you need:

$ fselect "name from /dir1 where size > 100
  and size in (
    select size from /dir2 where name in (
      select name from /dir3 where modified in (
        select modified from /dir4 where size < 200
      )
    )
  )"

Pipe it, process it, display it — pick your format with into:

$ fselect size, path from /home/user limit 5 into json
$ fselect size, path from /home/user limit 5 into csv
$ fselect size, path from /home/user limit 5 into html

Check extended attributes, ACLs, and Linux capabilities:

$ fselect "path, has_xattrs, has_xattr(user.test), xattr(user.test) from /home/user"

# find files with specific ACL entries
$ fselect path, acl from /shared where has_acl

# find binaries with Linux capabilities
$ fselect path, caps from /usr/bin where has_caps

Fire up the REPL and explore interactively. No shell escaping headaches, command history, the works:

$ fselect -i
# now you're in interactive mode!

fselect> name, size from . where is_image
fselect> cd /home/user/photos
fselect> path where width > 1920
fselect> exit

Find the top 10 biggest source files, sorted by size:

$ fselect fsize, path from ~/projects where is_source order by size desc limit 10

Get a breakdown of file types in a directory:

$ fselect "ext, count(*), sum(size) from ~/Downloads group by ext order by 3 desc limit 20"

Find empty directories:

$ fselect path from /home/user where is_dir and is_empty

Find all files NOT in your backup by comparing two directories:

$ fselect "name, path, size from /data as data
  where not exists (
    select * from /backup as backup
    where backup.name = data.name
  )"

Disk usage stats for your downloads folder, as JSON:

$ fselect "ext, count(*), format_size(sum(size), '%.1 ds') from ~/Downloads group by ext order by sum(size) desc limit 10 into json"

Find scripts (files starting with a shebang) that aren't executable:

$ fselect mode, path from /home/user/scripts where is_shebang and not user_exec

Photos taken with a Canon at ISO 100 with wide aperture, sorted by date:

$ fselect "exif_dto, exif_f_num, exif_iso, path from ~/photos
  where exif_make = 'Canon' and exif_iso = 100 and exif_f_num < 2.8
  order by exif_dto desc"