Find File
find_fileRead-only
Search for files matching a specific pattern while automatically excluding gitignored files. Use wildcards to locate files in any directory of your project.
Instructions
Finds non-gitignored files matching the given file mask within the given relative path. Returns a JSON object with the list of matching files.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_mask | Yes | The filename or file mask (using the wildcards * or ?) to search for. | |
| relative_path | Yes | The relative path to the directory to search in; pass "." to scan the project root. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/serena/tools/file_tools.py:125-159 (handler)The FindFileTool class provides the core handler logic for the 'find_file' tool, implementing the apply method that searches for files matching a given mask in a directory using fnmatch and scan_directory, returning a JSON list of matches.
class FindFileTool(Tool): """ Finds files in the given relative paths """ def apply(self, file_mask: str, relative_path: str) -> str: """ Finds non-gitignored files matching the given file mask within the given relative path :param file_mask: the filename or file mask (using the wildcards * or ?) to search for :param relative_path: the relative path to the directory to search in; pass "." to scan the project root :return: a JSON object with the list of matching files """ self.project.validate_relative_path(relative_path, require_not_ignored=True) dir_to_scan = os.path.join(self.get_project_root(), relative_path) # find the files by ignoring everything that doesn't match def is_ignored_file(abs_path: str) -> bool: if self.project.is_ignored_path(abs_path): return True filename = os.path.basename(abs_path) return not fnmatch(filename, file_mask) _dirs, files = scan_directory( path=dir_to_scan, recursive=True, is_ignored_dir=self.project.is_ignored_path, is_ignored_file=is_ignored_file, relative_to=self.get_project_root(), ) result = self._to_json({"files": files}) return result - src/serena/tools/tools_base.py:118-125 (registration)The get_name_from_cls method in the Tool base class derives the tool name 'find_file' from the class name 'FindFileTool' by removing 'Tool' suffix and converting to snake_case.
@classmethod def get_name_from_cls(cls) -> str: name = cls.__name__ if name.endswith("Tool"): name = name[:-4] # convert to snake_case name = "".join(["_" + c.lower() if c.isupper() else c for c in name]).lstrip("_") return name - src/serena/tools/tools_base.py:360-367 (registration)The ToolRegistry scans all subclasses of Tool in the serena.tools package and registers them by their derived name, including FindFileTool as 'find_file'.
if not any(cls.__module__.startswith(pkg) for pkg in tool_packages): continue is_optional = issubclass(cls, ToolMarkerOptional) name = cls.get_name_from_cls() if name in self._tool_dict: raise ValueError(f"Duplicate tool name found: {name}. Tool classes must have unique names.") self._tool_dict[name] = RegisteredTool(tool_class=cls, is_optional=is_optional, tool_name=name) - src/serena/tools/__init__.py:1-9 (helper)The __init__.py file imports all tool modules, exposing FindFileTool for use and discovery by the ToolRegistry.
# ruff: noqa from .tools_base import * from .file_tools import * from .symbol_tools import * from .memory_tools import * from .cmd_tools import * from .config_tools import * from .workflow_tools import * from .jetbrains_tools import *