跳转到内容
vibe

.vibe.toml

.vibe.toml 文件包含共享配置，通常会提交到 git 并与团队成员共享。

Copy 配置

Section titled “Copy 配置”

文件

Section titled “文件”

将源仓库中的单个文件复制到 worktree：

[copy]
files = [".env", "config.json"]

Glob 模式

Section titled “Glob 模式”

files 数组支持 glob 模式，可以灵活地选择文件：

[copy]
files = [
  "*.env",              # 根目录下的所有 .env 文件
  "**/*.json",          # 所有 JSON 文件（递归）
  "config/*.txt",       # config/ 下的所有 .txt 文件
  ".env.production"     # 精确路径依然可用
]

支持的模式：

模式 说明
* 匹配除 / 以外的任意字符
** 匹配包含 / 的任意字符（递归）
? 匹配任意单个字符
[abc] 匹配方括号内的任意字符

目录 v0.4.0+

Section titled “目录 ”

递归复制整个目录：

[copy]
dirs = [
  "node_modules",      # 精确的目录路径
  ".cache",            # 隐藏目录
  "packages/*"         # 匹配多个目录的 Glob 模式
]

共享目录（symlink） v3.1.0+

Section titled “共享目录（symlink） ”

除了把目录复制到每个工作树，也可以用符号链接指向源仓库中的目录来共享它：

[copy]
dirs = ["node_modules"]
symlink = [".cache", ".turbo"]

原因： 在 APFS/Btrfs/XFS 上写时复制（CoW）克隆让 dirs 很快，但在不支持 reflink 的文件系统（以及 Windows）上，完整复制庞大的依赖或缓存目录既慢又浪费 磁盘空间。有些目录本来也不需要按工作树隔离——共享的构建缓存或下载缓存反而更好。

规则：

  • 条目是相对于仓库根目录的精确目录路径。不支持 Glob 模式（一个符号链接只指向 一个要共享的目录）。
  • 实际创建了链接的 symlink 条目优先于覆盖同一路径的任何其他复制来源—— 既包括 files/dirs 条目，也包括由 untracked 或 modified 收集到的文件。 该路径会被链接而不是被复制。该判定在 glob 展开之后进行，因此即使 symlink = [".cache"] 与 dirs = [".*"] 同时存在，.cache 仍然会被链接， 只有其他匹配项会被复制。共享目录下层的路径（及其父目录）同样会被排除， 因此复制绝不会穿过链接写入源仓库。在不区分大小写的文件系统（APFS、NTFS）上， .Cache 与 .cache 是同一个目录条目，因此排除判定也会忽略大小写。
  • 目标必须存在于源仓库中且不能越出仓库范围。目标不存在、路径逃逸出仓库，或者操作 系统拒绝创建链接（未开启开发者模式的 Windows）时会打印警告并继续执行 vibe start——工作树仍然可用。此时并没有创建链接，因此指向同一路径的 files/dirs 条目仍会照常复制。
  • 工作树中该路径上已存在的真实文件或目录不会被替换；只有过期的符号链接会被刷新。
  • vibe clean 只删除链接，绝不删除它指向的目录。

并发数 v0.17.0+

Section titled “并发数 ”

控制并行执行的目录复制操作数量：

[copy]
concurrency = 8
  • 默认值：4
  • 取值范围：1 到 32
  • 在存储速度较快的系统（NVMe、SSD）上，提高该值可以加快复制
  • 降低该值可以减少系统资源占用

通过环境变量覆盖：

Terminal window
VIBE_COPY_CONCURRENCY=16 vibe start feat/my-feature

环境变量的优先级高于配置文件中的设置。

复制性能优化 v0.4.0+

Section titled “复制性能优化 ”

vibe 会根据你的系统自动选择最佳的复制策略：

策略 使用场景 平台
Clone (CoW) APFS 上的目录复制 macOS
Clone (reflink) Btrfs/XFS 上的目录复制 Linux
rsync 无法使用 clone 时的目录复制 macOS/Linux
robocopy (/MT) 目录复制 Windows
Standard 文件复制，或作为兜底方案 全部

工作原理：

  • 文件复制：始终使用原生的 copyFile()，以获得最佳的单文件性能
  • 目录复制：自动使用当前可用的最快方式

优势：

  • Copy-on-Write 只复制元数据而非实际数据，因此速度极快
  • 无需配置 - 最佳策略会被自动检测
  • 自动回退机制确保复制始终可用

钩子配置

Section titled “钩子配置”

关于 pre/post 钩子的配置细节，请参阅钩子。

子模块配置

Section titled “子模块配置”

在 worktree 创建之后、父仓库的 pre_start 钩子执行之前，加载所选直接子模块中已信任的 .vibe.toml 文件：

[submodules]
configs = ["libs/foo", "vendor/bar"]
  • 默认值：[]
  • 每一项都必须与 .gitmodules 中某个直接子模块的路径完全匹配
  • 会在新的 worktree 中执行 git submodule update --init -- <paths>
  • 使用各子模块自身的 trust entry 加载其 .vibe.toml / .vibe.local.toml
  • 子模块配置中的钩子和 copy 规则会以子模块根目录为基准解析路径并执行
  • --no-hooks 会跳过子模块的钩子，但不会跳过子模块的初始化
  • --no-copy 会跳过子模块的 copy 规则
  • 子模块更新、trust、路径校验或 setup 失败都会中断 vibe start，已创建的 worktree 会保留下来以便排查

Worktree 配置 v0.6.0+

Section titled “Worktree 配置 ”

使用外部脚本自定义 worktree 的目录路径。

path_script

Section titled “path_script”

指定一个输出 worktree 路径的脚本：

[worktree]
path_script = "~/.config/vibe/worktree-path.sh"

脚本会接收到以下环境变量：

变量 说明 示例
VIBE_REPO_NAME 仓库名称 my-project
VIBE_BRANCH_NAME 分支名称 feat/new-feature
VIBE_SANITIZED_BRANCH 净化后的分支名称（/ → -） feat-new-feature
VIBE_REPO_ROOT 仓库根目录路径 /path/to/repo

脚本示例：

~/.config/vibe/worktree-path.sh
#!/bin/bash
echo "${HOME}/worktrees/${VIBE_REPO_NAME}-${VIBE_SANITIZED_BRANCH}"

完整示例

Section titled “完整示例”
[copy]
files = [
  ".env",
  ".env.local",
  "**/*.secret"
]
dirs = [
  "node_modules",
  ".cache",
  "vendor"
]
concurrency = 8


[hooks]
pre_start = ["echo '正在准备 worktree...'"]
post_start = [
  "pnpm install",
  "pnpm db:migrate",
  "pnpm build"
]
pre_clean = ["git stash"]
post_clean = ["echo '清理完成'"]


[submodules]
configs = ["libs/foo"]


[worktree]
path_script = "~/.config/vibe/worktree-path.sh"