FSELECT(1)

NAME
fselect - find files with SQL-like queries

SYNOPSIS
fselect [--nocolor] [--no-errors] [--us-dates] [--config FILE]

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

fselect -i

DESCRIPTION
fselect is a command-line utility for finding files using an SQL-like query language. The fselect command itself acts as the select keyword (i.e., file select). An optional select keyword at the beginning of the query is accepted but not required.

Query columns may be file attributes, arbitrary string literals (quoted if they contain spaces), function calls, or arithmetic expressions.

If from is omitted, the current directory is searched. Multiple search roots may be listed, separated by commas. Each root may have its own set of options (depth, symlinks, archives, etc.).

Queries containing >, <, parentheses, or shell metacharacters such as * and ? should be enclosed in double quotes to prevent shell interpretation.

Commas between column names are optional. String literals do not need quotes unless they contain spaces or shell metacharacters. Functions with no arguments do not require parentheses. Curly braces may be used instead of parentheses.

OPTIONS

--interactive, -i
    Run in interactive mode.

--config FILE
    Specify an alternative configuration file location.

--nocolor, --no-color
    Disable colorized output.

--no-errors
    Suppress error messages.

--us-dates
    Interpret ambiguous dates in US format (MM/DD) instead of the default UK format (DD/MM).

--help, -h
    Show help and exit.

COLUMNS AND FIELDS

  File naming

name
    File name with extension.

filename or fname
    File name without extension.

extension or ext
    File extension only (without the leading dot).

path
    Path relative to the search root.

abspath
    Absolute path of the file.

directory or dirname or dir
    Directory portion of the path, relative to the search root.

absdir
    Absolute directory portion of the path.

link_target or symlink_target
    Target path of the symlink, or empty if the file is not a symlink.

  File naming terminology
Given a search root of /home/user/projects and a file at /home/user/projects/foobar/content/readme.md:

    abspath   /home/user/projects/foobar/content/readme.md
    absdir    /home/user/projects/foobar/content
    path      foobar/content/readme.md
    dir       foobar/content
    name      readme.md
    filename  readme
    ext       md

  Size

size
    Size of the file in bytes.

fsize or hsize
    Human-readable size with unit suffix.

  Timestamps

accessed
    Time the file was last accessed (YYYY-MM-DD HH:MM:SS).

created
    File creation time (YYYY-MM-DD HH:MM:SS).

modified
    Time the file was last modified (YYYY-MM-DD HH:MM:SS).

  Type tests (boolean)

is_dir
    True if path is a directory.

is_file
    True if path is a regular file.

is_symlink
    True if path is a symbolic link.

is_broken_symlink or is_broken_link
    True if path is a symbolic link whose target does not exist.

is_pipe or is_fifo
    True if path is a FIFO or named pipe.

is_char or is_character
    True if path is a character special file.

is_block
    True if path is a block special file.

is_socket
    True if path is a socket.

is_hidden
    True if file is hidden (starts with a dot on Unix).

is_empty
    True if file is empty or directory contains no entries.

is_shebang
    True if file begins with a shebang (#!).

is_binary
    True if MIME type detection identifies the file as binary.

is_text
    True if MIME type detection identifies the file as text.

  Git

is_git_repo
    True if the directory contains a .git subdirectory or file (i.e., is the root of a git repository).

is_git_tracked, git_tracked
    True if the file is tracked by git.

is_gitignored, is_git_ignored
    True if the file is ignored by git.

git_status
    Git status of the file: clean, modified, staged, untracked, conflicted, or ignored.

git_branch
    Current branch of the git repository containing the file.

git_last_commit_hash, git_commit_hash
    Hash of the last commit that touched the file.

git_last_commit_date, git_commit_date
    Date of the last commit that touched the file.

git_last_commit_author, git_commit_author
    Author of the last commit that touched the file.

  Permissions

mode
    Full permission string, similar to the first column of ls -la.

uid / gid
    Numeric user ID / group ID of the owner.

user / group
    Name of the owner / owner's group. Available only on Unix when the users feature is enabled.

user_read, user_write, user_exec, user_all / user_rwx
    Per-owner permission bits.

group_read, group_write, group_exec, group_all / group_rwx
    Per-group permission bits.

other_read, other_write, other_exec, other_all / other_rwx
    Permission bits for other users.

suid or is_suid
    SUID bit.

sgid or is_sgid
    SGID bit.

is_sticky or sticky
    Sticky bit.

  Unix/Linux-specific

device
    Device number the file resides on.

rdev
    Device ID for special files (character and block devices).

inode
    Inode number.

blocks
    Number of 512-byte blocks allocated.

blksize, block_size
    Preferred block size for filesystem I/O in bytes.

hardlinks
    Number of hard links.

atime
    Last access time as a Unix timestamp (seconds since epoch).

atime_nsec
    Nanosecond component of the last access time.

mtime
    Last modification time as a Unix timestamp (seconds since epoch).

mtime_nsec
    Nanosecond component of the last modification time.

ctime
    Last status change time as a Unix timestamp (seconds since epoch).

ctime_nsec
    Nanosecond component of the last status change time.

has_xattrs
    True if the file has extended attributes (xattrs).

xattr_count
    Number of extended attributes (xattrs) on the file, or alternate data streams on Windows.

extattrs
    Extended file attribute flags as reported by lsattr(1) (single-letter codes).

has_extattrs
    True if any extattrs flag is set.

acl All ACL entries in standard form, comma-separated. On Linux, returns POSIX ACL entries in getfacl(1) format. On Windows, returns explicit DACL entries as type:trustee:permissions (e.g., allow:BUILTIN\Administrators:full). Permission labels: full, modify, rx, read, write, or a hex value for non-standard masks. Available only on Linux and Windows.

has_acl
    True if the file has POSIX ACL entries beyond standard Unix permissions or explicit (non-inherited) Windows DACL entries.

default_acl
    All default POSIX ACL entries in standard form, comma-separated. Available only on Linux.

has_default_acl
    True if the directory has default POSIX ACL entries.

has_capabilities or has_caps
    True if the file has Linux capabilities. Available only on Linux.

capabilities or caps
    Linux capabilities string assigned to the file.

  Media

width / height
    Width and height of an image or MP4 video in pixels.

duration
    Duration of an audio file in seconds.

mp3_bitrate or bitrate
    Audio bitrate in kbps.

mp3_freq or freq
    Audio sampling frequency.

mp3_title or title
    Track title from audio metadata.

mp3_artist or artist
    Artist name from audio metadata.

mp3_album or album
    Album name from audio metadata.

mp3_genre or genre
    Genre from audio metadata.

mp3_comment or comment
    Comment from audio metadata.

mp3_track or track
    Track number from audio metadata (e.g. 4 or 4/9).

mp3_disc or disc
    Disc number (part of a set) from audio metadata (e.g. 1 or 1/2).

mp3_year or audio_year
    Year from audio metadata.

  EXIF metadata

exif_datetime
    Date and time recorded in EXIF data.

exif_datetime_original or exif_dto
    Original date and time when the photo was taken.

exif_altitude or exif_alt
    GPS altitude.

exif_latitude or exif_lat
    GPS latitude.

exif_longitude or exif_lng or exif_lon
    GPS longitude.

exif_make / exif_model
    Camera manufacturer and model.

exif_software
    Software used to create the image.

exif_version
    Version of EXIF metadata.

exif_exposure_time or exif_exptime
    Exposure time.

exif_aperture
    Aperture value.

exif_shutter_speed
    Shutter speed.

exif_f_number or exif_f_num
    F-number.

exif_iso_speed or exif_iso
    ISO speed (EXIF 2.3 ISOSpeed tag).

exif_sensitivity or exif_photo_sensitivity
    Photographic sensitivity (ISO).

exif_focal_length or exif_focal_len
    Focal length.

exif_lens_make / exif_lens_model
    Lens manufacturer and model.

exif_description or exif_desc
    Image description.

exif_artist
    Artist or photographer name.

exif_copyright
    Copyright information.

exif_orientation
    Image orientation.

exif_flash
    Flash status.

exif_color_space
    Color space.

exif_exposure_program or exif_exp_program
    Exposure program.

exif_exposure_bias or exif_exp_bias
    Exposure bias value.

exif_white_balance or exif_wb
    White balance mode.

exif_metering_mode
    Metering mode.

exif_scene_type or exif_scene
    Scene capture type.

exif_contrast
    Contrast setting.

exif_saturation
    Saturation setting.

exif_sharpness
    Sharpness setting.

exif_body_serial or exif_serial
    Camera body serial number.

exif_lens_serial
    Lens serial number.

exif_user_comment or exif_comment
    User comment.

exif_image_width or exif_width
    Image width from EXIF.

exif_image_height or exif_height
    Image height from EXIF.

exif_max_aperture
    Max aperture value of the lens.

exif_digital_zoom or exif_dzoom
    Digital zoom ratio.

  MIME and file type shortcuts

mime
    MIME type string.

line_count
    Number of lines in a text file.

word_count or words
    Number of whitespace-separated words in a text file.

char_count or chars
    Number of characters in a text file.

encoding
    Detected text encoding (e.g. ASCII, UTF-8, UTF-16LE), or empty for binary files.

has_bom
    True if the file begins with a byte-order mark (BOM).

line_ending or line_endings or eol
    Line ending style of a text file (LF, CRLF, CR, Mixed, or empty).

is_archive
    True if extension matches a known archive format (.7z, .bz2, .gz, .rar, .tar, .xz, .zip, and others).

is_audio
    True if extension matches a known audio format (.aac, .flac, .mp3, .ogg, .wav, .wma, and others).

is_book
    True if extension matches a known book format (.epub, .fb2, .mobi, .pdf, and others).

is_doc
    True if extension matches a known document format (.doc, .docx, .odt, .pdf, .ppt, .xls, and others).

is_font
    True if extension matches a known font format (.otf, .ttf, .woff, .woff2, and others).

is_image
    True if extension matches a known image format (.bmp, .gif, .jpeg, .jpg, .png, .svg, .webp, and others).

is_source
    True if extension matches a known source code format (.c, .cpp, .go, .java, .js, .py, .rs, .ts, and others).

is_video
    True if extension matches a known video format (.avi, .mkv, .mov, .mp4, .webm, .wmv, and others).

  File hashes

sha1
    SHA-1 digest.

sha2_256 or sha256
    SHA-256 digest.

sha2_512 or sha512
    SHA-512 digest.

sha3_512 or sha3
    SHA3-512 digest.

FUNCTIONS

  Aggregate functions
Queries using these functions return a single result row.

AVG Average value.

COUNT
    Number of rows.

MAX Maximum value.

MIN Minimum value.

SUM Sum of all values.

STDDEV_POP / STDDEV / STD
    Population standard deviation.

STDDEV_SAMP
    Sample standard deviation.

VAR_POP / VARIANCE
    Population variance.

VAR_SAMP
    Sample variance.

  Date functions

CURRENT_DATE / CUR_DATE / CURDATE
    Current date.

CURRENT_TIME / CUR_TIME / CURTIME
    Current local time (HH:MM:SS).

CURRENT_TIMESTAMP / NOW
    Current local timestamp (YYYY-MM-DD HH:MM:SS).

DAY Day of the month.

MONTH
    Month of the year.

YEAR
    Year.

DOW / DAYOFWEEK
    Day of the week (1 = Sunday, 2 = Monday, ...).

DAYNAME
    Name of the day of the week (e.g., Monday, Tuesday).

DOY / DAYOFYEAR
    Day of the year (1–366).

DATE_ADD / DATEADD(date, days)
    Add days to a date and return the resulting datetime.

DATE_SUB / DATESUB(date, days)
    Subtract days from a date and return the resulting datetime.

DATE_DIFF / DATEDIFF(date1, date2)
    Number of days between date1 and date2.

FROM_UNIXTIME(timestamp)
    Convert a Unix timestamp (seconds since epoch) to a datetime string.

LAST_DAY / LAST_DATE(date)
    Last day of the month for the given date.

EXTRACT(unit, date)
    Extract a date/time part from date. The unit must be a quoted string. Supported units: year, quarter, month, week (ISO), day, hour, minute, second, dow (1=Sun..7=Sat), isodow (1=Mon..7=Sun), doy, epoch (Unix timestamp).

DATE_TRUNC / DATETRUNC(unit, date)
    Truncate date to a unit boundary, returned as “YYYY-MM-DD HH:MM:SS”. The unit must be a quoted string. Supported units: year, quarter, month, week (truncates to Monday), day, hour, minute, second.

  String functions

LENGTH / LEN
    Length of the string value.

LOWER / LOWERCASE / LCASE
    Convert to lowercase.

UPPER / UPPERCASE / UCASE
    Convert to uppercase.

INITCAP
    First letter of each word uppercase, rest lowercase.

TO_BASE64 / BASE64
    Encode to Base64.

FROM_BASE64
    Decode from Base64.

CONCAT
    Concatenate expression values.

CONCAT_WS
    Concatenate expression values with a delimiter.

LOCATE / POSITION(str, substr [, pos])
    Position of substr in str.

SUBSTRING / SUBSTR(str, pos [, len])
    Substring starting at pos. Negative pos counts from the end.

REPLACE(str, from, to)
    Replace all occurrences.

TRIM
    Strip whitespace from both ends.

LTRIM
    Strip whitespace from the left.

RTRIM
    Strip whitespace from the right.

  Numeric functions

BIN / HEX / OCT
    Convert integer to binary, hexadecimal, or octal.

ABS Absolute value.

POWER / POW
    Raise to a power.

SQRT
    Square root.

LOG Common logarithm.

LN  Natural logarithm.

EXP Euler's number raised to the given power.

LEAST
    Smallest of the given values.

GREATEST
    Largest of the given values.

PI  The constant π.

FLOOR
    Largest integer not greater than the value.

CEIL / CEILING
    Smallest integer not less than the value.

ROUND
    Nearest integer.

RANDOM / RAND
    Random integer. With no argument: 0 to max int. With one argument: 0 to arg. With two arguments: from arg1 to arg2.

  Character detection functions

CONTAINS_JAPANESE / JAPANESE
    True if the string contains Japanese characters.

CONTAINS_HIRAGANA / HIRAGANA
    True if the string contains Hiragana characters.

CONTAINS_KATAKANA / KATAKANA
    True if the string contains Katakana characters.

CONTAINS_KANA / KANA
    True if the string contains Kana characters (Hiragana or Katakana).

CONTAINS_KANJI / KANJI
    True if the string contains Kanji characters.

CONTAINS_GREEK / GREEK
    True if the string contains Greek characters.

  Other functions

CONTAINS
    True if the file contains the given string.

COALESCE
    First non-empty value from the argument list.

FORMAT_TIME / PRETTY_TIME
    Human-readable duration (e.g., 2min 26s).

FORMAT_SIZE / FORMAT_FILESIZE
    Formatted file size. The optional second argument is a format specifier such as %.2 d (two decimal places, 1000-based units).

  Extended attribute and ACL functions

HAS_XATTR(name)
    True if the named xattr exists.

XATTR(name)
    Value of the named xattr.

HAS_EXTATTR(flag)
    True if the given lsattr(1) flag is set. Available only on Linux.

HAS_ACL_ENTRY(entry)
    True if the specified ACL entry exists. Entry format: type:qualifier (e.g., user:john, group:staff).

ACL_ENTRY(entry)
    Permissions for the specified ACL entry.

HAS_DEFAULT_ACL_ENTRY(entry)
    True if the specified default ACL entry exists.

DEFAULT_ACL_ENTRY(entry)
    Permissions for the specified default ACL entry.

HAS_CAPABILITY / HAS_CAP(cap)
    True if the file has the given Linux capability.

  User functions
Available only on Unix when the users feature is enabled.

CURRENT_UID()
    Current real UID.

CURRENT_USER()
    Name of the current real UID.

CURRENT_GID()
    Current primary GID.

CURRENT_GROUP()
    Name of the current primary GID.

FILE SIZE UNITS
Size comparisons and the fsize column understand the following unit suffixes:

    t or tib    tebibyte    1024^4 bytes
    tb          terabyte    1000^4 bytes
    g or gib    gibibyte    1024^3 bytes
    gb          gigabyte    1000^3 bytes
    m or mib    mebibyte    1024^2 bytes
    mb          megabyte    1000^2 bytes
    k or kib    kibibyte    1024 bytes
    kb          kilobyte    1000 bytes

SEARCH ROOTS
Each search root may be followed by one or more options:

mindepth N
    Minimum search depth. Depth 1 skips the root directory itself and starts at its children.

maxdepth N
    Maximum search depth. Depth 1 searches only the root directory. Depth 2 also searches immediate subdirectories. Synonym: depth.

symlinks / sym
    Follow symbolic links. Default is not to follow.

archives / arc
    Search inside archives (zip only). Default is not to search archives.

gitignore / git
    Respect .gitignore files.

hgignore / hg
    Respect .hgignore files.

dockerignore / dock
    Respect .dockerignore files.

nogitignore / nogit
    Disable .gitignore parsing.

nohgignore / nohg
    Disable .hgignore parsing.

nodockerignore / nodock
    Disable .dockerignore parsing.

dfs Depth-first traversal.

bfs Breadth-first traversal (default).

regexp / rx
    Treat the root path as a regular expression matching against multiple directories.

OPERATORS

  Comparison operators

= / == / eq
    Equal (with glob expansion and regular expression matching for strings).

!= / <> / ne
    Not equal.

=== / eeq
    Exact equal (no glob or regex expansion).

!== / ene
    Exact not-equal.

> / gt
    Greater than.

>= / gte / ge
    Greater than or equal.

< / lt
    Less than.

<= / lte / le
    Less than or equal.

=~ / ~= / regexp / rx
    Match regular expression.

!=~ / !~= / notrx
    Does not match regular expression.

like
    SQL LIKE pattern ( % matches any sequence, _ matches one character).

notlike
    Negation of like.

between
    Range check: column between val1 and val2

in  Set membership: column in (val1, val2, ...) or column in (subquery).

exists
    Row existence test: exists (subquery)

  Arithmetic operators

+ / plus
    Addition.

- / minus
    Subtraction.

* / mul
    Multiplication.

/ / div
    Division.

% / mod
    Modulo.

  Logical operators

and Logical conjunction.

or  Logical disjunction.

not Logical negation. May appear before an operator or a condition.

DATE AND TIME SPECIFIERS
When the = or != operator is used with an inexact date, it is treated as an interval:

    2017-05-01
        The entire day (00:00:00 to 23:59:59).

    2017-05-01 15
        One hour (15:00:00 to 15:59:59).

    2017-05-01 15:10
        One minute (15:10:00 to 15:10:59).

Other comparison operators accept more flexible date expressions: today , yesterday , last fri , apr 1 , 2017-05-01 , and numeric relative offsets (e.g., -2 means two days ago).

Dates default to UK locale (DD/MM). Use --us-dates or us_dates = true in the config file to switch to US format. The safest representation is ISO 8601: YYYY-MM-DD HH:MM:SS.

REGULAR EXPRESSIONS
Rust-flavor regular expressions are used (see regex(7) or the online documentation at https://docs.rs/regex).

SUBQUERIES
Subqueries may be used with the in, not in, exists, and not exists operators. To reference columns from an outer query in a correlated subquery, bind the search root with an alias using the as keyword:

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

OUTPUT FORMATS
Specified with the into keyword at the end of the query.

tabs
    Tab-separated columns (default).

lines
    Each column on a separate line.

list
    Columns separated by a NUL byte, similar to find -print0 (suitable for xargs -0).

csv Comma-separated values.

json
    JSON array of result objects.

html
    HTML document containing a table.

CONFIGURATION FILE
On Linux:
    ~/.config/fselect/config.toml

On Windows:
    %APPDATA%\jhspetersson\fselect\config.toml

If no config file is found on the standard paths, fselect also looks for a config file next to the executable. A custom path may be supplied with --config.

INTERACTIVE MODE
Start with fselect -i. In interactive mode:

•   Queries are entered directly without quoting for the shell.

•   Shell metacharacters need not be escaped.

•   Command history is available via the up and down arrow keys.

•   pwd prints the current directory; cd changes it.

•   errors off suppresses error reporting.

•   Exit with quit, exit, Ctrl+C, or Ctrl+D.

ENVIRONMENT

LS_COLORS
    Determines how search results are colorized; see dircolors(1).

NO_COLOR
    When set (to any value), disables all colorized output.

EXIT STATUS

0   Success.

1   I/O error during directory traversal or file reading.

2   Query parse error, or a fatal error while evaluating the query (e.g. an invalid root alias).

EXAMPLES

Find temporary and config files, showing size and full path:
    $ fselect size, path from /home/user where name = '*.cfg' or name = '*.tmp'

Search in a directory whose name contains spaces:
    $ fselect "name from '/home/user/dir with spaces' where size > 0"

Find large files (over 2 GiB):
    $ fselect size, abspath from ./tmp where size gt 2g

Find files within a size range:
    $ fselect name, size from ./tmp where size between 5mb and 6mb

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

Find files modified today, ordered by size:
    $ fselect path, size from /home/user where modified = today order by size desc

Find files by regular expression:
    $ fselect name from /home/user where path =~ '.*Rust.*'

Aggregate: total size of downloads:
    $ fselect "MIN(size), MAX(size), AVG(size), SUM(size), COUNT(*) from /home/user/Downloads"

Group files by extension with count:
    $ fselect "ext, count(*) from /tmp group by ext"

Filter groups after aggregation:
    $ fselect "ext, count(*) from /tmp group by ext having count(*) > 10"

Search with depth limit and symlink following:
    $ fselect path from /home/user depth 5 symlinks where name = '*.jpg'

Search respecting .gitignore:
    $ fselect size, path from /home/user/projects gitignore where name = '*.cpp'

Find images by dimensions:
    $ fselect path from /home/user/photos where width gte 2000 or height gte 2000

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

Find files with dangerous permissions:
    $ fselect mode, path from /home/user where other_write or other_exec

Find files not present in a backup directory:
    $ fselect "name, path from /current where name not in (select name from /backup)"

Output as JSON:
    $ fselect size, path from /home/user limit 5 into json

Pipe NUL-separated paths to grep:
    $ fselect path from /home/user into list | xargs -0 grep foobar

SEE ALSO
find(1), fd(1), ls(1), dircolors(1)