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 官方"基础用法"文档为核心骨架，完整覆盖快速开始、目录/文件精确选择、输出拆分、远程仓库处理、stdin 管道输入、代码压缩、Git 集成、Token 计数树、输出格式与配置初始化等全部实操场景，并结合当前仓库源码揭示每个功能背后的实现原理。读完本指南，你将掌握用 Repomix CLI 高效打包任意本地或远程代码库的完整技能。

快速开始：打包整个仓库

在项目根目录下直接运行以下命令，即可将当前目录的全部代码（自动遵守.gitignore等忽略规则）打包为单一输出文件：

repomix

默认情况下，Repomix 会在当前工作目录生成repomix-output.xml，采用 XML 结构组织文件内容与目录树。命令行入口与配置合并流程位于 src/cli/actions/defaultAction.ts，其核心路径是：加载配置文件 → 解析 CLI 参数 → 合并生成最终配置 → 调用pack()完成打包（对应runDefaultAction与buildMergedConfig函数）。

常用用例

打包特定目录

将目标目录作为位置参数传入即可，路径可以是相对路径：

repomix path/to/directory

从源码看，runDefaultAction会通过path.resolve(cwd, directory)将传入的相对目录解析为绝对路径后再交给打包流程，因此支持任意层级的目标目录。

通过 Glob 模式包含特定文件

使用--include配合 Glob 模式精确选择要打包的文件（语法遵循 fast-glob 模式）：

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

多个模式用逗号分隔。在 buildCliConfig 中，--include参数会通过splitPatterns拆分成模式数组写入配置的include字段，随后参与文件收集（src/core/file/fileCollect.ts），从而过滤最终进入输出的文件集合。

排除文件

使用--ignore排除不需要的文件或目录：

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

Repomix 的忽略机制是分层的：默认内置忽略模式（如.git、node_modules等）、.gitignore/.ignore文件规则与自定义--ignore模式叠加生效。在配置结构中，--ignore对应ignore.customPatterns字段。

将输出拆分为多个文件

处理大型代码库时，打包结果可能超过某些 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/mb单位（不区分大小写），kb按 1024 字节、mb按 1024×1024 字节换算，非法输入（如非正数、未知单位）会抛出明确错误。

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

这条保证的底层逻辑位于 src/core/output/outputSplit.ts：

buildOutputSplitGroups按顶层目录（root entry）把待处理文件归组；
generateSplitOutputParts以组为单位累积渲染，若某组加上已有内容超出限额，则先落盘当前部分再重试该组；
若某个组单独就超限，subdivideSplitGroup会将其按目录层级再细分（如src/细分为src/a/、src/b/），直到单个文件这一不可再分的最小单元——此时若仍超限，会抛出 "A single file cannot be split across parts" 的明确错误；
拆分文件名由buildSplitOutputFilePath生成，即在原文件名（不含扩展名）后追加.N序号再还原扩展名。

另外注意，--split-output与--stdout、--copy、--skill-generate存在冲突，validateConflictingOptions会在打包前校验并报错（参见 src/cli/actions/defaultAction.ts）。

处理远程仓库

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

# 使用 GitHub URL repomix --remote https://github.com/user/repo # 使用 owner/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：parseRemoteValue首先识别owner/repo简写并补全为https://github.com/user/repo.git（isValidShorthand校验），同时兼容 Azure DevOps 的 SSH/HTTPS 地址形式；--remote-branch对应的 ref 会作为分支、Tag 或 commit SHA 传给后续的克隆与归档流程（相关实现见 src/core/git/gitHubArchive.ts 与 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模式下传入的文件路径会被视为 include 模式的一部分，因此常规的 include/ignore 规则依然生效——通过 stdin 指定的文件如果命中 ignore 模式，仍然会被排除。

[!NOTE] 使用--stdin时，文件路径可以是相对路径或绝对路径，Repomix 会自动完成路径解析与去重。

这些行为在 src/core/file/fileStdin.ts 中有精确实现：

filterValidLines：过滤空行与#开头的注释行；
resolveAndDeduplicatePaths：相对路径基于当前工作目录解析为绝对路径，并用Set去重；
readFilePathsFromStdin：通过 readline 逐行读取直到 EOF（天然适配 fzf 这类需要时间的交互工具）；若 stdin 是 TTY（即没有管道输入）会抛出 "No data provided via stdin" 的错误，若过滤后没有有效路径则提示 "No valid file paths found in stdin input."。

同时注意，--stdin模式下不允许再传入目录位置参数，runDefaultAction会对该冲突场景直接报错（src/cli/actions/defaultAction.ts）。

代码压缩

--compress可以在保留代码结构的前提下显著减少 Token 数量，降低喂给 LLM 的成本：

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

压缩通过 tree-sitter 解析各类语言的 AST 实现，删除不影响语义的注释与空行，同时维持代码可读性。支持的编程语言、解析策略与压缩细节参见代码压缩指南以及 src/core/treeSitter 目录下的解析器实现。

Git 集成

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

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

这些上下文信息能帮助 AI 理解：

最近的改动：Git diffs 展示未提交的修改；
开发模式：Git logs 揭示哪些文件通常一起被修改；
提交历史：最近的提交信息反映开发重点；
文件关系：理解哪些文件在相同提交中被一起修改。

底层实现分别位于 src/core/git/gitDiffHandle.ts 与 src/core/git/gitLogHandle.ts：

--include-diffs会并行获取工作区 diff（git diff）与暂存区 diff（git diff --cached），非 Git 仓库时自动跳过；
--include-logs默认取includeLogsCount || 50条提交，并以\x00空字符作为提交记录分隔符解析git log输出——这比按空行切分更健壮，因为提交信息本身可能包含换行。

Token 计数优化

理解代码库的 Token 分布对优化 AI 交互至关重要。--token-count-tree以树状层级视图展示整个项目的 Token 使用情况：

repomix --token-count-tree

输出示例：

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

该功能可以帮助你：

识别 Token 大户——找出可能超出 AI 上下文限制的文件；
优化文件选择——借助--include与--ignore模式取舍；
规划压缩策略——针对最大贡献者制定定向压缩方案；
平衡内容与上下文——为 AI 分析准备代码时控制体积。

实现层面，src/core/tokenCount/buildTokenCountStructure.ts 将各文件 Token 数构建成目录树并自底向上汇总每个节点的tokenSum；src/cli/reporters/tokenCountTreeReporter.ts 负责按阈值过滤并渲染出带缩进与树形连接符的层级视图（目录显示汇总值、文件显示自身值，均按名称排序）。

输出格式

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

XML（默认格式）

repomix --style xml

Markdown

repomix --style markdown

JSON

repomix --style json

纯文本

repomix --style plain

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

附加选项

移除注释

--remove-comments会在打包前删除代码注释，进一步压缩体积：

repomix --remove-comments

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

显示行号

repomix --output-show-line-numbers

输出中为每行代码附加原始行号，便于 AI 引用具体代码位置。

复制到剪贴板

repomix --copy

打包完成后自动将输出内容复制到系统剪贴板，实现"打包即粘贴"的快捷工作流（实现见 src/core/packager/copyToClipboardIfEnabled.ts）。

禁用安全检查

默认情况下 Repomix 会对打包内容做安全检查（如检测密钥、凭据等敏感信息）。如确需关闭：

repomix --no-security-check

安全检测的具体规则与触发条件参见安全指南，检测实现在 src/core/security 目录。注意：关闭安全检查意味着敏感信息可能被直接写入输出文件，请仅在明确了解风险时使用。

配置文件

初始化配置文件：

repomix --init

该命令会在当前目录生成repomix.config.json，之后即可通过配置文件固化 include/ignore、输出样式、Git 选项等所有参数，与 CLI 参数按"CLI 覆盖文件配置、文件配置覆盖默认值"的优先级合并（合并逻辑见 src/config/configLoad.ts）。全部可配置项参见配置指南。

企业官网建设流程全解析