yek

一款基于 Rust 的快速工具[^1]，用于将仓库或目录中的文本文件序列化，以便供大语言模型使用。

默认情况下：

• 使用 .gitignore 规则跳过不需要的文件。
• 利用 Git 历史记录推断哪些文件更为重要。
• 自动推断额外的忽略模式（如二进制文件、大文件等）。
• 自动检测输出是否被管道重定向，并以流式方式输出内容，而非写入文件。
• 支持在单个命令中处理多个目录。
• 支持通配符模式和单独选择文件。
• 可通过 yek.yaml 配置文件进行自定义。

Yek 在波斯语中意为“一”。

假设你有一个如下简单的仓库结构：

.
├── README.md
├── src
│   ├── main.rs
│   └── utils.rs
└── tests
    └── test.rs

在该目录下运行 yek 将生成一个单独的文件，并将其写入临时目录，内容如下：

>>>> README.md
... 内容 ...
>>>> tests/test.rs
... 内容 ...
>>>> src/utils.rs
... 内容 ...
>>>> src/main.rs
... 内容 ...

[!NOTE]
yek 会优先将较重要的文件放在输出的最后。这对于大语言模型的使用非常有用，因为大语言模型通常更关注上下文中后出现的内容。

安装

请根据你的平台选择合适的安装方法：

类 Unix 系统（macOS、Linux）

curl -fsSL https://azimi.me/yek.sh | bash

适用于 Windows（PowerShell）：

irm https://azimi.me/yek.ps1 | iex

git clone https://github.com/mohsen1/yek
cd yek
cargo install --path .

使用

yek 具有合理的默认设置，你只需在目录中运行 yek 即可序列化整个仓库。它会将仓库中的所有文件序列化并写入一个临时文件，文件路径会在控制台打印出来。

示例

处理当前目录并写入临时目录：

yek

将输出通过管道复制到剪贴板（macOS）：

yek src/ | pbcopy

将最大输出大小限制为 128K 个 token：

yek --tokens 128k

[!NOTE] yek 会移除任何无法容纳在限制上下文大小内的文件，并尽量保留更重要的文件。

yek --max-size 100KB --output-dir /tmp/yek src/

处理多个目录：

yek src/ tests/

处理多个文件：

yek file1.txt file2.txt file3.txt

使用通配符模式：

yek "src/**/*.ts"

yek "src/main.rs" "tests/*.rs" "docs/README.md"

[!NOTE] 使用通配符模式时，请务必用引号括起来，以防止 shell 展开。

CLI 参考

yek --help
用法：yek [选项] [输入路径]...

参数：
  [输入路径]...                要处理的文件和/或目录

选项：
      --no-config                              不使用配置文件
      --config-file <CONFIG_FILE>              配置文件路径
  -V, --version                                打印 yek 版本信息
      --max-size <MAX_SIZE>                    每个分块的最大大小。例如：“10MB”或“128K”，或者在使用 token 计数模式时，“100”或“128K” [默认值：10MB]
      --tokens <TOKENS>                        使用 token 模式代替字节模式
      --json                                   启用 JSON 输出
      --debug                                  启用调试输出
      --line-numbers                           在输出中包含行号
      --output-dir [<OUTPUT_DIR>]              输出目录。如果未提供且标准输出是 TTY，则使用临时目录
      --output-name [<OUTPUT_NAME>]            输出文件名。如果指定，则将输出写入当前目录下的该文件
      --output-template [<OUTPUT_TEMPLATE>]    输出模板。默认为 “>>>> 文件路径\n文件内容”
      --ignore-patterns <IGNORE_PATTERNS>...  忽略模式
      --unignore-patterns <UNIGNORE_PATTERNS>... 取消忽略某些模式。yek 有一些内置的忽略模式，但你可以在这里覆盖它们。
  -t, --tree-header                            在输出中包含目录树头信息（与 JSON 输出不兼容）
      --tree-only                              只显示目录树结构（不包含文件内容，与 JSON 输出不兼容）
  -h, --help                                   打印帮助信息

CLI 选项详解

• [输入路径]... - 要处理的文件或目录。支持通配符模式（请用引号括起来以防止 shell 展开）。
• --no-config - 跳过加载任何配置文件。
• --config-file <CONFIG_FILE> - 使用指定的配置文件路径，而不是搜索默认配置文件。
• -V, --version - 打印版本信息并退出。
• --max-size <MAX_SIZE> - 每次输出的最大大小限制（例如：“10MB”、“128K”）。在字节模式下使用。
• --tokens <TOKENS> - 使用基于 token 的计数方式，而不是字节计数（例如：“128k”、“100”）。启用 token 模式。
• --json - 将结果以 JSON 格式输出，而不是文本格式。
• --debug - 启用调试日志以进行故障排除。
• --line-numbers - 在每个文件的输出中包含行号。
• --output-dir [<OUTPUT_DIR>] - 用于写入输出文件的目录。如果未指定且未进行流式输出，则使用临时目录。
• --output-name [<OUTPUT_NAME>] - 指定输出文件名。如果指定，则会将输出写入当前目录下的该文件。
• --output-template [<OUTPUT_TEMPLATE>] - 用于格式化输出的模板。可以使用 FILE_PATH 和 FILE_CONTENT 占位符。
• --ignore-patterns <IGNORE_PATTERNS>... - 额外的忽略模式（扩展 .gitignore 和默认规则）。
• --unignore-patterns <UNIGNORE_PATTERNS>... - 用于覆盖内置忽略规则的模式。
• -t, --tree-header - 在输出开头包含目录树结构（与 JSON 不兼容）。
• --tree-only - 只显示目录树结构，不包含文件内容（与 JSON 不兼容）。

配置文件

你可以在项目根目录下放置名为 yek.yaml 的文件，或者通过 --config-file 参数指定自定义路径。配置文件允许你：

1. 添加自定义的忽略模式。
2. 定义文件优先级规则以控制处理顺序。
3. 添加额外的二进制文件扩展名以进行忽略（扩展内置列表）。
4. 配置基于 Git 的优先级提升机制。
5. 定义输出目录和输出文件名。
6. 定义输出模板及其他输出选项。

可配置选项

大多数 CLI 选项都可以在配置文件中进行配置。以下选项可以设置：

文件处理：

• max_size - 大小限制（与 --max-size 相同）
• tokens - 令牌数量限制（与 --tokens 相同）
• ignore_patterns - 额外的忽略模式（与 --ignore-patterns 相同）
• unignore_patterns - 覆盖内置的忽略规则（与 --unignore-patterns 相同）

输出配置：

• json - 启用 JSON 输出（与 --json 相同）
• debug - 启用调试模式（与 --debug 相同）
• line_numbers - 包含行号（与 --line-numbers 相同）
• output_dir - 输出目录（与 --output-dir 相同）
• output_name - 输出文件名（与 --output-name 相同）
• output_template - 输出模板（与 --output-template 相同）
• tree_header - 包含目录树标题（与 --tree-header 相同）
• tree_only - 仅显示目录树（与 --tree-only 相同）

仅限配置的选项：

• priority_rules - 文件优先级规则（仅限配置文件）
• binary_extensions - 额外的二进制文件扩展名（仅限配置文件）
• git_boost_max - 基于 Git 的最大优先级提升值（仅限配置文件）

[!NOTE] 某些 CLI 选项，如 --no-config、--config-file 和 --version，仅适用于命令行，无法在配置文件中设置。

示例 yek.yaml

你也可以使用 yek.toml 或 yek.json 替代 yek.yaml。

这是可选的，你可以在项目的根目录下配置 yek.yaml 文件。

# 添加额外的忽略模式（除了 .gitignore）
ignore_patterns:
  - "ai-prompts/**"
  - "__generated__/**"

# 配置基于 Git 的优先级提升（可选）
git_boost_max: 50 # 根据 Git 历史的最大分数提升值（默认：100）

# 定义处理顺序的优先级规则
# 分数越高，越先被处理
priority_rules:
  - score: 100
    pattern: "^src/lib/"
  - score: 90
    pattern: "^src/"
  - score: 80
    pattern: "^docs/"

# 添加额外的二进制文件扩展名以供忽略
# 这些扩展名会扩展内置列表（.jpg、.png、.exe 等）
binary_extensions:
  - ".blend" # Blender 文件
  - ".fbx" # 3D 模型文件
  - ".max" # 3ds Max 文件
  - ".psd" # Photoshop 文件

# 输出配置
max_size: "128K"           # 大小限制（也可使用 tokens: "100k"）
json: false                # 启用 JSON 输出
debug: false               # 启用调试日志
line_numbers: false        # 在输出中包含行号
tree_header: false         # 在开头包含目录树

# 定义输出目录
output_dir: /tmp/yek

# 定义输出文件名（将写入当前目录并以此命名）
output_name: yek-output.txt

# 定义输出模板。
# 模板中应包含 FILE_PATH 和 FILE_CONTENT。
output_template: "FILE_PATH\n\nFILE_CONTENT"

性能

yek 非常快速。它使用 Rust 编写，并通过并行处理来加速任务。

以下是将其与 Repomix 对比的基准测试，两者都对 Next.js 项目进行了序列化：

time yek
执行时间    5.19 秒    fish           外部
   用户时间    2.85 秒   54.00 微秒    2.85 秒
   系统时间    6.31 秒  629.00 微秒    6.31 秒

time repomix
执行时间   22.24 分钟    fish           外部
   用户时间   21.99 分钟    0.18 毫秒   21.99 分钟
   系统时间    0.23 分钟    1.72 毫秒    0.23 分钟

yek 比 repomix 快 230 倍。

路线图

请参阅 拟议的功能。我欢迎新的功能请求。请提交详细提案以讨论新功能。

替代方案

• Repomix：一款工具，可将仓库序列化为单个文件，方式与 yek 类似。
• Aider：一款使用 AI 的全功能 IDE 式编码体验

许可证

MIT

[^1]: yek 并非“极速”运行。它只是足够快，具体速度取决于你的计算机性能。

yek 快速上手指南

yek 是一个基于 Rust 开发的高性能工具，专为将代码仓库或目录中的文本文件序列化为单个文件而设计，旨在优化大语言模型（LLM）的上下文输入。它默认遵循 .gitignore 规则，利用 Git 历史智能排序文件重要性，并支持流式输出。

环境准备

• 操作系统：macOS、Linux 或 Windows (PowerShell)
• 前置依赖：
  • 无需额外依赖，二进制文件开箱即用。
  • 若选择从源码编译，需安装 Rust (cargo)。
• 网络要求：安装脚本需要访问互联网下载最新释放版本。

安装步骤

根据你的操作系统选择以下一种方式进行安装：

macOS / Linux

使用官方一键安装脚本：

curl -fsSL https://azimi.me/yek.sh | bash

Windows (PowerShell)

使用 PowerShell 一键安装脚本：

irm https://azimi.me/yek.ps1 | iex

从源码编译 (可选)

如果你希望构建最新版本或使用自定义配置：

git clone https://github.com/mohsen1/yek
cd yek
cargo install --path .

基本使用

yek 设计了合理的默认值，通常只需一条命令即可开始工作。

1. 序列化当前目录

在当前项目根目录运行以下命令，yek 会自动识别文件、忽略无关内容，并将结果写入临时文件，同时在终端打印该文件路径：

yek

2. 指定目录或文件

你可以处理特定目录或多个文件：

# 处理 src 目录
yek src/

# 处理多个目录
yek src/ tests/

# 处理特定文件
yek file1.txt file2.rs

3. 配合管道使用 (推荐)

直接将输出传递给剪贴板或其他工具，无需生成中间文件：

# macOS: 直接复制到剪贴板
yek src/ | pbcopy

# Linux (需安装 xclip/xsel): 复制到剪贴板
yek src/ | xclip -selection clipboard

4. 限制输出大小 (适配 LLM 上下文)

通过 Token 数或文件大小限制输出，yek 会优先保留重要文件：

# 限制为 128k tokens
yek --tokens 128k

# 限制为 100KB
yek --max-size 100KB

5. 查看目录结构

仅预览将被处理的文件树结构，不包含具体内容：

yek --tree-only

提示：yek 会根据 Git 提交历史自动调整文件顺序，将更重要的文件放在输出内容的末尾，以便 LLM 更好地关注核心逻辑。