Repomix 基本使用指南：将整个代码库打包为 AI 友好的单一文件-育师

Repomix 基本使用指南：将整个代码库打包为 AI 友好的单一文件

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix

本指南基于 Repomix 官方使用文档（website/client/src/vi/guide/usage.md）编写，系统讲解 Repomix CLI 的核心用法：从一条命令打包整个仓库，到按 glob 模式挑选/排除文件、通过 stdin 灵活传入文件列表、打包远程 GitHub 仓库、拆分超长输出、集成 Git diff 与提交历史，再到用 Token 统计树与代码压缩优化 AI 上下文消耗。读完本文，你将掌握 Repomix 绝大多数高频命令的用法、参数默认值与底层实现原理，能够直接把代码库"喂"给 Claude、ChatGPT、DeepSeek 等 LLM 使用。

快速开始

在项目根目录直接运行：

repomix

Repomix 会读取当前目录下的所有文件（遵循.gitignore、.ignore及内置默认忽略规则，如node_modules、.git等），打包生成默认的repomix-output.xml文件。从源码看，默认目录参数是.，见 CLI 入口定义；默认输出文件名与格式定义在 CLI 输出选项中（-o, --output默认repomix-output.xml，--style默认xml）。

常见使用场景

打包特定目录

repomix path/to/directory

位置参数可传一个或多个目录，多个目录会用空格分隔依次传入，例如repomix src tests。目录会先被解析为基于当前工作目录的绝对路径后再进入打包流程（见 defaultAction.ts）。

包含特定文件

使用 glob 通配符模式精确挑选要打包的文件（语法遵循 fast-glob 风格）：

repomix --include "src/**/*.ts,**/*.md"

--include接受逗号分隔的多个模式，例如"src/**/*.js,*.md"。在 buildCliConfig 中，模式字符串会通过splitPatterns按逗号切分后写入config.include。注意：使用--include后，输出中的目录结构部分默认只显示被包含文件所在的路径，如需展示完整仓库树，可叠加--include-full-directory-structure（定义于 cliRun.ts）。

排除文件

repomix --ignore "**/*.log,tmp/"

--ignore（短选项-i）接受逗号分隔的排除模式，例如"*.test.js,docs/**"。它会追加到已有的忽略规则之上（cliRun.ts）。Repomix 的忽略体系分三层：

--no-gitignore：不读取.gitignore；
--no-dot-ignore：不读取.ignore；
--no-default-patterns：不应用内置默认忽略模式（node_modules、.git、构建目录等）。

三者默认全部开启，可在 File Selection Options 中查看。

拆分输出为多个文件

处理大型代码库时，打包结果可能超出某些 AI 工具的单文件大小上限（例如 Google AI Studio 的 1MB 限制）。使用--split-output自动拆分：

repomix --split-output 1mb

该命令会生成带序号的文件：

repomix-output.1.xml
repomix-output.2.xml
repomix-output.3.xml

大小支持带单位的写法：500kb、1mb、2mb、1.5mb等，支持小数。解析逻辑见 sizeParse.ts：大小写不敏感，按 1024 进制换算（1kb = 1024 字节、1mb = 1024 × 1024 字节），最终换算为字节数传入config.output.splitOutput（见 buildCliConfig）。

[!NOTE] 输出按顶层目录分组以维持上下文完整。单个文件或目录绝不会被拆散到多个输出文件中。

这条规则在源码中有完整实现：outputSplit.ts 先按路径的第一段（getRootEntry）把所有文件分组；当某个组单独就超出大小上限时，subdivideSplitGroup会把它按目录树再细分一层（src变为src/a、src/b…），直到每组能装下为止；若细分到单个文件仍超限，会直接报错：A single file cannot be split across parts。拆分的分片文件名由 buildSplitOutputFilePath 生成。另外从第 2 个分片起会禁用 git diff/log 段以避免重复（见makeChunkConfig，outputSplit.ts）。

需要留意的是--split-output与--stdout、--copy、--skill-generate互斥，冲突时会在打包前报错退出，见 validateConflictingOptions。

远程仓库

无需先克隆，直接打包 GitHub 仓库：

# 使用 GitHub URL repomix --remote https://github.com/user/repo # 使用简写形式 repomix --remote user/repo # 不带 --remote 的简写形式（自动检测） repomix user/repo # 指定分支/标签/commit repomix --remote user/repo --remote-branch main repomix --remote user/repo --remote-branch 935b695

从 cliRun.ts 的实现可以看到远程仓库的三种触发路径：

显式--remote参数；
位置参数以https://、git@、ssh://、git://开头时自动识别为远程 URL（isExplicitRemoteUrl）；
位置参数形如owner/repo且本地不存在该路径时，Repomix 会先通过一次git ls-remoteHEAD 探测确认该 GitHub 仓库真实存在，才触发远程打包；若探测失败（例如拼错本地路径src/uitls），则回退到本地路径处理，不会误触发克隆。

--remote-branch支持分支名、tag 名或完整 commit SHA，默认使用仓库默认分支。远程仓库相关选项见 Remote Repository Options。如需远程仓库的详细说明，可参考远程仓库处理指南。

通过 stdin 传入文件列表

--stdin让你把文件路径通过管道（pipe）传给 Repomix，获得最灵活的文件选择能力：

# 用 find 查找文件 find src -name "*.ts" -type f | repomix --stdin # 用 git 获取被跟踪的文件 git ls-files "*.ts" | repomix --stdin # 用 ripgrep (rg) 查找文件 rg --files --type ts | repomix --stdin # 用 grep 查找包含特定内容的文件 grep -l "TODO" **/*.ts | repomix --stdin # 用 ripgrep 查找包含特定内容的文件 rg -l "TODO|FIXME" --type ts | repomix --stdin # 用 sharkdp/fd 查找文件 fd -e ts | repomix --stdin # 用 fzf 从所有文件中交互选择 fzf -m | repomix --stdin # 先用 find 过滤再用 fzf 交互选择 find . -name "*.ts" -type f | fzf -m | repomix --stdin # 用 ls 配合 glob 模式 ls src/**/*.ts | repomix --stdin # 从包含文件路径列表的文件中读取 cat file-list.txt | repomix --stdin # 直接用 echo 传入 echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin

--stdin的实现细节（见 fileStdin.ts）：

空行与注释行会被过滤：以#开头的行视为注释直接丢弃（filterValidLines）；
路径可相对可绝对：相对路径基于当前工作目录解析为绝对路径，且自动去重（resolveAndDeduplicatePaths）；
必须通过管道传入：若 stdin 是交互式终端（TTY），会直接报错No data provided via stdin. Please pipe file paths to repomix when using --stdin flag.；
不能同时指定目录参数：stdin 模式下位置目录参数会被拒绝（见 defaultAction.ts）。

[!NOTE] 通过 stdin 指定的文件会被追加到 include 模式中，因此正常的包含/排除行为仍然生效：即便文件在 stdin 里列出，只要它命中 ignore 排除模式，仍然会被剔除。

代码压缩

在保留代码结构（类、函数、接口）的前提下显著减少 token 数量：

repomix --compress # 也可用于远程仓库 repomix --remote yamadashy/repomix --compress

--compress的底层实现采用Tree-sitter 解析提取代码骨架，即"提取本质代码结构（类、函数、接口）"，见 CLI 选项说明。仓库src/core/treeSitter/目录下包含针对 C/C++/C#/Go/Java/JavaScript/Python/Ruby/Rust/Swift/TypeScript/Vue 等多种语言的解析查询文件。详细机制可参考代码压缩指南。

Git 集成

将 Git 信息打包进输出，为 AI 分析提供开发上下文：

# 包含 git diff（未提交的改动） repomix --include-diffs # 包含 git commit 日志（默认最近 50 条） repomix --include-logs # 指定包含的 commit 数量 repomix --include-logs --include-logs-count 10 # 同时包含 diff 与日志 repomix --include-diffs --include-logs

这些选项带来的额外价值：

最近的改动：git diff 展示尚未提交的修改；
开发模式：git 日志揭示哪些文件经常一起被改动；
提交历史：最近的 commit message 反映开发重点；
文件关联：理解同一批 commit 中哪些文件被协同修改。

源码实现上，--include-diffs会并行获取工作树 diff与暂存区（staged）diff两部分内容，见 gitDiffHandle.ts；--include-logs默认取最近 50 条提交，数量由--include-logs-count控制（cliRun.ts），日志解析在 gitLogHandle.ts 中按空字符（\x00）分隔提交记录，以稳健处理含换行的 commit message。--include-logs-count必须是非负整数，否则会校验报错。

Token 数量优化

了解代码库的 token 分布对优化 AI 交互至关重要。使用--token-count-tree可视化整个项目的 token 占用：

repomix --token-count-tree

该命令会显示带 token 计数的层级视图：

🔢 Token Count Tree: ──────────────────── └── src/ (70,925 tokens) ├── cli/ (12,714 tokens) │ ├── actions/ (7,546 tokens) │ └── reporters/ (990 tokens) └── core/ (41,600 tokens) ├── file/ (10,098 tokens) └── output/ (5,808 tokens)

也可以设置最小 token 阈值，聚焦大文件：

repomix --token-count-tree 1000 # 只显示 token ≥ 1000 的文件/目录

阈值必须是非负整数（cliRun.ts），未带参数时显示全部条目。树形结构的构建在 buildTokenCountStructure.ts 中完成，目录的 token 数为其下所有文件的累加和；渲染与阈值过滤逻辑见 tokenCountTreeReporter.ts。

这个功能帮助你：

识别 token 大户：找出可能撑爆 AI 上下文窗口的文件；
优化文件选择：结合--include与--ignore精确控制打包范围；
规划压缩策略：优先压缩贡献最大的文件；
权衡内容与上下文：为 AI 分析准备恰到好处的代码量。

此外还可配合--token-budget <number>在输出超过 N 个 token 时以非零退出码失败，作为 CI/Agent 上下文限额的护栏（见 cliRun.ts），以及用--token-count-encoding指定计数模型（默认o200k_base，即 GPT-4o 的 tokenizer，定义于 cliRun.ts）。

输出格式

四种输出风格，默认 XML：

repomix --style xml # XML（默认） repomix --style markdown # Markdown repomix --style json # JSON repomix --style plain # 纯文本

--style值不区分大小写，在 buildCliConfig 中统一转为小写。输出结构通常包含文件摘要、目录树、文件内容等区块，可用--no-file-summary、--no-directory-structure、--no-files分别关闭。各格式的详细说明见输出格式指南。

附加选项

删除注释

repomix --remove-comments

支持的语言范围与细节见删除注释指南。

显示行号

repomix --output-show-line-numbers

为输出中的每一行代码前缀行号，便于 AI 分析时精确引用位置。

复制到剪贴板

repomix --copy

打包完成后自动把结果复制到系统剪贴板，方便直接粘贴到对话窗口。

关闭安全检查

repomix --no-security-check

默认情况下 Repomix 会扫描 API Key、密码等敏感信息（见安全指南），--no-security-check可跳过该扫描。在 buildCliConfig 中，只有显式传入--no-security-check（即securityCheck === false）才会覆盖配置文件的默认开启状态。

配置

初始化配置文件：

repomix --init

该命令会在当前目录生成repomix.config.json（加--global则写入主目录），仓库自带的 repomix.config.json 就是一份可参考的真实配置，其中展示了input.maxFileSize（最大文件大小，默认 50000000 字节）、output.style、output.git.includeDiffs/includeLogs、ignore.useGitignore、security.enableSecurityCheck、tokenCount.encoding等字段的典型用法。全部配置项详见配置指南。