Repomix 使用指南：从仓库打包到 Git 集成与 Token 优化的完整实战手册-酒店常州论坛

Repomix 使用指南：从仓库打包到 Git 集成与 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 友好文件的命令行工具，方便你把代码库直接喂给 Claude、ChatGPT、DeepSeek、Gemini 等大语言模型。本文以官方使用指南为核心，结合仓库源码，系统讲解 Repomix 的常用打包场景、输出格式、Git 集成、Token 优化与配置初始化，读完你即可熟练使用 CLI 完成目录打包、远程仓库处理、文件筛选、输出拆分与代码压缩等全套操作。

快速开始：一条命令打包整个仓库

在任意项目根目录下，直接运行：

repomix

Repomix 会自动收集当前目录下的全部代码文件（自动遵循.gitignore、.ignore等规则），并按默认格式生成打包输出文件，一次调用即可获得可供 LLM 分析的单文件产物。这也是后续所有高级用法的起点——所有选项都可以叠加在repomix基础命令之上。

常用打包场景

打包指定目录

默认打包当前目录，也可以通过位置参数指定任意目录：

repomix path/to/directory

从源码看，目录参数在 src/cli/actions/defaultAction.ts 中会经path.resolve(cwd, directory)解析为绝对路径后再进入打包流程，因此相对路径与绝对路径均可使用。

包含指定文件（include）

如果只想打包特定类型或特定路径的文件，使用--include配合 glob 模式：

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

--include支持逗号分隔的多个 glob 模式，内部通过 src/shared/patternUtils.ts 的splitPatterns拆分为模式数组后写入配置（见 defaultAction.ts），随后与默认包含模式合并生效。glob 语法遵循 fast-glob 的 pattern syntax，支持**（任意层级）、*（单层通配）与花括号扩展等。

排除指定文件（ignore）

与 include 相对，--ignore用于排除不需要进入打包输出的文件：

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

--ignore同样支持逗号分隔的多个模式。需要说明的是，ignore 模式的优先级高于 include：即使某个文件同时被--include命中，只要匹配 ignore 模式，最终仍会被排除（这一点与下文 stdin 输入的行为一致）。

拆分输出为多个文件（--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 揭示了单位换算规则：kb按 1024 字节、mb按 1024×1024 字节计算，正则^\s*(\d+(?:\.\d+)?)\s*(kb|mb)\s*$/i表明单位大小写不敏感、前导空格会被容忍、数值必须为正。

[!NOTE] 拆分时文件会按顶层目录分组，以保留目录上下文；单个文件或单个目录永远不会被拆散到多个输出文件中。

拆分算法的细节见 src/core/output/outputSplit.ts：它先把所有文件按顶层目录（如src/、docs/）分组，再按组逐个渲染并测量 UTF-8 字节数。若某个分组自身就超过上限，会沿目录树向下细分一级（subdivideSplitGroup），直到每组都能容纳；当细分到单文件仍然超限时才会报错退出。此外，只有第一个分片会包含 Git diff/log 内容（makeChunkConfig会关闭后续分片的includeDiffs与includeLogs），避免大段重复信息占用额度。

打包远程仓库（--remote）

无需先手动 clone，Repomix 可以直接打包远程仓库：

# 使用 GitHub URL repomix --remote https://github.com/user/repo # 使用 owner/repo 简写 repomix --remote user/repo # 省略 --remote（自动识别简写） repomix user/repo # 指定 branch / tag / 特定 commit repomix --remote user/repo --remote-branch main repomix --remote user/repo --remote-branch 935b695

从 src/core/git/gitRemoteParse.ts 可以看到：

user/repo简写会被自动补全为https://github.com/user/repo.git（isValidShorthand判断）；
同时支持 Azure DevOps 仓库（含 SSH、HTTPS 与 legacy*.visualstudio.com域名）；
URL 中/tree/<branch>、/commit/<sha>形式的 ref 会被解析出来，与--remote-branch等价。

执行流程（src/cli/actions/remoteAction.ts）为：若是 GitHub 仓库，优先尝试下载归档（带 60 秒超时与 2 次重试），失败后自动回退到 git 浅克隆；随后在临时目录中对克隆结果执行与本地一致的打包流程。远程模式下--config只允许绝对路径，以避免从克隆仓库中加载不可信的配置文件。

stdin 文件列表输入

--stdin允许你把文件路径列表通过管道喂给 Repomix，从而获得选择文件的最高灵活性：

# 使用 find 找出所有 TS 文件 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的使用要点：

stdin 指定的文件会叠加到 include 模式上，因此 include/ignore 的常规行为依然生效——如果某个文件匹配 ignore 模式，即使通过 stdin 传入也会被排除；
路径可以是相对路径或绝对路径，Repomix 会自动处理路径解析与去重；
若在交互式终端（TTY）下使用--stdin而未提供管道输入，会直接报错提示。

底层实现在 src/core/file/fileStdin.ts：filterValidLines会剔除空行以及#开头的注释行；resolveAndDeduplicatePaths把相对路径基于当前工作目录解析为绝对路径并用 Set 去重；读取过程通过 readline 逐行收集，等待 EOF 后才返回全部路径，因此像 fzf 这类需要时间的交互式工具也能正常工作。

代码压缩（--compress）

在尽量保留代码结构的前提下减少 token 数量：

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

压缩的详细机制见压缩指南。配置层面，compress默认值为false（见 src/config/configSchema.ts），开启后会在打包阶段对文件内容做结构感知的精简处理，适合在上下文窗口紧张时使用。

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

把 Git 信息一并打包，为 AI 分析提供开发上下文：

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

这些选项对应的配置默认值可在 src/config/configSchema.ts 中确认：includeDiffs默认为false，includeLogs默认为false，includeLogsCount默认为50，最小值 1。开启后输出会额外提供：

最近变更：git diff 展示尚未提交的修改；
开发模式：git log 揭示哪些文件通常一起被修改；
提交历史：最近的提交信息反映开发重点；
文件关联：帮助理解哪些文件在同一提交中被同时改动。

Git 相关处理分布在 src/core/git/ 目录，如 diff 计算在gitDiffHandle.ts、log 获取在gitLogHandle.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 # 只显示 token 数 ≥ 1000 的文件/目录

实现层面（src/cli/reporters/tokenCountTreeReporter.ts 与 src/core/tokenCount/buildTokenCountStructure.ts）：文件路径按/拆分构建树形结构，目录的 token 数由其下所有文件与子目录递归汇总（calculateTokenSums），展示时按字母序排序并只显示达到阈值的条目。token 计数基于gpt-tokenizer的编码实现（src/core/metrics/TokenCounter.ts），编码可配置。

它可以帮助你：

定位高 token 文件：识别可能撑爆 AI 上下文上限的大文件；
优化文件筛选：用--include/--ignore调整打包范围；
规划压缩策略：针对 token 贡献最大的文件优先压缩；
平衡内容与上下文：为 AI 分析准备恰到好处的代码材料。

输出格式

Repomix 支持四种输出格式，通过--style指定：

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

各格式的渲染器分别位于 src/core/output/outputStyles/（markdownStyle.ts、plainStyle.ts、xmlStyle.ts，JSON 对应测试见 tests/core/output/outputStyles/jsonStyle.test.ts）。详细对比可参考输出格式指南。

附加选项

删除注释

repomix --remove-comments

支持的语言列表与细节见注释删除指南。配置默认值为false，开启后打包时会剥离源码注释以压缩体积。

显示行号

repomix --output-show-line-numbers

输出内容中的每个文件会带上行号，便于 AI 回复时引用精确位置。showLineNumbers默认值为false（见 configSchema.ts）。

复制到剪贴板

repomix --copy

打包完成后自动把输出内容复制到系统剪贴板，方便直接粘贴到 AI 对话中。对应的copyToClipboard配置默认值为false，复制逻辑见 src/core/packager/copyToClipboardIfEnabled.ts。

关闭安全检查

repomix --no-security-check

Repomix 默认会对打包文件做安全检查（如检测密钥等敏感信息）。此选项用于显式关闭该检查，具体检测内容参见安全指南。相关实现位于 src/core/security/，其中securityCheck.ts负责整体流程，validateFileSafety.ts负责文件级校验。

配置文件初始化

repomix --init

该命令在当前目录生成repomix.config.*配置文件模板，后续可通过配置文件固化 include/ignore、输出格式、token 预算等全部选项，替代每次手写冗长的 CLI 参数。完整的配置项说明见配置指南，配置加载与合并逻辑见 src/config/configLoad.ts 和 src/config/configSchema.ts。

企业官网建设流程全解析