#gitignore #find #search-pattern #file #file-search #pattern-match #find-files

app filesfinder

Find files within current directory that match given patterns, while respecting gitignore rules

28 releases

0.5.1 Feb 19, 2024
0.4.12 Jul 24, 2023
0.4.6 Mar 28, 2023
0.3.5 Dec 6, 2022
0.1.0 Jul 29, 2022

#78 in Filesystem

Download history 2/week @ 2024-02-06 99/week @ 2024-02-13 96/week @ 2024-02-20 21/week @ 2024-02-27 1/week @ 2024-03-05 34/week @ 2024-03-12 30/week @ 2024-03-26 118/week @ 2024-04-02

178 downloads per month

MIT license

372 lines


Find files matching patterns while respecting .gitignore


  1. About
  2. Installation
  3. Examples
  4. GitHub Action
  5. Contributing


FilesFinder (FF) is a command-line tool that aims to search for files within a given repository. As such, it respects your .gitignore files and exclude the same files from the output.

FF is a faster and simpler-to-use alternative to other tools such as find from Findutils.

NOTE: FF is generally faster than find (or else), mainly because it uses parallel processing. If you find a scenario in which FF is slower than find or any other tool, please report it to me :-)


You can install the latest released version with cargo:

cargo install filesfinder

After that, FilesFinder can be used via the ff alias.

    ff [OPTIONS] <PATTERN>...

            A pattern to match against each file.

    -g, -G
            Parse pattern as a glob expression.
            [default behavior]

    -r, -R
            Parse pattern as a regular expression.
            Note that expressions are unanchored by default.
            Use '^' or '\A' to denote start, and '$' or '\z' for the end.

    -i, -I
            Matching files will be included in the output.
            [default behavior]

    -e, -E
            Matching files will be excluded from the output.

    -j <JOBS>
            Number of threads to use.
            Setting this to zero will choose the number of threads automatically.
            [default: num_cpus]

        --dir <PATH>
            Files will be searched in the directory specified by the PATH.
            Multiple occurences are allowed.
            [default: '.']

        --max-depth <DEPTH>
            Maximum depth to recurse.
            [default: None]

            Allow to follow symbolic links.

            Allow to show hidden files.

            Ignore .gitignore files.

            Ignore .ignore files.

            Do not strip './' prefix, same as what GNU find does.

    -h, --help
            Print help information.

    -V, --version
            Print version information.

    -   Capitalized options (.e.g., '-G') apply to all subsequent patterns.
        E.g.: 'ff -g "*.rs" -g "*.md"' is equivalent to 'ff -G "*.rs" "*.md"'.
        You can always unset a flag by overriding it.

    -   Options can be grouped under the same '-'.
        E.g.: 'ff -e -g "*.rs"' is equivalent to 'ff -eg "*.rs"'.

    -   File exclusion is performed after file inclusion.

    -   For performance reasons, prefer to use more general patterns first,
        and more specific ones at the end.
        E.g.: 'ff "*.md" "Cargo.toml"' is (usually) faster but equivalent to 'ff "Cargo.toml" "*.md"'.


> ff "*.rs"
# List all files with '.rs' extension

> ff "*.rs" -e "src/**.rs"
# List all files with 'rs' extension except those in the 'src' folder

> ff -r ".*\.md"
# List all files with 'md' extension, using regular expression

> ff -Re ".*\.md" ".*"
# List all files except those with 'md' extension, using regular expression

GitHub Action

A major application to FF is to be used within repositories. Therefore, you can also use the FilesFinder GitHub Action withing your projects.

# Your action in .github/workflows
- name: Checkout repository
  uses: actions/checkout@v3
    # Repository name with owner. For example, actions/checkout
    # Default: ${{ github.repository }}
    repository: ''
- name: Find files matching "*.rs" or "*.md"
  uses: jeertmans/filesfinder@latest
  id: ff # Any id, to be used later to reference to files output
    # Only argument, a single string, to be passed as arguments to ff.
    # See `ff --help` for more help.
    # Default: "*"
    args: "*.rs *.md"
- name: Print files
  run: echo "${{ steps.ff.outputs.files }}"


Contributions are more than welcome!


~257K SLoC