# ravel

**Repository Path**: Mr_Chippy/ravel

## Basic Information

- **Project Name**: ravel
- **Description**: a rust-made file flatten tool
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-20
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ravel

`ravel` 是一个用 Rust 编写的命令行工具，用来把一个代码仓库扁平化成**一份适合 AI 阅读的单文件**。

它会：

- 遍历指定目录下的所有源文件；
- 自动跳过二进制文件和超大文件；
- 为每个文件生成一个 **UUID**，并输出一个索引（INDEX）；
- 按统一格式输出每个文件的完整内容（CONTEXT）；
- 在文件开头给出一段说明，告诉 AI 这份「代码包」的结构和使用方式。

这样，你只需要把这一个输出文件贴给大模型，就可以在对话里用路径精确引用任意文件，而模型可以用索引快速定位对应内容，降低上下文压力。

---

## 功能特性

- ✅ **多命令模式**
    - `all` / `flat`：索引 + 内容 一起输出。
    - `idx`：只输出索引（文件列表）。
    - `context` / `ctx`：只输出文件内容块。

- ✅ **自动过滤噪音文件**
    - 在构建树时检测是否为「二进制文件」：
        - 读取前 4KB，包含 NUL 字节或控制字符比例过高时视为二进制。
    - 根据 `--max-file-size` 跳过超大文件。
    - 如果一个目录下所有文件都是「二进制或超大文件」，整个子树会被剪掉。

- ✅ **统一的索引格式（INDEX）**
    - 每个文件一行：`/path/to/file.rs->[uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]`
    - 不输出中间目录行，减少噪音。

- ✅ **统一的内容格式（CONTEXT）**
    - 每个文件都有一个内容块：
      ```text
      @@@@FILE START@@@@-PATH=/path/to/file.rs&&UUID=...
      <文件原始内容>
      @@@@FILE END@@@@-PATH=/path/to/file.rs&&UUID=...
      ```
    - 上下文区域被 `$$$CONTEXT-START$$$` / `$$$CONTEXT-END$$$` 包裹。

- ✅ **专为 AI 设计的头部说明**
    - 生成的文件开头自动附带一段 `Dev:` 说明，告诉 AI：
        - 索引区在哪；
        - 正文区在哪；
        - 如何通过 PATH + UUID 在 CONTEXT 中定位目标文件。

---

## 安装

### 从源代码构建

```bash
git clone https://github.com/yourname/ravel.git
cd ravel
cargo build --release
```

构建完成后，可执行程序通常位于：

```bash
target/release/ravel
```

你可以把它加到`PATH`，或者直接用绝对路径调用。

## 基本使用

### 1.输出索引+内容

```Bash
# 在当前目录运行
ravel all

# 或者指定目录（例如 src）
ravel src all

```

会在标准输出打印：

1. 头部说明（给 AI 的 Dev 提示）；
2. 索引区（INDEX）；
3. 正文区（CONTEXT）。

你可以：

直接把整个输出重定向到文件，例如：

```Bash

ravel all . > bundle.txt

```

### 2.只看索引

```Bash
ravel idx .
```

输出类似于：

```Text
$$$$INDEX-START$$$$

/src/main.rs->[uuid=19a2b6b0-0e25-4d52-b7f8-1fd5058cd222]
/src/lib.rs->[uuid=9e7c1f1e-3e11-4e3c-b673-9c7dfb28a333]

$$$$INDEX-END$$$$
```

适合快速了解项目有哪些文件。

### 3.只输出内容

```Bash
ravel context .
# 或
ravel ctx .
```

仅输出 CONTEXT 部分（不包含 INDEX 和 Dev 说明）。

## 命令行参数

### 顶层结构

```shell

ravel <COMMAND> [INPUT_DIR] [OPTIONS]

```

+ `COMMAND`：
    + `all`：索引 + 内容。
    + `idx`：只索引。
    + `context` / `ctx`：只内容。
+ `INPUT_DIR`：要展开的目录，默认为当前目录 `.`。

仅输出 CONTEXT 部分（不包含 INDEX 和 Dev 说明）。

### 通用扫描选项（ScanOptions）

+ `-i, --include-exts "rs,toml"`只输出指定扩展名的文件（内部会自动转小写并去掉前导 `.`）。
+ `-e, --exclude-exts "log,tmp"`排除指定扩展名的文件。
+ `-m, --max-file-size 1048576` 单位为字节，例如`1048576`表示 1MB。超过此大小的文件会在构建树时被剪掉。

注意：`-i` 与 `-e`互斥，只能用一个。

## 输出示例

```Text
Dev:
This file is a codebase bundle generated by `ravel`.

Structure:
- INDEX: between $$$$INDEX-START$$$$ and $$$$INDEX-END$$$$.
  Each line: /path/to/file.rs->[uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]
- CONTEXT: between $$$CONTEXT-START$$$ and $$$CONTEXT-END$$$.
  Each file block:
    @@@@FILE START@@@@-PATH=/path/to/file.rs&&UUID=...
    <original file content>
    @@@@FILE END@@@@-PATH=/path/to/file.rs&&UUID=...

For AI assistants:
- When the user mentions a file (e.g. "src/main.rs"), first find its line in INDEX and read the UUID.
- Then, in CONTEXT, read only the block between the matching FILE START/END markers for that PATH and UUID.
- Use only the relevant blocks to answer questions; you do not need to load the entire bundle at once.

$$$$INDEX-START$$$$

/src/main.rs->[uuid=19a2b6b0-0e25-4d52-b7f8-1fd5058cd222]
/src/lib.rs->[uuid=9e7c1f1e-3e11-4e3c-b673-9c7dfb28a333]

$$$$INDEX-END$$$$

$$$CONTEXT-START$$$

@@@@FILE START@@@@-PATH=/src/main.rs&&UUID=19a2b6b0-0e25-4d52-b7f8-1fd5058cd222
fn main() {
    println!("Hello, ravel!");
}
@@@@FILE END@@@@-PATH=/src/main.rs&&UUID=19a2b6b0-0e25-4d52-b7f8-1fd5058cd222

@@@@FILE START@@@@-PATH=/src/lib.rs&&UUID=9e7c1f1e-3e11-4e3c-b673-9c7dfb28a333
pub fn greet(name: &str) {
    println!("Hello, {name}!");
}
@@@@FILE END@@@@-PATH=/src/lib.rs&&UUID=9e7c1f1e-3e11-4e3c-b673-9c7dfb28a333

$$$CONTEXT-END$$$

```

## TODO

+ 暂不解析 `.gitignore` / `.ignore` 等规则；

+ 暂不自动忽略 `target/`、`node_modules/` 等目录（可以后续加选项或默认规则）；

+ 二进制判断基于简单启发式，极端情况下可能误判（可后续考虑引入专用 crate 改进）。