Repomix 基本使用完全指南：从仓库打包到 Token 优化的一站式 CLI 实战-迪斯科星球

Repomix 基本使用完全指南：从仓库打包到 Token 优化的一站式 CLI 实战

【免费下载链接】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 友好文件的命令行工具，本指南基于官方 Basic Usage 文档，系统讲解 Repomix CLI 的核心使用场景：从一条命令打包整个仓库，到按目录、glob 模式、stdin 管道精筛文件，再到远程仓库克隆、输出拆分、Git 集成、Token 统计与压缩等进阶能力。读完本文，你将能够熟练运用 Repomix 的各种命令行选项，把任意规模的项目整理成最适合喂给 Claude、ChatGPT、Gemini 等大语言模型的上下文文件。

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

在项目根目录下执行：

repomix

Repomix 会自动扫描当前目录（遵循.gitignore与默认忽略规则），收集所有代码文件，并生成默认的repomix-output.xml（XML 是默认输出格式）。

从源码看，这一过程由 pack 主流程驱动，依次完成文件搜索、路径排序、内容收集、安全扫描、文件处理、输出生成与 Token 度量：

文件搜索：searchFiles基于根目录与配置（include/ignore 模式）收集候选文件，见 fileSearch.ts；
文件收集与处理：collectFiles读取磁盘内容，随后应用文件处理器并执行processFiles，见 fileProcess.ts；
并行化：文件收集与 Git 操作（diffs/logs）通过Promise.all并行执行，互不阻塞，见 packager.ts。

常见使用场景

打包指定目录

默认打包当前目录；若要打包某个特定目录，直接把它作为位置参数传入：

repomix path/to/directory

底层会将传入目录通过path.resolve(cwd, directory)解析为绝对路径后交给pack，见 defaultAction.ts。

只包含指定文件（--include）

使用 glob 模式精确挑选要打包的文件：

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

支持逗号分隔多个模式（--include内部通过splitPatterns拆分成模式数组），匹配规则与 fast-glob 语法一致。该选项会写入配置的include字段，在文件搜索阶段与 ignore 规则共同决定哪些文件进入打包结果，见 defaultAction.ts 与 configSchema.ts。

排除文件（--ignore）

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

--ignore设置自定义排除模式（customPatterns），同时默认启用.gitignore、.ignore点文件与内置默认忽略规则；这些规则分别由useGitignore、useDotIgnore、useDefaultPatterns控制，均可通过--no-gitignore、--no-dot-ignore、--no-default-patterns显式关闭，见 defaultAction.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等，十进制小数同样有效（如2.5mb）。

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

实现细节：--split-output的值经 parseHumanSizeToBytes 解析为字节数——正则只接受kb/mb单位（大小写不敏感，1kb=1024 字节，1mb=1024² 字节），非法值或非正数会直接报错。拆分算法在 outputSplit.ts 中实现：先按路径首段（顶层目录）构建分组buildOutputSplitGroups，再逐个渲染分组并精确测量 UTF-8 字节数；若单个分组超限，会向下一层目录递归细分subdivideSplitGroup，直到拆分为单文件仍超限才抛出错误。同时，非首个分片会关闭 git diffs/logs 以避免重复的大段内容，见 makeChunkConfig。由于每次都要完整渲染当前累计的分组来精确度量大小，该算法复杂度为 O(N²)，对典型的 10~20 个顶层目录规模完全可接受（注释见 outputSplit.ts）。

注意：--split-output要求写入文件系统，因此与--stdout、--copy、--skill-generate互斥，冲突时会在运行前抛出错误，见 validateConflictingOptions。

打包远程仓库（--remote）

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

# 使用 GitHub URL repomix --remote https://github.com/user/repo # 使用 user/repo 简写 repomix --remote user/repo # 不带 --remote 的简写（自动识别） repomix user/repo # 指定分支/标签/提交 repomix --remote user/repo --remote-branch main repomix --remote user/repo --remote-branch 935b695

--remote接受 GitHub URL 或user/repo简写；--remote-branch可指定具体分支、标签或提交哈希，默认使用仓库的默认分支。相关实现可参阅 remoteAction.ts、gitHubArchive.ts 与 gitRemoteParse.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 # 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允许你把文件路径列表管道式输入 Repomix，在文件选择上提供最大灵活度。

使用--stdin时，指定的文件会被追加到 include 模式中，因此常规的 include/ignore 行为依然生效——即使通过 stdin 指定，匹配到 ignore 模式的文件仍会被排除，见 fileSearch.ts 中的显式文件合并逻辑。

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

实现细节：stdin 读取由 fileStdin.ts 承担——readFilePathsFromStdin先检测 stdin 是否为 TTY（交互终端下直接报错提示需要管道输入），再通过 readline 逐行读取直到 EOF，随后filterValidLines过滤空行与#开头的注释行，最后resolveAndDeduplicatePaths将相对路径基于当前工作目录解析为绝对路径并去重（fileStdin.ts）。使用--stdin时不能再传目录参数，校验逻辑见 defaultAction.ts。

代码压缩（--compress）

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

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

--compress借助 Tree-sitter 解析代码，抽取类、函数、接口等核心结构（详见 code-compress 指南）。解析策略定义在 src/core/treeSitter，例如 TypeScript/JavaScript 使用 queryTypescript.ts 与 queryJavascript.ts 中的查询语句，语言配置见 languageConfig.ts。配置项output.compress默认关闭（见 configSchema.ts）。

Git 集成

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

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

这为打包输出补充了极具价值的上下文：

近期变更：Git diffs 展示未提交的工作区/暂存区修改
开发模式：Git logs 揭示哪些文件通常一起被修改
提交历史：最近的提交信息反映开发重心
文件关联：理解哪些文件在同一提交中被改动

实现细节：Git 操作与文件收集并行执行（见 packager.ts）。diff 处理见 gitDiffHandle.ts，log 处理见 gitLogHandle.ts——其中以 NUL 字符（\x00）作为提交记录分隔符，避免提交信息含换行时解析错乱；--include-logs-count默认值为 50（includeLogsCount默认 50，见 configSchema.ts），非数字输入会被拒绝（cliRun.ts）。若当前目录不是 Git 仓库，相关功能会静默返回空。

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

--token-count-tree [threshold]的阈值是可选的，见 cliRun.ts。

该功能帮助你：

定位 Token 大户：识别可能超出 AI 上下文窗口的文件
优化文件选择：用--include与--ignore模式调整打包范围
规划压缩策略：针对最大的贡献者启用--compress
平衡内容与上下文：为 AI 分析准备恰到好处的代码

实现细节：Token 树由 buildTokenCountStructure.ts 生成——buildTokenCountTree把每个文件的相对路径按/拆分成目录节点（使用Map存储子目录以避免与files/tokenSum等元数据字段冲突），calculateTokenSums自底向上汇总每个目录的 Token 总和。Token 计数底层使用 gpt-tokenizer（默认编码），由 metrics/TokenCounter.ts 实现，并配套 tokenCountCache.ts 缓存以加速重复运行；工作线程池在文件搜索阶段就预先启动预热，见 packager.ts。

输出格式

--style指定输出格式，共四种：

XML（默认）

repomix --style xml

Markdown

repomix --style markdown

JSON

repomix --style json

纯文本

repomix --style plain

四种格式的渲染器分别位于 src/core/output/outputStyles（xmlStyle.ts、markdownStyle.ts、plainStyle.ts，JSON 输出另见对应实现）。CLI 传入的--style会被统一转为小写后写入配置，见 defaultAction.ts。

附加选项

删除注释

repomix --remove-comments

借助 Tree-sitter 移除代码注释以压缩体积（支持的编程语言与细节见 comment-removal 指南）。配置项默认关闭，见 configSchema.ts。

显示行号

repomix --output-show-line-numbers

在输出中为每行代码添加行号前缀，便于 AI 引用具体代码位置。

复制到剪贴板

repomix --copy

打包完成后自动把输出复制到系统剪贴板，方便直接粘贴给 AI 工具。配置项copyToClipboard默认关闭（configSchema.ts），复制动作由 copyToClipboardIfEnabled.ts 执行。

禁用安全检查

repomix --no-security-check

默认情况下 Repomix 会扫描输出内容中的敏感信息（如 API 密钥、密码等），此选项可跳过该扫描（安全检测的具体内容见 security 指南）。扫描实现在 security/securityCheck.ts 与 securityCheckWorker.ts，采用 worker 线程并行执行，并在打包完成后从结果中剔除可疑文件，见 packager.ts。

配置文件初始化

repomix --init

在项目根目录生成repomix.config.json（支持 json/yaml/ts/js 等格式），把常用的 include、ignore、输出样式等参数固化到配置文件中，替代每次手写冗长的 CLI 参数。配置的加载与合并顺序为：默认值 → 配置文件 → CLI 参数（后者优先级最高），见 buildMergedConfig 与 configLoad.ts。详细配置项说明见 configuration 指南。

企业官网建设流程全解析