Skip to content

多文件读取工具 (read_many_files)

¥Multi File Read Tool (read_many_files)

本文档描述了read_many_filesGemini CLI 的工具。

¥This document describes the read_many_files tool for the Gemini CLI.

描述

¥Description

使用read_many_files从路径或 glob 模式指定的多个文件中读取内容。此工具的行为取决于提供的文件：

¥Use read_many_files to read content from multiple files specified by paths or glob patterns. The behavior of this tool depends on the provided files:

  • 对于文本文件，此工具将其内容连接成一个字符串。

    ¥For text files, this tool concatenates their content into a single string.

  • 对于图像（例如 PNG、JPEG）、PDF、音频（MP3、WAV）和视频（MP4、MOV）文件，它会读取它们并将它们作为 base64 编码数据返回，前提是它们通过名称或扩展名明确请求。

    ¥For image (e.g., PNG, JPEG), PDF, audio (MP3, WAV), and video (MP4, MOV) files, it reads and returns them as base64-encoded data, provided they are explicitly requested by name or extension.

read_many_files可用于执行诸如获取代码库概览、查找特定功能的实现位置、查看文档或从多个配置文件收集上下文等任务。

¥read_many_files can be used to perform tasks such as getting an overview of a codebase, finding where specific functionality is implemented, reviewing documentation, or gathering context from multiple configuration files.

笔记： read_many_files查找遵循指定路径或 glob 模式的文件。例如"/docs"将返回空结果；该工具需要如下模式"/docs/*"或者"/docs/*.md"识别相关文件。

¥Note: read_many_files looks for files following the provided paths or glob patterns. A directory path such as "/docs" will return an empty result; the tool requires a pattern such as "/docs/*" or "/docs/*.md" to identify the relevant files.

参数

¥Arguments

read_many_files采用以下参数：

¥read_many_files takes the following arguments:

  • paths（list[string]，必需）：相对于工具目标目录的 glob 模式或路径数组（例如，["src/**/*.ts"]，["README.md", "docs/*", "assets/logo.png"]）。

    ¥paths (list[string], required): An array of glob patterns or paths relative to the tool's target directory (e.g., ["src/**/*.ts"], ["README.md", "docs/*", "assets/logo.png"]).

  • exclude（列表 [string]，可选）：要排除的文件/目录的 Glob 模式（例如，["**/*.log", "temp/"]）。如果useDefaultExcludes是真的。

    ¥exclude (list[string], optional): Glob patterns for files/directories to exclude (e.g., ["**/*.log", "temp/"]). These are added to default excludes if useDefaultExcludes is true.

  • include(list[string], 可选): 需要添加的额外 glob 模式。这些模式将与paths（例如，["*.test.ts"]如果测试文件被广泛排除，则专门添加测试文件，或者["images/*.jpg"]以包含特定图像类型）。

    ¥include (list[string], optional): Additional glob patterns to include. These are merged with paths (e.g., ["*.test.ts"] to specifically add test files if they were broadly excluded, or ["images/*.jpg"] to include specific image types).

  • recursive(boolean, 可选): 是否递归搜索。这主要由**在 glob 模式中。默认为true。

    ¥recursive (boolean, optional): Whether to search recursively. This is primarily controlled by ** in glob patterns. Defaults to true.

  • useDefaultExcludes（布尔值，可选）：是否应用默认排除模式列表（例如，node_modules，.git，非图像/pdf 二进制文件）。默认为true。

    ¥useDefaultExcludes (boolean, optional): Whether to apply a list of default exclusion patterns (e.g., node_modules, .git, non image/pdf binary files). Defaults to true.

  • respect_git_ignore(布尔值，可选)：查找文件时是否遵循 .gitignore 模式。默认为 true。

    ¥respect_git_ignore (boolean, optional): Whether to respect .gitignore patterns when finding files. Defaults to true.

如何使用read_many_files使用 Gemini CLI

¥How to use read_many_files with the Gemini CLI

read_many_files搜索与提供的匹配的文件paths和include模式，同时尊重exclude模式和默认排除（如果启用）。

¥read_many_files searches for files matching the provided paths and include patterns, while respecting exclude patterns and default excludes (if enabled).

  • 对于文本文件：它读取每个匹配文件的内容（尝试跳过未明确请求为图像/PDF 的二进制文件）并将其连接成一个字符串，并使用分隔符--- {filePath} ---每个文件的内容之间。默认使用 UTF-8 编码。

    ¥For text files: it reads the content of each matched file (attempting to skip binary files not explicitly requested as image/PDF) and concatenates it into a single string, with a separator --- {filePath} --- between the content of each file. Uses UTF-8 encoding by default.

  • 该工具插入--- End of content ---在最后一个文件之后。

    ¥The tool inserts a --- End of content --- after the last file.

  • 对于图像和 PDF 文件：如果明确请求名称或扩展名（例如，paths: ["logo.png"]或者include: ["*.pdf"])，该工具读取该文件并将其内容以 base64 编码的字符串形式返回。

    ¥For image and PDF files: if explicitly requested by name or extension (e.g., paths: ["logo.png"] or include: ["*.pdf"]), the tool reads the file and returns its content as a base64 encoded string.

  • 该工具尝试通过检查其初始内容中的空字节来检测并跳过其他二进制文件（那些不匹配常见图像/PDF 类型或未明确请求的文件）。

    ¥The tool attempts to detect and skip other binary files (those not matching common image/PDF types or not explicitly requested) by checking for null bytes in their initial content.

用法：

¥Usage:

read_many_files(paths=["Your files or paths here."], include=["Additional files to include."], exclude=["Files to exclude."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true)

read_many_files示例

¥read_many_files examples

读取所有 TypeScript 文件src目录：

¥Read all TypeScript files in the src directory:

read_many_files(paths=["src/**/*.ts"])

阅读主 README 文件，所有 Markdown 文件docs目录和特定的徽标图像，不包括特定文件：

¥Read the main README, all Markdown files in the docs directory, and a specific logo image, excluding a specific file:

read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"])

读取所有 JavaScript 文件，但明确包含测试文件和所有 JPEG 文件images文件夹：

¥Read all JavaScript files but explicitly include test files and all JPEGs in an images folder:

read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False)

重要说明

¥Important notes

  • 二进制文件处理：

    ¥Binary file handling:

  • 图像/PDF/音频/视频文件：该工具可以读取常见的图像类型（PNG、JPEG 等）、PDF、音频（mp3、wav）和视频（mp4、mov）文件，并将其返回为 base64 编码数据。这些文件必须被明确针对paths或者include模式（例如，通过指定确切的文件名，如video.mp4或者像*.mov）。

    ¥Image/PDF/Audio/Video files: The tool can read common image types (PNG, JPEG, etc.), PDF, audio (mp3, wav), and video (mp4, mov) files, returning them as base64 encoded data. These files must be explicitly targeted by the paths or include patterns (e.g., by specifying the exact filename like video.mp4 or a pattern like *.mov).

  • 其他二进制文件：该工具会尝试通过检查其他类型的二进制文件的初始内容中是否存在空字节来检测并跳过这些文件。该工具会将这些文件从输出中排除。

    ¥Other binary files: The tool attempts to detect and skip other types of binary files by examining their initial content for null bytes. The tool excludes these files from its output.

  • 表现：读取大量文件或非常大的单个文件可能会耗费大量资源。

    ¥Performance: Reading a very large number of files or very large individual files can be resource-intensive.

  • 路径特异性：确保路径和 glob 模式相对于工具的目标目录正确指定。对于图像/PDF 文件，请确保模式足够具体，以便包含它们。

    ¥Path specificity: Ensure paths and glob patterns are correctly specified relative to the tool's target directory. For image/PDF files, ensure the patterns are specific enough to include them.

  • 默认排除：注意默认排除模式（例如node_modules，.git）并使用useDefaultExcludes=False如果您需要覆盖它们，但请谨慎操作。

    ¥Default excludes: Be aware of the default exclusion patterns (like node_modules, .git) and use useDefaultExcludes=False if you need to override them, but do so cautiously.