FilesFinder

Find files matching patterns while respecting .gitignore

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

About

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 :-)

Installation

You can install the latest released version with cargo:

cargo install filesfinder

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

USAGE:
    ff [OPTIONS] <PATTERN>...
    ff [OPTIONS] <PATTERN> [OPTIONS] <PATTERN> ...

ARGS:
    <PATTERN>...
            A pattern to match against each file.

OPTIONS:
    -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]

        --follow-links
            Allow to follow symbolic links.

        --show-hidden
            Allow to show hidden files.

        --no-gitignore
            Ignore .gitignore files.

        --no-ignore
            Ignore .ignore files.

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

    -h, --help
            Print help information.

    -V, --version
            Print version information.

NOTES:
    -   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"'.

Examples

> 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
  with:
    # 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 }}"

Contributing

Contributions are more than welcome!