Repomix 命令行选项完全指南：覆盖输入输出、文件筛选、远程仓库与 MCP 的 CLI 参数实战手册

Repomix 命令行选项完全指南覆盖输入输出、文件筛选、远程仓库与 MCP 的 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/repomixRepomix 是一个把整个代码仓库打包成单个 AI 友好文件XML / Markdown / JSON / Plain的命令行工具其全部能力都通过 CLI 参数暴露。本文以官方文档《Command Line Options》为骨架逐项讲解 Repomix 从输入输出、文件选择、远程仓库、配置管理、安全扫描、Token 计数到 MCP 服务器与 Agent Skills 生成的每一类命令行选项并深入仓库源码src/cli/cliRun.ts、src/config/configSchema.ts 等说明各参数的默认值、校验规则与底层实现。读完本文你将能熟练组合这些参数把 Repomix 灵活接入本地开发、CI 流水线与 AI Agent 工作流。一、CLI 参数体系总览Repomix 的 CLI 基于 Commander.js 构建入口位于 src/cli/cliRun.ts所有选项按语义划分为多个分组Basic Options基础选项CLI Input/Output OptionsCLI 输入/输出Repomix Output Options输出格式File Selection Options文件选择Remote Repository Options远程仓库Configuration Options配置管理Security Options安全Token Count OptionsToken 计数MCPModel Context ProtocolSkill GenerationAgent Skills 生成Watch Mode监视模式runClisrc/cli/cliRun.ts#L336是核心分发函数它会先判断是否为 stdout 模式--output -会被隐式转换为--stdout随后校验--watch的冲突选项、设置日志级别--quiet为 SILENT、--verbose为 DEBUG、--stdout强制 SILENT再按优先级依次分发到版本输出、--init、远程仓库、自动检测的远程 URL、--watch、GitHub 短格式owner/repo和本地默认打包流程。值得留意的一个易用性细节仓库在 src/cli/cliRun.ts#L16-L49 内置了一张语义建议映射表当用户输入了不存在的选项如--exclude、--format、--silent时Repomix 会给出Did you mean: --ignore?之类的智能提示而不是直接报错。二、基础选项与 CLI 输入/输出选项基础选项选项说明-v, --version显示工具版本信息后退出--version通过runVersionAction输出版本号在runCli中版本检查发生在--init、--remote等动作之前src/cli/cliRun.ts#L384-L388。CLI 输入/输出选项选项说明--verbose开启详细 debug 日志显示文件处理过程、Token 数量与配置细节--quiet除错误外抑制所有控制台输出适合脚本场景--stdout将打包结果直接写入 stdout 而非文件同时抑制所有日志--stdin从 stdin 按每行一个路径读取文件列表指定文件被直接处理--copy处理完成后将生成结果复制到系统剪贴板--token-count-tree [threshold]显示带 Token 数的文件树可传可选阈值只显示 ≥N Token 的文件如--token-count-tree 100--top-files-len number摘要中显示的最大文件数量默认5源码层面的校验规则src/cli/cliRun.ts#L61-L100--verbose与--quiet互斥.conflicts(quiet)--stdout与--output互斥--token-count-tree与--top-files-len的值必须是非负整数否则抛出RepomixError--top-files-len对应配置项output.topFilesLength默认值 5 定义在 src/config/configSchema.ts#L140。stdin 模式的实现位于 src/cli/actions/defaultAction.ts#L131-L145使用--stdin时不允许再传入目录位置参数只能为.文件路径经由readFilePathsFromStdin读取。该模式特别适合与find、git ls-files等命令配合见下文示例。三、Repomix 输出选项选项说明-o, --output file输出文件路径默认repomix-output.xml传-表示输出到 stdout--style style输出格式xml、markdown、json、plain默认xml--output-file-path-style style输出中文件路径的显示方式target-relative或cwd-relative默认target-relative--parsable-style转义特殊字符以保证 XML/Markdown 合法当输出含破坏格式的代码时必需--compress使用 Tree-sitter 解析提取核心代码结构类、函数、接口--output-show-line-numbers在输出中为每一行代码添加行号前缀--no-file-summary从输出中省略文件摘要部分--no-directory-structure从输出中省略目录树可视化--no-files只生成元数据而不含文件内容适合仓库分析--remove-comments打包前去除所有代码注释--remove-empty-lines去除所有文件中的空行--truncate-base64截断过长的 base64 数据字符串以减小输出体积--header-text text在输出开头加入自定义文本--instruction-file-path path指定包含自定义指令的文件路径将其内容包含进输出--split-output size将输出拆分为多个编号文件如repomix-output.1.xml尺寸支持500kb、2mb、1.5mb等--include-empty-directories在目录结构中包含无文件的文件夹--include-full-directory-structure即使在用--include模式时也在目录结构部分显示完整仓库树--no-git-sort-by-changes不按 git 变更频率排序文件默认变更最多的文件排最前--include-diffs添加 git diff 部分展示工作区与暂存区变更--include-logs添加带提交信息与变更文件的 git 提交历史--include-logs-count count--include-logs要包含的最近提交数默认50源码视角的默认值与校验这些选项与配置文件的映射关系集中在buildCliConfigsrc/cli/actions/defaultAction.ts#L215对应默认值可在 src/config/configSchema.ts 中查到输出风格默认xml四种风格对应的默认文件名映射为repomix-output.xml/repomix-output.md/repomix-output.txt/repomix-output.jsonsrc/config/configSchema.ts#L14-L19--output-file-path-style使用.choices([target-relative, cwd-relative])限制取值范围src/cli/cliRun.ts#L105-L110--split-output的值通过parseHumanSizeToBytessrc/shared/sizeParse.ts解析为字节数因此支持500kb、2mb、1.5mb这类人类可读写法--no-*系列标志遵循只有显式传 false 才覆盖配置文件的原则src/cli/actions/defaultAction.ts#L207-L214以保证配置文件中的设定不被 CLI 隐式覆盖git 相关默认值sortByChanges默认true最多统计 100 条提交、includeDiffs默认false、includeLogs默认false、includeLogsCount默认50src/config/configSchema.ts#L150-L156。输出选项的冲突校验validateConflictingOptionssrc/cli/actions/defaultAction.ts#L437-L474内置了 5 组输出级冲突检测--split-output不能与--stdout同用拆分需要写文件系统--split-output不能与--skill-generate同用Skill 输出是目录--split-output不能与--copy同用拆分产生多个文件--skill-generate不能与--stdout同用--skill-generate不能与--copy同用Skill 输出是目录无法复制到剪贴板。四、文件选择选项选项说明--include patterns只包含匹配这些 glob 模式的文件逗号分隔如src/**/*.js,*.md-i, --ignore patterns额外的排除模式逗号分隔如*.test.js,docs/**--no-gitignore不使用.gitignore规则过滤文件--no-dot-ignore不使用.ignore规则过滤文件--no-default-patterns不应用内置忽略模式node_modules、.git、构建目录等在buildCliConfig中--include与--ignore通过splitPatternssrc/shared/patternUtils.ts按逗号切分为数组而--no-gitignore、--no-dot-ignore、--no-default-patterns都只在显式为 false 时才写入cliConfig.ignoresrc/cli/actions/defaultAction.ts#L221-L241。对应的默认配置均为开启useGitignore: true、useDotIgnore: true、useDefaultPatterns: truesrc/config/configSchema.ts#L159-L164。文件过滤的实际执行链路可进一步参考 src/core/file/fileSearch.tsgitignore 规则处理与 src/config/defaultIgnore.ts内置忽略模式相关行为有专门的测试覆盖如 tests/core/file/fileSearch.gitignoreSpec.test.ts 与 tests/core/file/dotIgnoreSpec.test.ts。五、远程仓库选项选项说明--remote url克隆并打包远程仓库支持 GitHub URL 或user/repo格式--remote-branch name指定分支、tag 或 commit默认仓库默认分支--remote-trust-config信任并加载远程仓库中的配置文件。被信任的配置可以执行命令、读取本地文件因此只应对完全信任的仓库使用出于安全默认关闭。在交互式终端上会显示配置并请求确认下载策略归档优先git 兜底runRemoteActionsrc/cli/actions/remoteAction.ts#L21实现了完整的远程打包流程创建临时目录 → 下载仓库 → 运行默认打包 → 把输出文件复制回当前目录 → 校验 Token 预算 → 清理临时目录。下载采用双通道策略GitHub 归档下载若目标是 GitHub 仓库且支持归档下载先尝试通过downloadGitHubArchive下载仓库归档带 60 秒超时、2 次重试与进度显示此时无需本地安装 gitgit clone 兜底归档下载失败或非 GitHub 仓库时回退到execGitShallowClone浅克隆此时会先检查 git 是否已安装未安装则抛出明确错误并通过getRemoteRefs获取远端引用用于解析分支/tag/commit。远程模式还支持位置参数自动检测当位置参数是显式远程 URLhttps://、git、ssh://、git://或符合owner/repo格式且本地不存在同名路径、且 GitHub 上确认可达时无需--remote也能直接打包src/cli/cliRun.ts#L407-L446。远程配置信任机制--remote-trust-config触发confirmRemoteConfigTrust确认流程src/cli/actions/remoteAction.ts#L107-L121也支持通过环境变量REPOMIX_REMOTE_TRUST_CONFIGtrue开启。信任后才会加载远程仓库自带的配置文件并启用其 file processors可执行任意命令这正是默认关闭的原因。此外远程模式下--config必须传绝对路径以防止从被克隆的仓库中加载配置src/cli/actions/remoteAction.ts#L38-L44。六、配置选项选项说明-c, --config path使用自定义配置文件替代repomix.config.json--init用默认设置创建新的repomix.config.json--global与--init配合在 home 目录而非当前目录创建配置runInitActionsrc/cli/actions/initAction.ts#L19是一个交互式向导包含两步先询问是否创建repomix.config.json交互选择输出风格与文件路径默认风格来自defaultConfig.output.style默认文件名来自defaultFilePathMap再询问是否创建.repomixignore文件全局模式下跳过。已存在文件时会请求覆盖确认。最终写入的配置包含$schema字段与默认值合并结果src/cli/actions/initAction.ts#L106-L117。buildMergedConfigsrc/cli/actions/defaultAction.ts#L38展示了配置的合并顺序默认配置 → 文件配置repomix.config.json或-c指定→ CLI 配置后者优先级最高。七、安全选项选项说明--no-security-check跳过对 API 密钥、密码等敏感数据的扫描谨慎使用可能把机密暴露在输出中安全扫描默认开启enableSecurityCheck默认truesrc/config/configSchema.ts#L165-L167底层实现位于 src/core/security/securityCheck.ts工作线程逻辑见 src/core/security/workers/securityCheckWorker.ts。与--no-gitignore等标志相同--no-security-check也只在显式传 false 时才覆盖配置src/cli/actions/defaultAction.ts#L282-L284。八、Token 计数选项选项说明--token-count-encoding encoding用于计数的 tokenizer 模型o200k_baseGPT-4o、cl100k_baseGPT-3.5/4等默认o200k_base--token-budget number当打包输出超过 N 个 Token 时以非零退出码失败。适合作为 CI 流水线与 Agent 工作流中的防护让输出保持在目标模型的上下文窗口内。输出仍会生成仅由退出码标示超限支持的编码集合定义在 src/core/metrics/tokenEncodings.ts#L3[o200k_base, cl100k_base, p50k_base, p50k_edit, r50k_base]默认o200k_basesrc/config/configSchema.ts#L168-L170。该模块被刻意独立出来避免configSchema的启动加载拖入gpt-tokenizer。--token-budget的校验逻辑在validateTokenBudgetsrc/cli/cliTokenBudget.ts#L13当总 Token 数超过预算时抛出RepomixError提示可用--compress减小输出、用--include/--ignore收窄范围或调高--token-budget。注意它属于输出已生成后的后置守卫——失败的是退出码而非打包过程本身远程模式下该检查会被延迟到输出复制出临时目录之后执行src/cli/actions/remoteAction.ts#L180-L197避免超限时输出随临时目录一起被清理。九、MCP 选项选项说明--mcp以 Model Context Protocol 服务器模式运行用于 AI 工具集成--sandbox [dir]与--mcp搭配把 MCP 服务器的文件工具限制在工作区目录内默认是当前工作目录如--sandbox path/to/project。所有路径都相对于该根目录绝对路径/主机路径被拒绝且远程打包、Skill 生成、附加外部输出均被禁用MCP 服务器模式的相关文档见 MCP 服务器指南。从源码看src/cli/cliRun.ts#L367-L382--sandbox不带值时回退到当前工作目录沙箱根目录会经过canonicalizeSandboxRoot规范化解析符号链接Windows 短路径异常时有词法回退以确保路径守卫、输出虚拟化与错误清洗三者的口径一致--sandbox在没有--mcp时只会给出警告而不会生效。MCP 服务器的完整工具集实现见 src/mcp/mcpServer.ts 与 src/mcp/pathScope.ts。十、Agent Skills 生成选项选项说明--skill-generate [name]生成 Claude Agent Skills 格式的输出到.claude/skills/name/目录省略时自动生成名称--skill-project-name name覆盖生成的 Skills 描述中使用的项目名--skill-output path直接指定 Skill 输出目录路径跳过位置提示-f, --force跳过所有确认提示覆盖 Skill 目录、远程配置信任Skill 生成的名称默认从目录或远程 URL 推导generateDefaultSkillName/generateDefaultSkillNameFromUrl。--skill-output、--skill-project-name、--force都只能与--skill-generate搭配使用单独使用会直接报错src/cli/actions/defaultAction.ts#L94-L110。本地模式下未传--skill-output时会通过promptSkillLocation交互询问输出位置远程模式下默认 Skill 名称从 URL 推导且 Skill 直接写入目标目录而非临时目录。十一、Watch 监视模式选项说明-w, --watch监视文件变化并自动重新打包。新增、修改、删除的文件都会被检测快速连续变化会被去抖300ms每次重建后打印时间戳。按CtrlC停止runWatchActionsrc/cli/actions/watchAction.ts#L58的底层实现要点基于 chokidar 监视目录而非单个文件以便发现新文件忽略谓词buildWatchIgnoreFilter见 src/cli/actions/watch/watchIgnore.ts与打包器保持一致避免监视node_modules、.git等目录防止大型项目 EMFILE 与无谓重建awaitWriteFinish稳定阈值为 100ms防止半写文件被中途打包src/cli/actions/watchAction.ts#L22300ms 去抖REBUILD_DEBOUNCE_MS合并快速事件重建守卫防止并发打包若重建期间又发生变更会排队一次后续重建重建完成时间戳用toTimeString().split( )[0]生成 24 小时制HH:MM:SS保证跨平台一致src/cli/actions/watchAction.ts#L167优雅退出SIGINT/SIGTERM触发 cleanup幂等重复 CtrlC 安全先关 watcher 再等飞行中的重建完成。Watch 模式的不兼容限制监视模式只支持本地目录因此不能与以下选项组合src/cli/cliRun.ts#L265-L296--remote或位置参数形式的远程 URL--stdoutWatch 写入文件--stdinWatch 自动发现文件--copy每次变更都重新打包会反复覆盖剪贴板--split-output拆分文件会被 watcher 自己捡到形成循环--skill-generate。这些限制无论选项来自命令行还是配置文件都生效——watchAction会在合并配置后再次逐项校验src/cli/actions/watchAction.ts#L77-L101因为cliRun中的 CLI 校验看不到配置文件里的设置。十二、组合使用完整示例合集以下示例覆盖了绝大多数实战场景可直接复制运行示例出自官方文档# 基本用法当前目录打包为默认的 repomix-output.xml repomix # 自定义输出文件与格式 repomix -o my-output.md --style markdown repomix -o my-output.json --style json # 输出到 stdout repomix --stdout custom-output.txt # 输出到 stdout 后管道给其他命令如 simonw/llm repomix --stdout | llm 请解释这段代码是做什么的。 # 自定义输出 代码压缩 repomix --compress # 按每份大小拆分输出 repomix --split-output 20mb # 用模式处理特定文件 repomix --include src/**/*.ts,*.md --ignore *.test.js,docs/** # 远程仓库指定分支 repomix --remote https://github.com/user/repo/tree/main # 远程仓库指定 commit repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1 # 远程仓库短格式 repomix --remote user/repo # 远程仓库短格式自动检测无需 --remote repomix user/repo # 用 stdin 提供文件列表 find src -name *.ts -type f | repomix --stdin git ls-files *.js | repomix --stdin echo -e src/index.ts\nsrc/utils.ts | repomix --stdin # Git 集成 repomix --include-diffs # 包含未提交变更的 git diff repomix --include-logs # 包含 git 日志默认最近 50 条提交 repomix --include-logs --include-logs-count 10 # 包含最近 10 条提交 repomix --include-diffs --include-logs # 同时包含 diff 与日志 # Token 计数分析 repomix --token-count-tree repomix --token-count-tree 1000 # 只显示 1000 Token 的文件/目录 # 监视模式文件变化时自动重新打包 repomix --watch repomix -w --include src/**/*.ts十三、相关资源配置指南把选项写进repomix.config.json而非 CLI 标志输出格式XML、Markdown、JSON、Plain 四种格式的细节代码压缩--compress如何借助 Tree-sitter 工作安全--no-security-check关闭了什么MCP 服务器--mcp与--sandbox的完整用法【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考