ZFIND(1)

NAME
zfind - searches for files, including inside archives.

SYNOPSIS
zfind [<where> [<path> ...]] [flags]

DESCRIPTION

zfind makes finding files easy with a filter syntax that is similar to an SQL-WHERE clause.
    For examples run "zfind -H" or go to <https://github.com/laktak/zfind>.

  Arguments:

[<where>]
    The filter using SQL-where syntax (see -H). Use '-' to skip when providing a path.

[<path> ...]
    Paths to search.

  Flags:

-h, --help
    Show context-sensitive help.

-H, --filter-help
    Show where-filter help.

-l, --long
    Show long listing format.

--csv
    Show listing as CSV.

--csv-no-head
    Show listing as CSV without header.

--archive-separator="//"
    Separator between the archive name and the file inside

-L, --follow-symlinks
    Follow symbolic links.

-n, --no-archive
    Disables archive support.

-0, --print0
    Use a null character instead of the newline character, to be used with the -0 option of xargs.

-V, --version
    Show version.

EXAMPLES

    # find files smaller than 10KB, in the current path
    zfind 'size<10k'

    # find files in the given range in /some/path
    zfind 'size between 1M and 1G' /some/path

    # find files modified before 2010 inside a tar
    zfind 'date<"2010" and archive="tar"'

    # find files named foo* and modified today
    zfind 'name like "foo%" and date=today'

    # find files that contain two dashes using a regex
    zfind 'name rlike "(.*-){2}"'

    # find files that have the extension .jpg or .jpeg
    zfind 'ext in ("jpg","jpeg")'

    # find directories named foo and bar
    zfind 'name in ("foo", "bar") and type="dir"'

    # search for all README.md files and show in long listing format
    zfind 'name="README.md"' -l

    # show results in csv format
    zfind --csv
    zfind --csv-no-head

  Where Syntax

•   AND, OR and () parentheses are logical operators used to combine multiple conditions. AND means that both conditions must be true for a row to be included in the results. OR means that if either condition is true, the row will be included. Parentheses are used to group conditions, just like in mathematics.

Example: '(size > 20M OR name = "temp") AND type="file"' selects all files that are either greater than 20 MB in size or are named temp.

•   Operators =, <>, !=, <, >, <=, >= are comparison operators used to compare values and file properties. The types must match, meaning don’t compare a date to a file size.

Example: 'date > "2020-10-01"' selects all files that were modified after the specified date.

•   LIKE, ILIKE and RLIKE are used for pattern matching in strings.

    •   LIKE is case-sensitive, while ILIKE is case-insensitive.

    •   The % symbol is used as a wildcard character that matches any sequence of characters.

    •   The _ symbol matches any single character.

    •   RLIKE allows matching a regular expression.

Example: '"name like "z%"' selects all files whose name starts with `z'.

•   IN allows you to specify multiple values to match. A file will be included if the value of the property matches any of the values in the list.

Example: '"type in ("file", "link")' selects all files of type file or link.

•   BETWEEN selects values within a given range (inclusive).

Example: '"date between "2010" and "2011-01-15"' means that all files that were modified from 2010 to 2011-01-15 will be included.

•   NOT is a logical operator used to negate a condition. It returns true if the condition is false and vice versa.

Example: '"name not like "z%"', '"date not between "2010" and "2011-01-15"', '"type not in ("file", "link")'

•   Values can be numbers, text, date and time, TRUE and FALSE

    •   dates have to be specified in YYYY-MM-DD format

    •   times have to be specified in 24h HH:MM:SS format

    •   numbers can be written as sizes by appending B, K, M, G and T to specify bytes, KB, MB, GB, and TB.

    •   empty strings and 0 evaluate to false

  Properties

The following file properties are available:

name
    name of the file

path
    full path of the file

container
    path of the container (if inside an archive)

size
    file size (uncompressed)

date
    modified date in YYYY-MM-DD format

time
    modified time in HH:MM:SS format

ext short file extension (e.g., txt)

ext2
    long file extension (two parts, e.g., tar.gz)

type
    file, dir, or link

archive
    archive type: tar, zip, 7z, rar or empty

Helper properties

today
    today’s date

mo  last monday’s date

tu  last tuesday’s date

we  last wednesday’s date

th  last thursday’s date

fr  last friday’s date

sa  last saturday’s date

su  last sunday’s date

  Supported archives

tar .tar, .tar.gz, .tgz, .tar.bz2, .tbz2, .tar.xz, .txz

zip .zip

7zip
    .7z

rar .rar

Note: use the flag -n (or –no-archive) to disable archive support. You can also use 'not archive' in your query but this still requires zfind to open the archive.

  Actions

zfind does not implement actions like find, instead use xargs -0 to execute commands:

    zfind --no-archive 'name like "%.txt"' -0 | xargs -0 -L1 echo

zfind can also produce --csv (or --csv-no-head) that can be piped to other commands.

CONFIGURATION

Set the environment variable NO_COLOR to disable color output.

SEE ALSO
find(1), xargs(1).

AUTHORS
zfind is developed by Christian Zangl, see <https://github.com/laktak/zfind>.

This man page has been written by Daniel Lange <DLange@debian.org> for Debian based on the project's README file.