list_dir
Scan and retrieve non-gitignored files and directories from a specified path, optionally with recursion. Outputs results as a JSON object for easy integration and analysis.
Instructions
Lists all non-gitignored files and directories in the given directory (optionally with recursion). Returns a JSON object with the names of directories and files within the given directory.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max_answer_chars | No | If the output is longer than this number of characters, no content will be returned. Don't adjust unless there is really no other way to get the content required for the task. | |
| recursive | Yes | Whether to scan subdirectories recursively. | |
| relative_path | Yes | The relative path to the directory to list; pass "." to scan the project root. |
Implementation Reference
- src/serena/tools/file_tools.py:84-122 (handler)The `ListDirTool` class provides the core implementation of the `list_dir` tool. Its `apply` method handles directory listing, validation, scanning using `scan_directory`, and returns a JSON-formatted result with directories and files, optionally skipping ignored paths and limiting output length.class ListDirTool(Tool): """ Lists files and directories in the given directory (optionally with recursion). """ def apply(self, relative_path: str, recursive: bool, skip_ignored_files: bool = False, max_answer_chars: int = -1) -> str: """ Lists files and directories in the given directory (optionally with recursion). :param relative_path: the relative path to the directory to list; pass "." to scan the project root :param recursive: whether to scan subdirectories recursively :param skip_ignored_files: whether to skip files and directories that are ignored :param max_answer_chars: if the output is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don't adjust unless there is really no other way to get the content required for the task. :return: a JSON object with the names of directories and files within the given directory """ # Check if the directory exists before validation if not self.project.relative_path_exists(relative_path): error_info = { "error": f"Directory not found: {relative_path}", "project_root": self.get_project_root(), "hint": "Check if the path is correct relative to the project root", } return self._to_json(error_info) self.project.validate_relative_path(relative_path, require_not_ignored=skip_ignored_files) dirs, files = scan_directory( os.path.join(self.get_project_root(), relative_path), relative_to=self.get_project_root(), recursive=recursive, is_ignored_dir=self.project.is_ignored_path if skip_ignored_files else None, is_ignored_file=self.project.is_ignored_path if skip_ignored_files else None, ) result = self._to_json({"dirs": dirs, "files": files}) return self._limit_length(result, max_answer_chars)