#find #files #gitignore

app filesfinder

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

20 unstable releases (3 breaking)

0.4.6 Mar 28, 2023
0.4.5 Mar 28, 2023
0.3.8 Mar 11, 2023
0.3.5 Dec 6, 2022
0.1.0 Jul 29, 2022

#92 in Filesystem

Download history 17/week @ 2023-02-09 28/week @ 2023-02-16 95/week @ 2023-03-09 25/week @ 2023-03-16 104/week @ 2023-03-23 12/week @ 2023-03-30 52/week @ 2023-04-06 22/week @ 2023-04-13 11/week @ 2023-04-20 1/week @ 2023-04-27 40/week @ 2023-05-04 2/week @ 2023-05-11 2/week @ 2023-05-18 20/week @ 2023-05-25

64 downloads per month

MIT license

345 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@v0.4.6
  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!


~79K SLoC