Gemini CLI 文件管理实战 引用上下文、代码探索、修改确认与 .geminiignore 可见性控制【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli在 Gemini CLI 中文件操作是 Agent 与代码库交互的核心能力通过引用强制注入文件内容、用glob/list_directory等工具定位未知文件、用replace/write_file工具完成精确修改并用.gitignore与.geminiignore控制模型能“看见”的内容范围。读完本文你可以掌握一套完整的文件管理工作流——从提供上下文、探索代码库、安全地修改和创建文件到验证变更与控制 Agent 的文件可见性并能对照仓库源码理解每个步骤背后的工具实现。前提条件已安装并完成认证的 Gemini CLIgemini可正常运行。一个可用于实践的项目目录例如一个 Git 仓库。通过读取文件提供上下文Gemini CLI 通常会主动读取相关文件依据你的权限设置有时会先征求你的访问许可。如果你希望确保某个文件一定进入上下文可以直接在提示词中引用它。直接文件引用语法已知目标文件路径时使用符号即可强制 CLI 立即读取该文件并将其内容注入提示词src/components/UserProfile.tsx Explain how this component handles user data.从源码结构看这套引用的解析逻辑集中在 atCommandProcessor.ts 中parseAllAtCommands函数用正则把查询串切分为“普通文本段”和路径段且支持用反斜杠转义空格、以及引号包裹的路径如含空格的文件名避免路径被错误截断。此外categorizeAtCommandsatCommandProcessor.ts会把每个引用分类为三类已注册的Agentsubagent 名称、MCP Resource URI、或普通的文件/目录路径。只有第三类才会走文件读取流程。而checkPermissionsatCommandProcessor.ts会在处理前对每个文件路径做解析与validatePathAccess权限校验越出可访问范围的路径会被拦截——这就是“有时提示你授权访问”的来源之一。同时引用多个文件复杂功能往往横跨多个文件。可以把多个引用串联起来给 Agent 完整的依赖关系视图src/components/UserProfile.tsx src/types/User.ts Refactor the component to use the updated User interface.引用整个目录对于大范围问题或重构可以直接引用整个目录src/utils/ Check these utility functions for any deprecated API usage.注意引用大目录会消耗更多 token请谨慎使用。从实现上看目录与 glob 模式的处理发生在resolveFilePathsatCommandProcessor.ts中它通过工具注册表取出glob工具展开路径并结合config.getFileFilteringOptions()应用.gitignore/.geminiignore过滤规则被忽略的路径会被单独记录且能区分是被 Git 忽略、被 Gemini 忽略还是两者都忽略reason: git | gemini | both因此你在交互中能看到“该路径已被忽略”的提示而非静默丢弃。文件探索不知道路径时如何定位如果你不知道确切文件路径可以直接让 Gemini CLI 帮你找。这在熟悉陌生代码库或定位特定逻辑时非常实用。场景查找组件定义你知道存在一个UserProfile组件但不知道它在哪里Find the file that defines the UserProfile component.Gemini 会调用glob或list_directory工具搜索项目结构然后返回具体路径例如src/components/UserProfile.tsx你可以在下一轮用直接引用它。提示你也可以要求列出文件例如“Show me all the TypeScript configuration files in the root directory.”这些探索类工具的技术参数可以参考仓库内的文件系统工具参考文档 docs/tools/file-system.mdlist_directoryls.ts列出指定路径下的文件和子目录支持ignoreglob 排除参数和file_filtering_options.gitignore/.geminiignore合规配置。globglob.ts按 glob 模式如*.py、src/**/*.js在整个工作区查找文件默认case_sensitive为false、respect_git_ignore为true结果按修改时间倒序返回并默认跳过node_modules、.git等噪声目录。grep_searchgrep.ts在文件内容中做正则搜索支持includeglob 过滤在 Git 仓库中优先使用git grep提速否则回退到系统grep或 JS 实现。修改代码当 Gemini CLI 已拥有上下文后你可以指示它做具体修改。该 Agent 具备复杂重构能力而非仅做简单文本替换Update src/components/UserProfile.tsx to show a loading spinner if the user data is null.Gemini CLI 使用replace工具提出定向代码变更。该工具的核心行为详见 docs/tools/file-system.md 与 edit.ts参数file_path、instruction变更的语义描述、old_string要查找的精确原文、new_string替换内容、可选的allow_multiple默认要求old_string在文件中恰好出现一次从而保证修改位置唯一、精确如需替换全部相同位置才需显式设置allow_multiple: true该工具需要用户手动确认Confirmation: manual approval。创建新文件你也可以让 Agent 从零创建新文件或目录结构Create a new file src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.Gemini CLI 使用write_file工具生成新文件。从 write-file.ts 的实现可以看到该工具不仅负责写入文件存在则覆盖、不存在则创建还会引入diff库生成统一差异、通过resolveDefensiveToolPath做路径防御性校验防止越出工作区边界、用detectLineEnding保留原有换行符风格并对写入内容做ensureCorrectFileContent校验——也就是说即使是“写新文件”也会纳入下面的 diff 确认流程。审查并确认变更Gemini CLI 将安全放在首位在任何文件被修改之前它会展示拟议变更的统一 diffunified diff- if (!user) return null; if (!user) return LoadingSpinner /;红色行-将被删除的代码绿色行将被添加的代码。按y确认并应用变更到本地文件系统如果 diff 不符合预期按n取消并细化你的提示词。这一确认机制在源码中由工具的ToolCallConfirmationDetails/ToolEditConfirmationDetails体系承载见 write-file.ts 从tools.js引入的确认类型定义write_file与replace都被标记为需要人工批准的工具。验证结果编辑完成后要验证修改最简做法是再次读取文件更好的做法是运行项目测试Run the tests for the UserProfile component.Gemini CLI 使用run_shell_command工具执行你的测试框架例如npm test或jest实现位于 shell.ts以确保变更没有破坏既有功能。进阶控制 Gemini 能看见什么默认情况下Gemini CLI 会遵循你的.gitignore文件它不会读取或搜索node_modules、构建产物及其他被忽略的路径。如果你有一些敏感文件如.env或大体积资源希望在不把它们加入 Git ignore 的前提下对 AI 隐藏可以在项目根目录创建.geminiignore文件.geminiignore示例.env local-db-dump.sql private-notes.md.geminiignore的完整语法约定与.gitignore基本一致详见 docs/cli/gemini-ignore.md空行和以#开头的行被忽略支持标准 glob 模式*、?、[]例如*.md排除所有 Markdown 文件行尾加/只匹配目录行首加/将路径锚定到.geminiignore所在目录!用于否定某条规则例如# 排除所有 .md 文件但保留 README.md *.md !README.md需要注意.geminiignore只影响支持该特性的工具如引用、glob、list_directory等这些文件对 Git 等其他服务仍然可见修改该文件后需要重启 Gemini CLI 会话才能生效。其读取与匹配逻辑位于 fileDiscoveryService.ts配合上文提到的resolveFilePaths在引用阶段即时过滤被忽略路径。另外如果你的项目目录不在信任列表中Agent 的文件读写请求会额外受到权限提示的约束可参考 Trusted folders 文档 了解访问权限管理。延伸学习Memory management管理上下文与记忆让 Agent 在长会话中保持高效Execute shell commands更多运行测试与构建的实战File system referenceread_file、write_file、replace等文件工具的完整参数技术参考gemini-ignore.geminiignore的独立功能文档。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考