Skip to content

Find files matching patterns while respecting .gitignore

License

Notifications You must be signed in to change notification settings

jeertmans/filesfinder

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

FilesFinder

Find files matching patterns while respecting .gitignore

Crates.io

  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.

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

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

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

Options:
  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Walk options:
  -j <JOBS>
          Number of threads to use.
          
          Setting this to zero will choose the number of threads automatically.

  -d, --dir <DIRECTORY>
          Directory to search for files
          
          [default: .]

      --max-depth <DEPTH>
          Maximum depth to recurse into directories

      --follow-links
          Allow to follow symbolic links

  -., --hidden
          Search hidden files and directories.
          
          By default, hidden files and directories are skipped.

      --no-gitignore
          Ignore .gitignore files

      --no-ignore
          Ignore .ignore files

Match options:
  -g
          Parse pattern as a glob expression (default) [global alias: G]

  -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
          Matching files will be included in the output (default) [global alias: I]

  -e
          Matching files will be excluded from the output [global alias: E]

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

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!