Repomix 使用指南：从目录打包到远程仓库与 Token 优化的一站式实战-二趣网

Repomix 使用指南：从目录打包到远程仓库与 Token 优化的一站式实战

【免费下载链接】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 是一个将整个代码仓库打包为单一 AI 友好文件（默认 XML 格式）的命令行工具，专为向 Claude、ChatGPT、DeepSeek 等大语言模型（LLM）投喂代码而设计。本文以官方《Uso básico》（基本使用）文档为骨架，结合 CLI 入口实现与各功能模块源码，系统讲解 Repomix 的目录打包、文件筛选、输出分割、远程仓库、stdin 输入、Git 集成、Token 统计与压缩等核心用法。读完本文，你将能够熟练使用repomix命令行完成从单目录到多仓库的各种打包场景，并掌握输出格式与配置项的底层行为。

快速开始：一键打包整个仓库

在任意项目根目录直接执行：

repomix

不带任何参数时，Repomix 默认处理当前目录（.）下的全部文件，生成默认输出文件repomix-output.xml。从源码看，位置参数的定义是argument('[directories...]', 'list of directories to process', ['.'])（见 src/cli/cliRun.ts），默认值为['.']，即当前工作目录；输出路径默认repomix-output.xml，可通过-o, --output <file>覆盖，传-时输出到 stdout（见 src/cli/cliRun.ts）。

执行时 CLI 会先加载配置文件（repomix.config.*）、解析命令行参数并合并为最终配置，然后调用核心的pack()函数完成文件收集、处理与输出（见 src/cli/actions/defaultAction.ts）。

常用使用场景

打包指定目录

repomix ruta/al/directorio

位置参数支持传入一个或多个目录，Repomix 会递归收集其中的文件。源码中目录参数会被解析为绝对路径后传入打包流程（见 src/cli/actions/defaultAction.ts）。

仅包含指定文件（glob 模式）

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

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

--include接受逗号分隔的多个 glob 模式，源码中通过splitPatterns拆分为模式数组，并写入最终配置的include字段（见 src/cli/actions/defaultAction.ts）。注意该参数的作用是"仅包含匹配的文件"，而非附加文件。

排除文件

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

--ignore（简写-i）在默认忽略规则（node_modules、.git、构建目录等内置模式）与.gitignore/.ignore规则之上追加自定义排除模式，同样支持逗号分隔。若希望关闭内置默认模式或 gitignore 规则，可使用--no-default-patterns、--no-gitignore、--no-dot-ignore三个开关（定义见 src/cli/cliRun.ts）。

将输出分割为多个文件（--split-output）

打包大型代码库时，输出文件可能超过某些 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 的实现看，大小由正则^\s*(\d+(?:\.\d+)?)\s*(kb|mb)\s*$解析（不区分大小写），换算系数为kb = 1024字节、mb = 1024 * 1024字节，非法输入会直接报错。--split-output在 CLI 参数层通过argParser(parseHumanSizeToBytes)绑定该解析函数（见 src/cli/cliRun.ts）。

关于分割粒度，有一个重要行为需要了解：文件按顶层目录分组以保持上下文，单个文件或目录绝不会被拆分到多个输出文件中。从 src/core/output/outputSplit.ts 的源码可以看到，所有文件先按相对路径的第一段目录（root entry）分组；若某个组单独仍超过大小上限，会继续向下一级目录细分（subdivideSplitGroup），直到最终单个文件——单个文件无法再分，若其自身超过限制则直接报错（见 src/core/output/outputSplit.ts）。此外，只有第一份输出包含 Git diff/log 段落，避免大段重复内容（见 src/core/output/outputSplit.ts）。

[!NOTE] 输出文件命名规则：在基础文件名前插入编号，例如repomix-output.xml变为repomix-output.1.xml、repomix-output.2.xml（实现见 src/core/output/outputSplit.ts）。

打包远程仓库（--remote）

无需本地克隆即可直接打包 GitHub 仓库，支持多种写法：

# 使用 GitHub URL repomix --remote https://github.com/usuario/repositorio # 使用 owner/repo 缩写 repomix --remote usuario/repositorio # 省略 --remote，自动检测缩写（当该参数不是本地存在的路径，且确认为可访问的 GitHub 仓库时） repomix usuario/repositorio # 指定分支 / 标签 / 提交 repomix --remote usuario/repositorio --remote-branch main repomix --remote usuario/repositorio --remote-branch 935b695

远程模式的底层流程（见 src/cli/actions/remoteAction.ts）值得说明：

Repomix 会先尝试从 GitHub 下载仓库归档包（速度更快，带进度提示，1 分钟超时并自动重试 2 次）；
若归档下载失败或仓库不支持归档方式，则回退为git 浅克隆（需要系统安装 git）；
仓库被解压/克隆到临时目录后执行常规打包，最终把输出文件复制回当前目录并清理临时目录。

--remote-branch指定分支、标签或提交哈希，默认使用仓库默认分支。另外需要注意：在远程模式下，--config必须是绝对路径，以防止加载克隆仓库中的不可信配置文件（见 src/cli/actions/remoteAction.ts）。

位置参数同样支持 URL：当且仅当只有一个位置参数、且是显式远程 URL（https://、git@、ssh://、git://）时自动进入远程模式；owner/repo缩写则需满足"本地不存在该路径 + GitHub 探测可达"两个条件才会被识别为远程（见 src/cli/cliRun.ts）。

从 stdin 读取文件列表（--stdin）

--stdin允许通过管道传入文件路径列表，实现最大化的文件选择灵活性：

# 使用 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的工作机制（见 src/core/file/fileStdin.ts）：

空行与注释行（以#开头）会被过滤（filterValidLines）；
相对路径基于当前工作目录解析为绝对路径，并自动去重（resolveAndDeduplicatePaths）；
使用 readline 逐行读取并等待 EOF，因此对 fzf 这类交互式工具也能正常等待输出；
如果 stdin 是 TTY（即没有实际管道输入），会报错提示必须先管道传入路径。

需要特别留意的是：--stdin指定的文件等效于被追加到 include 模式中，即正常的 include/ignore 行为仍然生效——通过 stdin 传入的文件若命中 ignore 模式，依然会被排除。此外，--stdin模式下不能再传目录位置参数（源码中会直接报错，见 src/cli/actions/defaultAction.ts），且此时不会打印版本横幅，避免干扰 fzf 等工具的管道输出（见 src/cli/cliRun.ts）。

[!NOTE] 使用--stdin时，路径可以是相对路径或绝对路径，Repomix 会自动处理路径解析与重复项删除。

代码压缩（--compress）

在保留代码结构的前提下显著减少 Token 数：

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

--compress通过 Tree-sitter 解析提取代码的核心结构（类、函数、接口等），见 src/cli/cliRun.ts 的参数定义。更详细的原理与支持范围请参考代码压缩指南。

Git 集成（--include-diffs / --include-logs）

为 AI 分析补充开发上下文信息：

# 包含 git 工作区与暂存区的 diff（未提交的变更） repomix --include-diffs # 包含 git 提交日志（默认最近 50 条） repomix --include-logs # 指定包含的提交数量 repomix --include-logs --include-logs-count 10 # 同时包含 diff 与日志 repomix --include-diffs --include-logs

这些选项为输出添加了极具价值的上下文：

近期变更：Git diff 展示未提交的工作区与暂存区修改（src/core/git/gitDiffHandle.ts 分别通过git diff与git diff --cached获取）；
开发模式：Git 日志揭示哪些文件通常一起被修改；
提交历史：近期提交信息反映开发思路与方向；
文件关联关系：理解哪些文件在同一次提交中一同变更。

--include-logs-count默认值为 50，可通过参数覆盖（见 src/core/git/gitLogHandle.ts）。底层实现采用空字符（\x00）作为记录分隔符来解析git log输出，可稳健处理包含换行符的提交信息（见 src/core/git/gitLogHandle.ts）。另外，若目标目录不是 git 仓库，diff/log 获取会静默跳过，不会报错中断（见 src/core/git/gitDiffHandle.ts）。

Token 计数优化（--token-count-tree）

理解代码库的 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 # 只显示 1000+ tokens 的文件/目录

该选项在 CLI 层接受一个可选数字参数，非数字输入会被拒绝（见 src/cli/cliRun.ts）；树形渲染逻辑位于 src/cli/reporters/tokenCountTreeReporter.ts，目录按字母序排列，文件与子目录分别输出，并会过滤掉低于阈值的条目。

Token 树可以帮助你：

识别高 Token 文件——它们可能超出 AI 的上下文限制；
优化文件选择——借助--include与--ignore模式；
规划压缩策略——优先针对贡献最大的文件；
平衡内容与上下文——为 AI 分析准备恰当的代码量。

相关补充：--token-count-encoding可指定 Token 计数模型（默认o200k_base，对应 GPT-4o），--token-budget <number>可在输出超出指定 Token 数时以非零退出码失败，适合作为 CI/Agent 上下文限制的护栏（见 src/cli/cliRun.ts）。

输出格式

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

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

各格式的详细说明（模板结构、文件摘要、目录树等）参见输出格式指南。

其他常用选项

删除注释（--remove-comments）

repomix --remove-comments

打包前剥离所有代码注释以进一步压缩体积，支持的语言范围详见注释删除指南。

显示行号（--output-show-line-numbers）

repomix --output-show-line-numbers

在输出的每一行前加上原始行号，便于 AI 回复时精确引用代码位置。

复制到剪贴板（--copy）

repomix --copy

打包完成后自动将输出复制到系统剪贴板，省去手动打开文件的步骤（底层由 src/core/packager/copyToClipboardIfEnabled.ts 实现）。

禁用安全检查（--no-security-check）

repomix --no-security-check

默认情况下 Repomix 会扫描 API 密钥、密码等敏感信息。该选项跳过扫描，仅在明确信任内容时使用。Repomix 具体检测哪些敏感信息，见安全指南。

配置管理

初始化配置文件：

repomix --init

该命令会在当前目录生成带默认值的repomix.config.json（--global可改为写入用户主目录）。此后 CLI 启动时会自动加载配置文件，并按"默认值 < 配置文件 < 命令行参数"的优先级合并（合并逻辑见 src/cli/actions/defaultAction.ts）。CLI 中使用的--no-*系列开关（如--no-file-summary、--no-directory-structure）只有在显式指定时才覆盖配置文件中的对应值，从而保证配置文件拥有默认控制权（见 src/cli/actions/defaultAction.ts 的注释说明）。

更详细的配置项说明（include/ignore、output、tokenCount、security 等完整 schema）请参考配置指南。

企业官网建设流程全解析