fselect Documentation

File: README.md Copy Chapter

fselect

Find files with SQL-like queries

Why use fselect? Copy Section

While it doesn't tend to fully replace traditional find and ls, fselect has these nice features:

• SQL-like (not real SQL, but highly relaxed!) grammar easily understandable by humans
• complex queries, compare results in several directories with subqueries
• aggregate, statistics, date, and other functions
• search within archives
• .gitignore, .hgignore, and .dockerignore support (experimental)
• search by width and height of images, EXIF metadata
• search by audio metadata (MP3, FLAC, Ogg Vorbis, Opus, M4A/AAC, WAV, AIFF, APE, WavPack, Musepack, Speex)
• search by extended file attributes, POSIX ACLs, and Linux capabilities
• search by file hashes
• search by MIME type
• shortcuts to common file types
• interactive mode
• support for plocate and Everything indexes for lightning-fast search
• various output formatting (CSV, JSON, and others)

More is under way!

Installation Copy Section

Latest release from source

• Install Rust with Cargo and its dependencies to build a binary
• Run cargo install fselect

You can optionally build with fast, index-backed search support: voidtools Everything
on Windows (--features everything, then pass --everything) or plocate
on Linux (--features plocate, then pass --plocate). See the
usage guide for details.

Debian/Ubuntu

deb package

Fedora/RHEL/openSUSE

rpm package

Arch Linux

AUR package, thanks to @asm0dey

AUR bin package, thanks to @4censord

NixOS

fselect in nixpkgs, thanks to @filalex77

Other Linux

• x86_64: glibc · musl (static)
• aarch64: glibc · musl (static)

Windows 64bit

A precompiled binary

Windows via winget

• Install winget
• Run winget install -e --id fselect.fselect

Windows via Chocolatey

• Install Chocolatey
• Run choco install fselect

Windows via Scoop

• Install Scoop
• Run scoop install fselect

macOS

Precompiled binaries are available at GitHub downloads (gunzip, then chmod +x fselect):

• Intel (x86_64)
• Apple Silicon (aarch64)

Mac via Homebrew

• Install brew
• Run brew install fselect

Mac via MacPorts

• Install MacPorts
• Run:
  text Copy

  sudo port selfupdate
  sudo port install fselect

Usage Copy Section

fselect [ARGS] COLUMN[, COLUMN...] [from ROOT[, ROOT...]] [where EXPR] [group by COLUMNS] [having EXPR] [order by COLUMNS] [limit N] [offset N] [into FORMAT]

Interactive mode Copy Section

fselect -i

Documentation Copy Section

Detailed description of all the supported features.

Examples Copy Section

Find temporary or config files (full path and size):

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

Windows users may omit the quotes:

fselect size, path from C:\Users\user where name = *.cfg or name = *.tmp

Or put all the arguments into the quotes like this:

fselect "name from /home/user/tmp where size > 0"

Search within a directory name with spaces (backticks are also supported):

fselect "name from '/home/user/dir with spaces' where size > 0"
fselect "name from `/home/user/dir with spaces` where size > 0"

Or simply escape the single quote:

fselect name from \'/home/user/dir with spaces\' where size gt 0

Specify the file size, get an absolute path, and add it to the results:

cd /home/user
fselect size, abspath from ./tmp where size gt 2g
fselect fsize, abspath from ./tmp where size = 5m
fselect hsize, abspath from ./tmp where size lt 8k
fselect name, size from ./tmp where size between 5mb and 6mb

More complex query:

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

You can use subqueries:

fselect "name from /test1 where size > 100 and size in (select size from /test2 where name in (select name from /test3 where modified in (select modified from /test4 where size < 200)))"
fselect "name, path, size from /data as data where exists (select * from /backup as backup where backup.name = data.name)"

A subquery can also be used in the FROM clause as the source of the outer query:

fselect "src.name, src.size from (select path from /projects depth 2 where size > 100) as src where src.name like '%.rs'"

Aggregate functions (you can use curly braces if you want and even combine them with the regular parentheses):

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

Formatting functions:

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

Get the year of the oldest file:

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

Use single quotes if you need to address files with spaces:

fselect "path from '/home/user/Misc stuff' where name != 'Some file'"

Regular expressions of Rust flavor are supported:

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

Negate regular expressions:

fselect "name from . where path !=~ '^\./config'"

Simple globs expand automatically and work with = and != operators:

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

Classic LIKE:

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

Exact match operators to search with regexps disabled:

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

Find files by date:

fselect path from /home/user where created = 2017-05-01
fselect path from /home/user where modified = today
fselect path from /home/user where accessed = yesterday
fselect "path from /home/user where modified = 'apr 1'"
fselect "path from /home/user where modified = 'last fri'"

Be more specific to match all files created at an interval between 3PM and 4PM:

fselect path from /home/user where created = '2017-05-01 15'

And even more specific:

fselect path from /home/user where created = '2017-05-01 15:10'
fselect path from /home/user where created = '2017-05-01 15:10:30'

Date and time intervals are possible (find everything updated since May 1st):

fselect path from /home/user where modified gte 2017-05-01

Default is the current directory:

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

Search within multiple locations:

fselect path from /home/user/oldstuff, /home/user/newstuff where name = '*.jpg'

With minimum and/or maximum depth specified (depth is a synonym for maxdepth):

fselect path from /home/user/oldstuff depth 5 where name = '*.jpg'
fselect path from /home/user/oldstuff mindepth 2 maxdepth 5, /home/user/newstuff depth 10 where name = '*.jpg'

Optionally follow symlinks:

fselect path, size from /home/user symlinks where name = '*.jpg'

Search within archives (currently only zip-archives are supported):

fselect path, size from /home/user archives where name = '*.jpg'

Or in combination:

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

Enable .gitignore or .hgignore support:

fselect size, path from /home/user/projects gitignore where name = '*.cpp'
fselect size, path from /home/user/projects git where name = '*.cpp'    
fselect size, path from /home/user/projects hgignore where name = '*.py'

Search by image dimensions:

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

Find square images:

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

Find images with a known name part but unknown extension:

fselect path from /home/user/projects where name = "*RDS*" and width gte 1

Find old-school rap MP3 files:

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

Shortcuts to common file extensions:

fselect path from /home/user where is_archive = true
fselect path, mime from /home/user where is_audio = 1
fselect path, mime from /home/user where is_book != false

Even simpler way of using boolean columns:

fselect path from /home/user where is_doc
fselect path from /home/user where is_image
fselect path from /home/user where is_video

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

Simple glob-like expressions or even regular expressions in file mode are possible:

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

Find files by owner's uid or gid:

fselect uid, gid, path from /home/user where uid != 1000 or gid != 1000

Or by owner's or group's name:

fselect user, group, path from /home/user where user = mike or group = mike

Find special files:

fselect name from /usr/bin where suid
fselect path from /tmp where is_sticky
fselect path from /tmp where is_pipe
fselect path from /tmp where is_socket

Find files with xattrs, check if a particular xattr exists, or get its value:

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

Include arbitrary text as columns:

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

Group results:

fselect "ext, count(*) from /tmp group by ext"
fselect "ext, count(*) from /tmp group by 1"
fselect "mime, ext, count(*) from /tmp group by 1, 2"

Filter groups after aggregation:

fselect "ext, count(*) from /tmp group by ext having count(*) > 10"
fselect "sha256, count(*) from ~/Downloads group by sha256 having count(*) > 1"

Order results:

fselect path from /tmp order by size desc, name
fselect modified, fsize, path from ~ order by 1 desc, 3

Finally, limit the results:

fselect name from /home/user/samples limit 5

Format output:

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

License Copy Section

MIT/Apache-2.0

Supported by JetBrains IDEA open source license

File: docs/usage.md Copy Chapter

fselect

Find files with SQL-like queries.

Basic usage
Restrictions
Columns and fields
File naming terminology
Functions
File size units
Search roots
Operators
Arithmetic operators
Subqueries in the FROM clause
Subqueries for IN and EXISTS
Date and time specifiers
Regular expressions
MIME and file types
Audio support
File hashes
Output formats
Configuration file
Bash completion
Command-line arguments
Index-backed search
Interactive mode
Environment variables
Exit values

Basic usage Copy Section

fselect [ARGS] COLUMN[, COLUMN...] [from ROOT[, ROOT...]] [where EXPR] [group by COLUMNS] [having EXPR] [order by COLUMNS] [limit N] [offset N] [into FORMAT]

You write an SQL-like query, that's it.

fselect command itself is like a first keyword (select, i.e., file select).
But if you put one more select behind occasionally, that's not a problem.

Next you put columns you are interested in. It could be a file name or path, size, modification date, etc.
See the full list of possible columns. You can add columns with arbitrary text (put in quotes if it contains spaces).
A few functions (aggregating and formatting) are there for your service. You can use arithmetic expressions when it makes sense.

Where to search? Specify with from keyword. You can list one or more directories separated with comma.
If you leave the from, then current directory will be processed.

What to search? Use where with any number of conditions.

Group results with group by followed by one or more columns. Like order by, this clause
accepts positional numeric shortcuts that refer to columns from the select list, for example
group by 1 or group by 1, 2. An aggregate function in the select list is not required:
select ext from /home/user group by ext returns one row per distinct extension, like
SELECT DISTINCT in SQL.

Filter the groups themselves with having, which runs after aggregation
(while where filters individual files before it):

fselect ext, count(*) from /home/user group by ext having count(*) > 10
fselect "ext, sum(size) from /home/user group by ext having sum(size) > 100mb"
fselect "ext, count(*) as c from /home/user group by ext having c > 10 order by c desc"
fselect "sha256, count(*) from /home/user/Downloads group by sha256 having count(*) > 1"

A having condition may use aggregate functions (even ones not in the select list),
grouping columns, select-list aliases, and and/or/not logic. Referencing a
non-grouping column outside an aggregate is an error, as in SQL. With aggregation but no
group by, the whole result set forms one implicit group, and having decides whether the
single result row is returned at all. Subqueries (in, exists) are not supported inside
having yet.

Order results like in real SQL with order by. All columns are supported for ordering by,
as well as asc/desc parameters and positional numeric shortcuts.

Limiting search results is possible with limit and offset. Formatting options are supported with into keyword.

If you want to use operators containing > or <,
put the whole query into the double quotes.
This will protect a query from the shell and output redirection.
The same applies to queries with parentheses or *, ? and other special shell
metacharacters.

It's ok to use any metacharacters in interactive mode.

It's not a real SQL Copy Section

Directories to search at are listed with comma separators.
In a real SQL, such syntax would make a cross-product. Here it means just search at A, next at B, and so on.

You can use curly braces instead of the regular parentheses! This helps to avoid a few of the shell pitfalls a little bit.
Functions with no arguments don't require parentheses at all.

String literals don't really need quotes.
You will need to put them just in case you query something with spaces inside.
And yes, you should use quotes for glob-patterns or regular expressions in the query
on Linux or macOS to prevent parameter expansion from the shell.
If you are on Windows, feel free to omit most of the quotes.

Commas for column separation aren't needed as well. Column aliasing (with or without as keyword) is not supported.

where section can contain short syntax conditions for boolean columns (like is_audio or other_write).

into keyword specifies output format, not output table.

Joins and unions are not supported (yet?).
Subqueries have only limited support: in IN / EXISTS predicates, and as the source of a FROM clause.

Columns and fields Copy Section

File naming terminology Copy Section

Let's see how all these are different:

fselect abspath, absdir, path, dir, name, filename, ext from /home/user/projects where is_file

Functions Copy Section

Aggregate functions

Queries using these functions return only one result row.

Date functions

Used mostly for formatting results.

User functions

These are only available on Unix platforms when users feature has been enabled during compilation.

Xattr functions

Used to check if a particular xattr exists or to get its value.
Supported platforms are Linux, macOS, FreeBSD, and NetBSD.

ACLs

fselect can read and display Access Control Lists on both Linux and Windows.

POSIX ACLs (Linux)

On Linux, fselect reads POSIX Access Control Lists stored as system.posix_acl_access or system.posix_acl_default
extended attributes. It is useful for auditing file permissions beyond the standard Unix owner/group/other model.

The has_acl field returns true when a file has extended ACL entries (named users, named groups,
or a mask entry) beyond the basic owner/group/other permissions.

The acl field returns all ACL entries in standard getfacl-like format, comma-separated:
user::rwx,user:john:rw-,group::r-x,group:staff:r--,mask::rwx,other::r--

Use has_acl_entry and acl_entry to query specific entries. The entry specifier uses the format
type:qualifier where type is user (or u), group (or g), mask (or m), or other (or o).
An empty qualifier refers to the owning user/group. Examples:

fselect name from /data where has_acl = true
fselect "name, acl from /data where has_acl = true"
fselect "name from /data where has_acl_entry('user:john')"
fselect "name, acl_entry('group:staff') from /data"

When the users feature is enabled, uid/gid values are resolved to usernames/group names.
Otherwise, numeric IDs are used in the output.

Windows DACLs

On Windows, fselect reads the Discretionary Access Control List (DACL) via the Win32 Security API.
Only explicit (non-inherited) ACEs are shown.

The has_acl field returns true when a file has at least one explicit (non-inherited) ACE in its DACL.

The acl field returns all explicit ACEs as comma-separated entries in the format
type:trustee:permissions, where:

• type is allow or deny
• trustee is the resolved account name (e.g., BUILTIN\Administrators, NT AUTHORITY\SYSTEM)
• permissions is one of full, modify, rx, read, write, or a hex value for non-standard masks

Example output: allow:BUILTIN\Administrators:full,allow:NT AUTHORITY\SYSTEM:full,allow:BUILTIN\Users:rx

The default_acl and has_default_acl fields report a directory's inheritable ACEs (those
carrying the object- or container-inherit flag), which are the Windows analogue of POSIX default
ACLs — the entries that propagate to newly created child objects.

Use has_acl_entry and acl_entry (and their default_acl_entry counterparts) to query a
single trustee. The argument is matched against the trustee either as a full DOMAIN\Name or as
a bare account name, case-insensitively:

fselect name from C:\ where has_acl = true
fselect "name, acl from C:\Users where has_acl = true"
fselect "name, default_acl from C:\Windows where is_dir = true"
fselect "name from C:\data where has_acl_entry('Administrators')"
fselect "name, acl_entry('BUILTIN\Users') from C:\data"

Extended file attributes

fselect can read and query extended file attributes (also known as file flags). On Linux these
are the flags managed with chattr and displayed with lsattr, read via the FS_IOC_GETFLAGS
ioctl on ext2/ext3/ext4, btrfs, and other supporting filesystems. On Windows these are the NTFS
file attributes.

On Linux the extattrs field returns a string of flag letters for each set attribute, using the
same single-letter codes as lsattr/chattr:
s (secure deletion), u (undelete), c (compress), S (synchronous updates),
i (immutable), a (append only), d (no dump), A (no atime updates),
E (encrypted), I (indexed directory), j (journal data), t (no tail-merging),
D (dirsync), T (top of directory hierarchy), e (extents), V (verity),
C (no copy-on-write), x (DAX), N (inline data), P (project hierarchy),
F (case-insensitive directory).

On Windows the extattrs field returns a string of letters for each set NTFS attribute
(letters follow the attrib command where applicable):
R (read-only), H (hidden), S (system), A (archive), T (temporary),
P (sparse file), L (reparse point), C (compressed), O (offline),
I (not content indexed), E (encrypted), V (integrity stream).
Note that the Windows letters are case-sensitive (all upper-case).

The has_extattrs field returns true when any of these attributes are set.
Use the has_extattr() function to check for a specific flag:

fselect name from / where has_extattrs = true
fselect "name, extattrs from /data where has_extattrs = true"
fselect "name from / where has_extattr('i')"
fselect "name, extattrs from C:\data where has_extattr('H')"

String functions

Used mostly for formatting results.

Japanese string functions

Used for detecting Japanese symbols in file names and such.

Greek string functions

Used for detecting Greek symbols in file names and such.

Other functions

Let's try FORMAT_SIZE with different format specifiers:

File size units Copy Section

fselect size, path from /home/user/tmp where size gt 2g
fselect fsize, path from /home/user/tmp where size = 5mib
fselect hsize, path from /home/user/tmp where size lt 8kb

Search roots Copy Section

path [option N] [option] [option] [option...][, path2 [option...]]

When you put a directory to search at, you can specify some options.

Operators Copy Section

• = or == or eq
• != or <> or ne
• === or eeq
• !== or ene
• > or gt
• >= or gte or ge
• < or lt
• <= or lte or le
• =~ or ~= or regexp or rx
• !=~ or !~= or notrx
• like
• notlike
• between
• in
• exists

Arithmetic operators Copy Section

Subqueries in the `FROM` clause Copy Section

The FROM clause can take a parenthesized inner query in place of (or alongside) a filesystem path.
The inner query is executed first, and the rows it produces become the input set the outer query
iterates over — its WHERE, SELECT, LIMIT, and ORDER BY clauses then run against that set
without any further directory traversal.

select name from (select * from /projects depth 2)

You can attach options like an alias to the subselect root just like a regular root:

select src.name, src.size from (select path from /projects depth 2) as src where src.size > 1024

A WHERE clause inside the subselect filters the input set; a WHERE clause outside filters the
outer rows produced from that input set:

select name from (select path from /projects depth 2 where size > 100) where name like '%.rs'

Subselects may be nested.

Subqueries for `IN` and `EXISTS` Copy Section

Subqueries in fselect allow you to nest queries within queries, enabling powerful file search operations that compare results across different directory trees.
Subqueries can be used with the IN, NOT IN, EXISTS, and NOT EXISTS operators to create sophisticated filtering logic.

Important: When using subqueries that need to reference the parent query's results, you must bind search roots using aliases with the AS keyword.
This creates a correlated subquery where the inner query can reference columns from the outer query.

[!CAUTION]
This feature is still in development. Random queries can fail for no obvious reason.

General Subquery Syntax

SELECT columns FROM root AS alias
WHERE column operator (SELECT columns2 FROM root2 AS alias2 WHERE condition)

Supported Operators

• IN - Tests if a value exists in the subquery result set
• NOT IN - Tests if a value does not exist in the subquery result set
• EXISTS - Tests if the subquery returns any rows
• NOT EXISTS - Tests if the subquery returns no rows

`IN` Operator

The IN operator checks if a value from the outer query matches any value returned by the subquery.

Example: Find files in /backup that have the same size as files in /production:

select name, size from /backup 
where size in (select size from /production)

Example: Find files with multiple levels of correlation:

select name from /test1 
where size > 100 and size in (
  select size from /test2 
  where name in (
    select name from /test3 
    where modified in (
      select modified from /test4 
      where size < 200
    )
  )
)

This query finds files in /test1 where:

1. Size is greater than 100 bytes
2. Size matches files in /test2
3. Those /test2 files have names matching files in /test3
4. Those /test3 files have modification times matching files in /test4 (smaller than 200 bytes)

Example: Find files in /home/user/docs where the filename appears in subdirectories with the same extension:

select name, path from /home/user/docs as parent
where name in (
  select name from /home/user/docs/archive as child
  where child.ext = parent.ext
)

The as parent and as child aliases allow the subquery to reference the outer query's ext column.

`NOT IN` Operator

The NOT IN operator checks if a value from the outer query does NOT match any value in the subquery.

Example: Find files in /current that don't exist in /backup (by name):

select name, path from /current
where name not in (select name from /backup)

Example: Find config files that exist in production but not in staging:

select name, path from /production/config as prod
where name not in (
  select name from /staging/config where ext = 'cfg'
)

Example: Find files unique to a directory by both name and size:

select name, size, path from /home/user/projects as proj
where name not in (
  select name from /home/user/archive as arch
  where arch.size = proj.size
)

Important Note: NOT IN can produce unexpected results if the subquery returns any NULL/empty values.
When in doubt, use NOT EXISTS instead (see below).

`EXISTS` Operator

The EXISTS operator returns true if the subquery returns at least one row.
It's often more efficient than IN and handles NULL/empty values better.

Example: Find directories that contain image files:

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

Example: Find files in /data that have a backup in /backup with the same name:

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

Example: Find directories that have been modified recently (contain files modified in the last 7 days):

select path from /home/user/projects gitignore as proj
where is_dir 
  and exists (
      select * from /home/user/projects as files
      where is_file 
        and files.dir = proj.abspath 
        and files.modified >= 'last week'
  )

`NOT EXISTS` Operator

The NOT EXISTS operator returns true if the subquery returns zero rows. This is the safest way to check for non-matching data.

Example: Find files in /production that don't have a backup:

select name, path from /production as prod
where not exists (
  select * from /backup as backup
  where backup.name = prod.name
)

Example: Find files in /cache that don't have corresponding source files:

select name, path from /cache as cache
where not exists (
  select * from /source as source
  where source.name = cache.name
    and source.size > 0
)

Example: Find source files that have no corresponding test files:

select name, path from /home/user/src as src
where ext = 'rs' and not exists (
  select * from /home/user/tests as tests
  where tests.name like concat(src.name, '_test%')
    and tests.ext = 'rs'
)

Unix timestamps Copy Section

The atime, mtime, and ctime fields return raw Unix timestamps (seconds since epoch) as integers.
These are available only on Unix platforms and are useful when you need numeric comparison
or want to pass exact values to external tools.

fselect name, mtime from /home/user/projects
fselect name, atime from /home/user where atime gt 1700000000
fselect "name, format_time(mtime) from /home/user"
fselect "name, day(accessed), mtime from /home/user"

Unlike accessed, modified, and created which return formatted date/time strings,
these fields return the raw integer value from the filesystem metadata.

The companion atime_nsec, mtime_nsec, and ctime_nsec fields return the sub-second
nanosecond component of the respective timestamp, for cases where second-level precision
is not enough.

fselect name, mtime, mtime_nsec from /home/user/projects

Git fields Copy Section

The git fields look up the repository containing each file (the nearest enclosing work tree)
and report per-file information. git_status returns one of clean, modified, staged,
untracked, conflicted, or ignored. The git_last_commit_* fields walk the repository
history to find the last commit that touched the file, like git log -1 -- path, so they are
relatively expensive on large histories.

fselect name, git_status from /home/user/projects/repo where git_status = modified
fselect path from /home/user/projects/repo where is_git_tracked = false and is_gitignored = false
fselect name, git_last_commit_date, git_last_commit_author from src
fselect path, git_branch from /home/user/projects where is_git_repo = true depth 2

is_git_repo simply checks for a .git subdirectory (or file) and is available in every build.
All other git fields require the git feature (enabled by default).

Date and time specifiers Copy Section

When you specify inexact date and time with = or != operator, fselect understands it as an interval.

fselect path from /home/user where modified = 2017-05-01

2017-05-01 means all day long from 00:00:00 to 23:59:59.

fselect path from /home/user where modified = '2017-05-01 15'

2017-05-01 15 means one hour from 15:00:00 to 15:59:59.

fselect path from /home/user where modified ne '2017-05-01 15:10'

2017-05-01 15:10 is a 1-minute interval from 15:10:00 to 15:10:59.

Other operators assume the exact date and time, which could be specified in a freer way:

fselect "path from /home/user where modified === 'apr 1'"
fselect "path from /home/user where modified gte 'last fri'"
fselect path from /home/user where modified gte '01/05'

Or simply use relative offsets as days:

fselect created, path from /home/user where created gte -2

More about writing dates in plain English

fselect uses UK locale by default, not American style dates, i.e. 08/02 means February 8th by default.

To change this behavior, supply --us-dates option to the fselect command, or put us_dates = true into the configuration file.

The safest way to specify dates is to use ISO 8601 format: YYYY-MM-DD HH:MM:SS.

Regular expressions Copy Section

Rust flavor regular expressions are used.

MIME and file types Copy Section

For MIME guessing use field mime. It returns a simple string with a deduced MIME type,
which is not always accurate.

fselect path, mime, is_binary, is_text from /home/user

is_binary and is_text return true or false based on MIME type detected.
Once again, this should not be considered as a 100% accurate result,
or even possible at all to detect a correct file type.

Other fields listed below do NOT use MIME detection.
Assumptions are being made based on file extension.

The lists below could be edited with the configuration file.

fselect is_archive, path from /home/user
fselect is_audio, is_video, path from /home/user/multimedia
fselect path from /home/user where is_doc != 1
fselect path from /home/user where is_image = false
fselect path from /home/user where is_video != true

Audio support Copy Section

fselect reads audio metadata via lofty, so it can search by
bitrate, sampling frequency, title, artist, album, genre, year, comment, track, and disc number across
many formats: MP3, FLAC, Ogg Vorbis, Opus, M4A/AAC/ALAC, WAV, AIFF, APE, WavPack, Musepack, and Speex.

Duration is measured in seconds.

fselect duration, bitrate, path from /home/user/music
fselect mp3_year, album, title from /home/user/music where artist like %Vampire% and bitrate gte 320
fselect bitrate, freq, path from /home/user/music where genre = Rap or genre = HipHop
fselect path, title, artist from /home/user/music where ext in (flac, opus, m4a)

File hashes Copy Section

fselect path, sha256, 256 from /home/user/archive limit 5
fselect path from /home/user/Download where sha1 like cb23ef45%

Output formats Copy Section

... into FORMAT

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
fselect path from /home/user into list | xargs -0 grep foobar

Configuration file Copy Section

fselect tries to create a new configuration file if one doesn't exist.

Usual location on Linux:

/home/user_name/.config/fselect/config.toml

On Windows:

C:\Users\user_name\AppData\Roaming\jhspetersson\fselect\config.toml

Fresh config is filled with defaults, feel free to update it.

If no config on the standard paths is found, fselect checks its presence next to the executable.
You can also specify a config location with a runtime option, e.g.:

fselect --config /home/user_name/fselect_custom.toml name, size from /home/user_name/Music where is_audio = 1

Check for updates

fselect can be built with update-notifications feature, that enables automatic check for updates.
This check is disabled by default. To enable it, put

check_for_updates = true

into the config file.

Bash completion Copy Section

fselect comes with a bash completion script (fselect-completion.bash) that provides tab completion for:

• Directory paths after the from keyword
• Output formats after the into keyword
• Fields and functions in other contexts

To enable bash completion for fselect, you need to install the completion script. The installation method varies depending on your Linux distribution:

Ubuntu/Debian and Red Hat/Fedora/CentOS

1. Copy the completion script to the bash completion directory:

sudo cp fselect-completion.bash /etc/bash_completion.d/fselect

2. Make the script executable:

sudo chmod +x /etc/bash_completion.d/fselect

3. Source the script or restart your shell:

source /etc/bash_completion.d/fselect

Arch Linux

1. Copy the completion script to the bash completion directory:

sudo cp fselect-completion.bash /usr/share/bash-completion/completions/fselect

2. Make the script executable:

sudo chmod +x /usr/share/bash-completion/completions/fselect

3. Source the script or restart your shell:

source /usr/share/bash-completion/completions/fselect

Manual installation (any Linux distribution)

If your distribution doesn't have a standard location for bash completion scripts, or if you don't have root access, you can install the script in your home directory:

1. Create a directory for bash completion scripts if it doesn't exist:

mkdir -p ~/.bash_completion.d

2. Copy the completion script to this directory:

cp fselect-completion.bash ~/.bash_completion.d/fselect

3. Make the script executable:

chmod +x ~/.bash_completion.d/fselect

4. Add the following line to your ~/.bashrc file:

source ~/.bash_completion.d/fselect

5. Source your ~/.bashrc file or restart your shell:

source ~/.bashrc

Command-line arguments Copy Section

Index-backed search (Everything / plocate) Copy Section

fselect can optionally use an external file-name index as the source of candidate paths instead
of walking the filesystem. Because these indexes are prebuilt, enumerating a large directory tree is
typically much faster. Two backends are supported, each behind an opt-in build feature:

• Everything (Windows) — the voidtools Everything engine, via its
  client DLL. Enable with the everything feature and the --everything flag.
• plocate (Linux) — the plocate locate replacement, invoked as a
  subprocess. Enable with the plocate feature and the --plocate flag.

# Windows
cargo build --release --features everything
fselect --everything "name, size from C:\Users where size gt 100mb"

# Linux
cargo build --release --features plocate
fselect --plocate "name, size from /home where size gt 100mb"

Both backends behave the same way:

• They can also be enabled via the configuration file (everything = true / plocate = true).
• If the backend is unavailable — Everything not running / DLL missing, or the plocate binary or
  its database missing — fselect transparently falls back to normal traversal.
• mindepth/maxdepth (and depth) constraints are applied to the index results.
• The where/order by/select logic, functions, and all fields work exactly as with traversal —
  the index only supplies the candidate paths.
• Options that require reading the filesystem structure — searching archives, or applying
  .gitignore/.hgignore/.dockerignore filters — automatically use normal traversal instead.
• Locations the index does not cover (for example, some network drives, or a stale plocate
  database) will return no results in this mode.

Interactive mode Copy Section

In interactive mode, you can:

• execute queries directly without calling fselect every time
• use any characters without escaping them from the shell
• run multiple searches sequentially without restarting the tool
• edit and refine queries iteratively
• use command history (up/down arrows) to recall previous queries
• get current directory with pwd and change it with cd
• suppress error reporting with errors off
• exit with quit, exit, Ctrl+C or Ctrl+D

Environment variables Copy Section

fselect respects NO_COLOR environment variable.

Exit values Copy Section