CodeWeaver：从你的代码库生成 Markdown 文档

CodeWeaver 是一款命令行工具，可将你的代码库转换为一个单一、可导航的 Markdown 文档。它会递归扫描指定目录，创建项目文件结构的树状表示，并将每个文件的内容嵌入到 Markdown 代码块中。通过提供整合且易读的 Markdown 输出，这简化了代码库的共享、文档化以及与 AI/ML 工具的集成。

当前仓库的输出可以在这里找到 here。

核心特性

• 全面的代码库文档： 生成一个 Markdown 文件，以清晰的树状格式概述项目的目录和文件结构。
• 包含代码内容： 将每个文件的完整内容嵌入到 Markdown 文档中，并根据文件扩展名使用代码块。
• 灵活的路径过滤： 使用正则表达式定义 include 和/或 ignore 模式，让你精确控制哪些文件会被包含。
• 可选路径记录： 将包含和排除的文件路径列表分别保存到单独的文件中，以便进行详细跟踪。
• 剪贴板集成： 可选择将生成的 Markdown 复制到剪贴板，方便粘贴。
• 简洁的 CLI： 直观易用的命令行界面。

安装

使用 go install（推荐）：

需要 Go 1.18 或更高版本。

go install github.com/tesserato/CodeWeaver@latest

安装特定版本：

go install github.com/tesserato/CodeWeaver@vX.Y.Z  # 将 X.Y.Z 替换为所需版本

从预编译的可执行文件：

从 发布页面 下载适用于你操作系统的相应可执行文件。

下载后，赋予可执行权限：

chmod +x codeweaver  # 在 Linux/macOS 上

使用方法

codeweaver [选项]

获取帮助：

codeweaver -h

选项：

选项	描述	默认值
-input <directory>	要扫描的根目录。	.（当前目录）
-output <filename>	输出 Markdown 文件的名称。	codebase.md
-ignore "<regex patterns>"	用于排除路径的逗号分隔的正则表达式列表。例如：\.git.*,node_modules,*.log	\.git.*
-include "<regex patterns>"	逗号分隔的正则表达式列表。仅匹配这些模式的路径会被包含。例如：\.go$,\.md$	无
-included-paths-file <filename>	将包含的路径列表保存到此文件。	无
-excluded-paths-file <filename>	将排除的路径列表保存到此文件。	无
-clipboard	将生成的 Markdown 复制到剪贴板。	false
-version	显示版本并退出。
-help	显示此帮助信息并退出。

理解 -include 和 -ignore

这些标志控制哪些文件和目录会被包含在生成的文档中。

• -ignore（黑名单）： 排除匹配任何给定正则表达式的文件/目录。
• -include（白名单）： 仅包含匹配至少一个给定正则表达式的文件/目录。如果使用了 -include，默认情况下其他所有内容都会被排除。

行为表：

-ignore	-include	行为
无	无	包含所有文件/目录，但不包括输入目录本身（.）。
是	无	排除匹配 -ignore 的文件/目录；包含其余所有内容。
无	是	仅包含匹配 -include 的文件/目录。其余所有内容都被排除。
是	是	包含同时满足至少一个 -include 模式且不匹配任何 -ignore 模式的文件/目录。-include 创建白名单，而 -ignore 则对其进行过滤。

示例

1. 基本用法：

codeweaver

在当前目录下创建 codebase.md，记录代码库的结构和内容（排除与默认忽略模式 \.git.* 匹配的路径）。

2. 自定义输入输出：

codeweaver -input=my_project -output=project_docs.md

处理 my_project 目录，并将输出保存到 project_docs.md 文件中。

3. 忽略特定文件/目录：

codeweaver -ignore="\.log,temp,build"

排除名为 .log、temp 或 build 的文件或目录。

4. 仅包含特定类型的文件：

codeweaver -include="\.go$,\.md$"

仅包含 Go（.go）和 Markdown（.md）文件。

5. 结合 include 和 ignore：

codeweaver -include="\.go$,\.md$" -ignore="vendor,test"

包含 Go 和 Markdown 文件，但排除路径中包含 vendor 或 test 的文件。

6. 保存包含与排除的路径：

codeweaver -ignore="node_modules" -included-paths-file=included.txt -excluded-paths-file=excluded.txt

生成 codebase.md，并将包含的路径保存到 included.txt，排除的路径保存到 excluded.txt。

7. 复制到剪贴板：

codeweaver -clipboard

生成 codebase.md 并将其内容复制到剪贴板。

8. 正则表达式示例：

• .：匹配任意单个字符。
• *：匹配前面字符出现零次或多次。
• +：匹配前面字符出现一次或多次。
• ?：匹配前面字符出现零次或一次。
• [abc]：匹配方括号内的任意一个字符。
• [^abc]：匹配不在方括号内的任意字符。
• [a-z]：匹配 a 到 z 范围内的任意字符。
• ^：匹配字符串的开头。
• $：匹配字符串的结尾。
• \.：匹配字面意义上的点（.）。由于 . 在正则表达式中有特殊含义，因此需要转义。
• \|：用于选择（OR）。例如，a\|b 匹配 “a” 或 “b”。
• .*\.py[cod]$：匹配以 pyc、pyd 或 pyo 结尾的 Python 文件。
• .*\.pdf：匹配 PDF 文件。
• (dir1\|dir2)：匹配 dir1 或 dir2。

9. 完整示例：

codeweaver -input=. -output=codebase.md -ignore="\.git.*,.+\.exe,codebase.md,excluded_paths.txt" -include="\.go$,\.md$,\.ps1$,\.yaml$,\.txt$,\.csv$" -excluded-paths-file="excluded_paths.txt" -clipboard

该命令将：

• 处理当前目录（.）。
• 生成文档并保存到 codebase.md。
• 排除与 .git.*、.+\.exe、输出文件（codebase.md）以及保存排除路径的文件匹配的文件。
• 仅包含扩展名为 .go、.md、.ps1、.yaml、.txt 和 .csv 的文件。
• 将排除的文件列表保存到名为 excluded_paths.txt 的文件中。
• 将生成的 Markdown 内容复制到系统剪贴板。

贡献

欢迎贡献！请在项目的 GitHub 仓库中提交问题或拉取请求。

许可证

CodeWeaver 根据 MIT 许可证 发布。

星标历史

替代方案

本节列出了功能相似或重叠的工具。

GitHub 仓库

项目	星标
ai-context
bundle-codebases
code2prompt
code2text
codefetch
copcon
describe
feed-llm
files-to-prompt
ggrab
gitingest
gitpodcast
globcat.sh
grimoire
llmcat
RepoMix
RepoMix
techdocs
thisismy
yek
your-source-to-prompt
ingest
onefilellm
repo2file
clipsource

其他工具

• r2md： 一个 Rust 库（https://crates.io/crates/r2md）。
• repo2txt： 一个基于网页的工具（https://chathub.gg/repo2txt 和 https://repo2txt.simplebasedomain.com/local.html）。
• repoprompt： 一个网络服务（https://www.repoprompt.com）。

VSCode 扩展

• 代码库转 Markdown：（https://marketplace.visualstudio.com/items?itemName=DVYIO.combine-open-files）

CodeWeaver 快速上手指南

CodeWeaver 是一款命令行工具，可将代码库递归扫描并转换为单个可导航的 Markdown 文档。它非常适合用于代码分享、生成文档或为 AI/ML 工具提供上下文。

环境准备

• 操作系统：支持 Linux、macOS 和 Windows。
• 前置依赖：
  • 方案 A（推荐）：已安装 Go 1.18 或更高版本。
  • 方案 B：若无 Go 环境，可直接下载预编译的可执行文件。

安装步骤

方式一：使用 Go 安装（推荐）

如果你已配置好 Go 环境，运行以下命令即可自动下载并安装最新版本的 codeweaver：

go install github.com/tesserato/CodeWeaver@latest

如需安装特定版本，请将 @latest 替换为版本号（例如 @v1.0.0）：

go install github.com/tesserato/CodeWeaver@vX.Y.Z

注意：安装完成后，请确保 $GOPATH/bin 已添加到你的系统环境变量 PATH 中，以便在任意目录运行命令。

方式二：下载预编译文件

1. 访问 Releases 页面 下载对应你操作系统的二进制文件。
2. （Linux/macOS）赋予执行权限：

chmod +x codeweaver

3. 将文件移动到系统路径（如 /usr/local/bin）或直接在该目录下使用。

基本使用

1. 最简单用法

在当前项目根目录下运行以下命令，将自动生成名为 codebase.md 的文件，包含当前目录的文件树结构及所有文件内容（默认排除 .git 等目录）：

codeweaver

2. 指定输入与输出

扫描指定目录并保存为自定义文件名：

codeweaver -input=my_project -output=project_docs.md

3. 常用场景示例

• 仅包含特定类型文件（例如只处理 Go 和 Markdown 文件）：

  codeweaver -include="\.go$,\.md$"
  

• 排除特定目录或文件（例如排除日志和构建目录）：

  codeweaver -ignore="\.log,temp,build"
  

• 生成文档并直接复制到剪贴板：

  codeweaver -clipboard
  

• 查看帮助信息：

  codeweaver -h