FSELECT(1)

๐Ÿ“ฆ
version 0.10.3 ยท 2 versions
, in nixpkgs unstable

๐Ÿ’– NAME ๐Ÿ’–

okay bestie, this is the iconic fselect(1) page from the General Commands Manual โ€” a command-line utility for finding files with SQL-like queries. It's giving search-but-make-it-query-language, and honestly? Obsessed. ๐Ÿ’–


โœจ SYNOPSIS โœจ

here's the shape of it, bestie โ€” copy these exactly:

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 ๐Ÿฆ‹

okay so 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 โ€” you can literally skip it if you're feeling casual. ๐Ÿ’…

Query columns may be file attributes, arbitrary string literals (quoted if they contain spaces), function calls, or arithmetic expressions. Slay, versatile icon behavior. โœจ

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.). Highkey main character energy for every root, fr fr. ๐ŸŽ€

๐Ÿšจ bestie, important vibe check: queries containing >, <, parentheses, or shell metacharacters such as * and ? should be enclosed in double quotes to prevent shell interpretation. Protect the query. Periodt. ๐Ÿ’€

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. lowkey flexible, highkey iconic. ๐Ÿฆ‹


๐ŸŒธ OPTIONS ๐ŸŒธ

  • --interactive, -i โ€” Run in interactive mode. it's giving choose-your-own-adventure, but make it files ๐ŸŽฎ
  • --config FILE โ€” Specify an alternative configuration file location. custom config bestie behavior ๐ŸŽ€
  • --nocolor, --no-color โ€” Disable colorized output. let your terminal be its natural, unbothered self ๐Ÿ’…
  • --no-errors โ€” Suppress error messages. quiet-luxury era, no drama ๐Ÿ™ˆ
  • --us-dates โ€” Interpret ambiguous dates in US format (MM/DD) instead of the default UK format (DD/MM). US-format bestie mode activated ๐Ÿ‡บ๐Ÿ‡ธโœจ
  • --help, -h โ€” Show help and exit. the โ€œwait, how does this work again?โ€ button ๐Ÿซถ

โœจ COLUMNS AND FIELDS โœจ

okay so these are the literal column and field names, bestie ๐Ÿ’– like the whole menu of stuff this page knows how to talk about. no cap, every single one is listed here.

๐ŸŽ€ File naming ๐ŸŽ€

  • name โ€” the full file name, extension included.
  • filename, fname โ€” the file name without its extension.
  • extension, ext โ€” just the extension, with no leading dot.
  • path โ€” the path relative to the search root.
  • abspath โ€” the absolute path of the file.
  • directory, dirname, dir โ€” the directory part of the path, relative to the search root.
  • absdir โ€” the absolute directory part of the path.
  • link_target, symlink_target โ€” the target path of a symlink, or empty if the file is not a symlink.

๐Ÿงš File naming terminology ๐Ÿงš

so if your search root is /home/user/projects and the file is sitting at /home/user/projects/foobar/content/readme.md, then it breaks down like this:

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 โ€” the file size in bytes.
  • fsize, hsize โ€” a human-readable size with a unit suffix.

๐Ÿ•ฐ๏ธ Timestamps ๐Ÿ•ฐ๏ธ

  • accessed โ€” when the file was last accessed (YYYY-MM-DD HH:MM:SS).
  • created โ€” the file creation time (YYYY-MM-DD HH:MM:SS).
  • modified โ€” when the file was last modified (YYYY-MM-DD HH:MM:SS).

โœ… Type tests (boolean) โœ…

these ones are giving very โ€œtrue or false, bestieโ€ energy ๐Ÿ’…

  • is_dir โ€” true if the path is a directory.
  • is_file โ€” true if the path is a regular file.
  • is_symlink โ€” true if the path is a symbolic link.
  • is_broken_symlink, is_broken_link โ€” true if the path is a symbolic link whose target does not exist.
  • is_pipe, is_fifo โ€” true if the path is a FIFO or named pipe.
  • is_char, is_character โ€” true if the path is a character special file.
  • is_block โ€” true if the path is a block special file.
  • is_socket โ€” true if the path is a socket.
  • is_hidden โ€” true if the file is hidden (starts with a dot on Unix).
  • is_empty โ€” true if the file is empty or the directory contains no entries.
  • is_shebang โ€” true if the 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 โ€” the fileโ€™s git status: clean, modified, staged, untracked, conflicted, or ignored.
  • git_branch โ€” the current branch of the git repository that contains the file.
  • git_last_commit_hash, git_commit_hash โ€” the hash of the last commit that touched the file.
  • git_last_commit_date, git_commit_date โ€” the date of the last commit that touched the file.
  • git_last_commit_author, git_commit_author โ€” the author of the last commit that touched the file.

๐Ÿ” Permissions ๐Ÿ”

  • mode โ€” the full permission string, similar to the first column of ls -la.
  • uid / gid โ€” numeric user ID / group ID of the owner.
  • user / group โ€” the 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, is_suid โ€” the SUID bit.
  • sgid, is_sgid โ€” the SGID bit.
  • is_sticky, sticky โ€” the sticky bit.

๐Ÿง Unix/Linux-specific ๐Ÿง

  • device โ€” the device number the file resides on.
  • rdev โ€” the device ID for special files (character and block devices).
  • inode โ€” the inode number.
  • blocks โ€” the number of 512-byte blocks allocated.
  • blksize, block_size โ€” the preferred block size for filesystem I/O, in bytes.
  • hardlinks โ€” the number of hard links.
  • atime โ€” the last access time as a Unix timestamp (seconds since epoch).
  • atime_nsec โ€” the nanosecond component of the last access time.
  • mtime โ€” the last modification time as a Unix timestamp (seconds since epoch).
  • mtime_nsec โ€” the nanosecond component of the last modification time.
  • ctime โ€” the last status change time as a Unix timestamp (seconds since epoch).
  • ctime_nsec โ€” the nanosecond component of the last status change time.
  • has_xattrs โ€” true if the file has extended attributes (xattrs).
  • xattr_count โ€” the 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, has_caps โ€” true if the file has Linux capabilities. Available only on Linux.
  • capabilities, caps โ€” the 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, bitrate โ€” audio bitrate in kbps.
  • mp3_freq, freq โ€” audio sampling frequency.
  • mp3_title, title โ€” track title from audio metadata.
  • mp3_artist, artist โ€” artist name from audio metadata.
  • mp3_album, album โ€” album name from audio metadata.
  • mp3_genre, genre โ€” genre from audio metadata.
  • mp3_comment, comment โ€” comment from audio metadata.
  • mp3_track, track โ€” track number from audio metadata (e.g. 4 or 4/9).
  • mp3_disc, disc โ€” disc number (part of a set) from audio metadata (e.g. 1 or 1/2).
  • mp3_year, audio_year โ€” year from audio metadata.

๐Ÿ“ธ EXIF metadata ๐Ÿ“ธ

  • exif_datetime โ€” date and time recorded in EXIF data.
  • exif_datetime_original, exif_dto โ€” the original date and time when the photo was taken.
  • exif_altitude, exif_alt โ€” GPS altitude.
  • exif_latitude, exif_lat โ€” GPS latitude.
  • exif_longitude, exif_lng, 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, exif_exptime โ€” exposure time.
  • exif_aperture โ€” aperture value.
  • exif_shutter_speed โ€” shutter speed.
  • exif_f_number, exif_f_num โ€” F-number.
  • exif_iso_speed, exif_iso โ€” ISO speed (EXIF 2.3 ISOSpeed tag).
  • exif_sensitivity, exif_photo_sensitivity โ€” photographic sensitivity (ISO).
  • exif_focal_length, exif_focal_len โ€” focal length.
  • exif_lens_make / exif_lens_model โ€” lens manufacturer and model.
  • exif_description, 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, exif_exp_program โ€” exposure program.
  • exif_exposure_bias, exif_exp_bias โ€” exposure bias value.
  • exif_white_balance, exif_wb โ€” white balance mode.
  • exif_metering_mode โ€” metering mode.
  • exif_scene_type, exif_scene โ€” scene capture type.
  • exif_contrast โ€” contrast setting.
  • exif_saturation โ€” saturation setting.
  • exif_sharpness โ€” sharpness setting.
  • exif_body_serial, exif_serial โ€” camera body serial number.
  • exif_lens_serial โ€” lens serial number.
  • exif_user_comment, exif_comment โ€” user comment.
  • exif_image_width, exif_width โ€” image width from EXIF.
  • exif_image_height, exif_height โ€” image height from EXIF.
  • exif_max_aperture โ€” max aperture value of the lens.
  • exif_digital_zoom, 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, words โ€” number of whitespace-separated words in a text file.
  • char_count, 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, line_endings, eol โ€” line ending style of a text file (LF, CRLF, CR, Mixed, or empty).
  • is_archive โ€” true if the extension matches a known archive format (.7z, .bz2, .gz, .rar, .tar, .xz, .zip, and others).
  • is_audio โ€” true if the extension matches a known audio format (.aac, .flac, .mp3, .ogg, .wav, .wma, and others).
  • is_book โ€” true if the extension matches a known book format (.epub, .fb2, .mobi, .pdf, and others).
  • is_doc โ€” true if the extension matches a known document format (.doc, .docx, .odt, .pdf, .ppt, .xls, and others).
  • is_font โ€” true if the extension matches a known font format (.otf, .ttf, .woff, .woff2, and others).
  • is_image โ€” true if the extension matches a known image format (.bmp, .gif, .jpeg, .jpg, .png, .svg, .webp, and others).
  • is_source โ€” true if the extension matches a known source code format (.c, .cpp, .go, .java, .js, .py, .rs, .ts, and others).
  • is_video โ€” true if the extension matches a known video format (.avi, .mkv, .mov, .mp4, .webm, .wmv, and others).

๐Ÿ”‘ File hashes ๐Ÿ”‘

  • sha1 โ€” SHA-1 digest.
  • sha2_256, sha256 โ€” SHA-256 digest.
  • sha2_512, sha512 โ€” SHA-512 digest.
  • sha3_512, sha3 โ€” SHA3-512 digest.

๐Ÿ’– FUNCTIONS ๐Ÿ’–

okay bestie, this is the built-in function menu โ€” every alias is listed exactly, no cap โœจ

๐ŸŒŸ 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 ๐ŸŒฟ

Okay so environment variables, bestie โ€” these are the little vibes you set outside the command and fselect lowkey respects them:

  • LS_COLORS โ€” this is the one that decides how search results get colorized, fr fr. See dircolors(1) for the whole color situation ๐Ÿ’…
  • NO_COLOR โ€” when it's set (to any value), it disables all colorized output. Not some. All. Periodt ๐Ÿ™ˆ

๐Ÿšฆ EXIT STATUS ๐Ÿšฆ

Exit codes are giving "read the room" energy โ€” here's what each one means:

  • 0 โ€” success, slay โœจ
  • 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 ๐ŸŽ€

This is the part where it gets iconic. Every example is here, bestie โ€” no skips, no cap ๐Ÿ‘‘

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 ๐Ÿ‘€

The besties in the same man-page universe, iykyk: find(1), fd(1), ls(1), dircolors(1) ๐Ÿซถ


That's the whole FSELECT(1) page, bestie โ€” source, version, and date are living their best life in the footer, and yes, they ate ๐Ÿ’…โœจ๐ŸŽ€

๐Ÿ“ฆ where this page comes from