Home

Awesome

Find Files (ff)

Build Status Version info

Find Files (ff) utility recursively searches the files whose names match the specified RegExp pattern in the provided directory (defaults to the current directory if not provided).

Dual-licensed under MIT or the UNLICENSE.

Screenshot

Screenshot

Installation

There are various ways to install ff on your system.

Install using Homebrew

If you use macOS, install ff simply using brew install vishaltelangre/tap/ff.

Download precompiled executables for your platform/OS

Download the latest precompiled executable ff binary for your platform from the releases page.

Install using Cargo

If you're a Rust programmer, download and install ff command using cargo install find-files. To update to a newer version, use the --force flag.

Benchmark Results

$ hyperfine                                \
    --warmup 3                             \
    --export-markdown benchmark-results.md \
    "find . -iregex '.*[0-9]\.jpg$'"       \
    "find . -iname '*[0-9].jpg'"           \
    "fd -HI '.*[0-9]\.jpg$'"               \
    "ff .*[0-9]\.jpg$"

Benchmark #1: find . -iregex '.*[0-9]\.jpg$'
  Time (mean ± σ):      42.8 ms ±   5.5 ms    [User: 11.7 ms, System: 30.1 ms]
  Range (min … max):    31.2 ms …  56.9 ms    48 runs

Benchmark #2: find . -iname '*[0-9].jpg'
  Time (mean ± σ):      60.8 ms ±   7.2 ms    [User: 27.9 ms, System: 31.4 ms]
  Range (min … max):    44.0 ms …  76.2 ms    37 runs

Benchmark #3: fd -HI '.*[0-9]\.jpg$'
  Time (mean ± σ):      18.8 ms ±   5.3 ms    [User: 14.9 ms, System: 19.9 ms]
  Range (min … max):    11.2 ms …  41.6 ms    96 runs

Benchmark #4: ff .*[0-9]\.jpg$
  Time (mean ± σ):      18.7 ms ±   4.6 ms    [User: 15.7 ms, System: 22.5 ms]
  Range (min … max):    11.7 ms …  30.4 ms    123 runs

Summary
  'ff .*[0-9]\.jpg$' ran
    1.00 ± 0.37 times faster than 'fd -HI '.*[0-9]\.jpg$''
    2.29 ± 0.63 times faster than 'find . -iregex '.*[0-9]\.jpg$''
    3.25 ± 0.88 times faster than 'find . -iname '*[0-9].jpg'
CommandMean [ms]Min…Max [ms]
find . -iregex '.*[0-9]\.jpg$'42.8 ± 5.531.2…56.9
find . -iname '*[0-9].jpg'60.8 ± 7.244.0…76.2
fd -HI '.*[0-9]\.jpg$'18.8 ± 5.311.2…41.6
ff .*[0-9]\.jpg$18.7 ± 4.611.7…30.4

Table: benchmark-results.md

NOTE: Sometimes, fd is a bit faster than ff by approximately 1 ms to 2 ms.

Usage

USAGE:
    ff [FLAGS] [OPTIONS] <PATTERN> [ROOT_PATH]

FLAGS:
    -s, --case-sensitive       Search case sensitively. By default, files are
                               searched case insensitively.
    -D, --exclude-dir-paths    Exclude paths from the search result which are
                               directories and not files.
    -h, --help                 Prints help information
    -G, --ignore-gitignore     Ignore searching files and directories specified
                               in .gitignore. By default, the files and
                               directories specified in .gitignore are included
                               in the search results.
    -H, --ignore-hidden        Ignore searching hidden files and directories. By
                               default, hidden files and directories are
                               included in the search results.
    -V, --version              Prints version information

OPTIONS:
    -x, --exclude <exclude>    Exclude files and directories matching this
                               regular expression from the search results.
    -L, --level <level>        Recursively search only given level directories
                               deep. By default no depth restriction is imposed.
                               A value of 0 would always yield zero results. A
                               value of 1 searches for the direct children in
                               the given path.
    -j, --threads <threads>    The approximate number of threads to use. A value
                               of 0 (which is the default) results in thread
                               count set to available CPU cores.

ARGS:
    <PATTERN>      Find files whose name (path) matches this substring or
                   the regular expression.
    <ROOT_PATH>    Path to the directory to search files inside.[default:
                   `$PWD`]

Examples

There are a tons of possibilities to search files using ff. Following examples demonstrate just a tip of an iceberg.