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 是一款将整个代码仓库压缩打包为单一文件的 CLI 工具，输出结果专为 Claude、ChatGPT、DeepSeek、Gemini 等大语言模型（LLM）设计，方便直接喂给 AI 进行分析。本文以官方使用指南（website/client/src/pt-br/guide/usage.md）为主体，系统讲解 Repomix 的核心用法：从一条命令打包整个目录，到远程仓库、stdin 文件列表、输出拆分、Git 集成、Token 计数与代码压缩等进阶场景，并结合仓库源码（如 src/core/output/outputSplit.ts、src/core/file/fileStdin.ts、src/config/configSchema.ts）深入解析底层实现原理。读完本文，你将掌握 Repomix 命令行工具的完整实操技能，并能根据项目规模灵活选择打包策略。

快速开始

安装 Repomix 后，在项目根目录执行：

repomix

即可将整个当前目录打包为默认的repomix-output.xml文件。从源码看，默认输出文件名与格式的映射定义在 src/config/configSchema.ts 的defaultFilePathMap中：XML 对应repomix-output.xml，Markdown 对应repomix-output.md，纯文本对应repomix-output.txt，JSON 对应repomix-output.json，默认样式为 XML。

Repomix 的配置解析遵循"默认值 → 配置文件 → CLI 参数"的三层合并流程（见 src/cli/actions/defaultAction.ts 中的buildMergedConfig）：先执行旧版 Repopack 配置迁移，再加载repomix.config.*文件配置，最后解析命令行参数并合并，CLI 参数优先级最高。

常见使用场景

打包指定目录

默认打包整个仓库，也可以只打包某个子目录：

repomix path/to/directory

包含特定文件

使用 glob 模式（与 fast-glob 语法一致）精确筛选要打包的文件：

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

多个模式用逗号分隔。**表示任意层级目录，*匹配单层内的任意文件名。该选项对应配置项include（src/config/configSchema.ts），CLI 层面由--include传入后经 src/shared/patternUtils.ts 拆分解析。

排除文件

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

排除规则同样支持逗号分隔的多个 glob 模式。默认情况下 Repomix 会同时启用.gitignore、.dotignore以及内置默认忽略模式（对应配置项ignore.useGitignore、ignore.useDotIgnore、ignore.useDefaultPatterns，默认均为true，见 src/config/configSchema.ts）。也就是说，即使不传--ignore，被版本管理忽略的文件和常见无关文件（如二进制、构建产物）默认也不会被打包。

将输出拆分为多个文件

当代码库很大时，打包产物可能超过某些 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等，支持小数值。单位换算规则定义在 src/shared/sizeParse.ts：kb按 1024 字节、mb按 1024×1024 字节计算，不合法输入会抛出明确错误。

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

这一保证在源码层面有直接体现：src/core/output/outputSplit.ts 的getRootEntry以路径第一个段为分组键，buildOutputSplitGroups将所有文件按顶层目录归类；当一个组超过大小上限时，subdivideSplitGroup会将该组向下一层目录细分（如src拆成src/a、src/b），但递归到底层是单个文件时则无法再拆，此时会抛出错误（outputSplit.ts）。此外，outputSplit.ts 中的makeChunkConfig显示：git diff 与 commit log 信息只会出现在第一个分片文件中，避免在后续分片中重复输出大段内容。

远程仓库

Repomix 支持直接打包 GitHub 等远程仓库，无需先克隆到本地：

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

从 src/core/git/gitRemoteParse.ts 的解析逻辑看，user/repo这类简写会被自动补全为 GitHub 完整仓库地址；URL 中的/tree/branch或/commit/sha段会被提取为ref（分支或 commit）；同时支持 Azure DevOps（dev.azure.com与*.visualstudio.com）等仓库的识别。指定--remote-branch时，对应值会作为 clone 的 ref 传入（参见 src/cli/actions/remoteAction.ts）。

文件列表输入（stdin）

--stdin允许通过管道将文件路径列表喂给 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 # 用 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的实现细节可以从 src/core/file/fileStdin.ts 中确认：

空行与注释被过滤：filterValidLines（fileStdin.ts）会剔除空行和以#开头的注释行，因此可以在文件列表中写注释说明；
路径解析与去重：resolveAndDeduplicatePaths（fileStdin.ts）把相对路径基于当前工作目录解析为绝对路径，并用 Set 去重，相对/绝对路径均可；
交互终端报错：如果 stdin 是 TTY（没有管道输入），会抛出"No data provided via stdin"错误；
不能混用目录参数：src/cli/actions/defaultAction.ts 中校验，使用--stdin时不允许再传目录参数。

同时要注意：通过--stdin指定的文件在效果上被添加进 include 模式，因此常规的 include/ignore 规则依然生效——通过 stdin 指定的文件如果命中了排除规则，仍会被排除。

代码压缩

在保留代码结构的前提下降低 Token 计数：

repomix --compress # 也可以与远程仓库结合使用： repomix --remote yamadashy/repomix --compress

--compress对应配置项output.compress（默认false）。压缩的具体规则（支持的语法、注释精简策略等）参见代码压缩指南，底层解析基于 tree-sitter 完成，可在 src/core/treeSitter 目录中查看各语言的具体解析策略实现。

Git 集成

引入 Git 信息，为 AI 分析提供开发上下文：

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

这些选项对应的默认值定义在 src/config/configSchema.ts：includeDiffs默认false、includeLogs默认false、includeLogsCount默认50，sortByChanges（按修改次数排序文件）默认true。其底层实现分别位于 src/core/git/gitDiffHandle.ts（diff 收集）与 src/core/git/gitLogHandle.ts（日志收集）。

引入这些信息能为 AI 提供宝贵上下文：

近期变更：Git diff 展示未提交的修改
开发模式：Git 日志揭示哪些文件通常一起被修改
提交历史：最近的提交信息反映开发重点
文件关联：理解哪些文件在同一批提交中被共同修改

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+ 的文件/目录

该功能的实现位于 src/cli/reporters/tokenCountTreeReporter.ts，目录树由 src/core/tokenCount/buildTokenCountStructure.ts 构建：每个目录的 Token 数为子项之和，文件和目录按名称字母序排列，低于阈值的条目会被过滤。默认的 Token 编码为o200k_base（见 src/config/configSchema.ts）。

--token-count-tree帮助你：

识别 Token 密集文件——可能超出 AI 上下文限制
优化文件筛选——借助--include和--ignore模式
规划压缩策略——精准定位最大贡献者
权衡内容与上下文——为 AI 分析准备代码

输出格式

Repomix 支持四种输出样式，默认是 XML：

XML（默认）

repomix --style xml

Markdown

repomix --style markdown

JSON

repomix --style json

纯文本

repomix --style plain

样式枚举定义在 src/config/configSchema.ts，每种样式对应不同的输出文件名（repomix-output.xml、repomix-output.md、repomix-output.json、repomix-output.txt）。各格式的生成逻辑分别位于 src/core/output/outputStyles/markdownStyle.ts、plainStyle.ts、xmlStyle.ts。各格式的详细结构说明参见输出格式指南。

其他常用选项

移除注释

repomix --remove-comments

支持的语言范围与实现细节参见注释移除指南。

显示行号

repomix --output-show-line-numbers

对应配置项output.showLineNumbers（默认false），会在输出内容的每行前附加行号。

复制到剪贴板

repomix --copy

打包完成后自动把输出内容复制到系统剪贴板，实现逻辑见 src/core/packager/copyToClipboardIfEnabled.ts。

关闭安全检查

repomix --no-security-check

Repomix 默认开启安全扫描（配置项security.enableSecurityCheck默认true，见 src/config/configSchema.ts），用于检测打包内容中可能泄露的密钥与敏感信息。Repomix 具体检测哪些内容参见安全指南，检测实现位于 src/core/security 目录。

配置文件

初始化配置文件：

repomix --init

该命令会在当前目录生成repomix.config.json（也可用--global生成全局配置），之后所有 CLI 选项都可以持久化写入配置文件。详细的配置项说明参见配置指南。仓库根目录的 repomix.config.json 就是一份现成的参考示例。

企业官网建设流程全解析